Tool
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Tool
io/agentscope/core/tool/Tool.java:57–225用于标记工具相关元数据的注解。位于 io.agentscope.core.tool 包。核心成员包括 name、description、strict、readOnly、concurrencySafe、externalTool。
Annotation to mark a method as a tool that can be invoked by AI agents.
Methods annotated with @Tool are automatically registered with the toolkit and made
available to agents for execution. The toolkit uses reflection to discover tool methods and
generate appropriate JSON schemas for LLM consumption.
Usage Example:
`public class WeatherTools {
@Tool(name = "get_weather", description = "Get current weather for a city")
public String getWeather(
@ToolParam(name = "city", description = "City name") String city,
@ToolParam(name = "unit", description = "Temperature unit") String unit) {
// Implementation
return "Weather data...";
}
}
`
Requirements:
-
All parameters must be annotated with
ToolParam(exceptToolEmitter) -
Return type must be String, Mono<String>, or other reactive types
-
Tool names should follow snake_case convention for LLM compatibility
-
Descriptions should clearly explain what the tool does and when to use it
注解元素摘要Annotation Element Summary
| 元素Element | 类型Type | 默认值Default | 说明Description |
|---|---|---|---|
name | String | "" | 工具的名称。 The name of the tool. |
description | String | "" | 返回 `description` 结果。 The description of the tool that explains its purpose and usage. |
strict | boolean | false | 返回 `strict` 结果。 Whether to enable strict schema mode for this tool. |
readOnly | boolean | false | 返回 `readOnly` 结果。 Whether the tool only reads data without observable side effects. |
concurrencySafe | boolean | true | 返回 `concurrencySafe` 结果。 Whether the tool is safe to invoke concurrently with itself. |
externalTool | boolean | false | 返回外部工具。 Whether the tool is executed outside the framework. |
stateInjected | boolean | false | 返回 `stateInjected` 结果。 Whether the tool requires the agent state to be injected at call time. |
returnDirect | boolean | false | 返回 `returnDirect` 结果。 Whether to return this tool's result directly to the caller as the turn's final
assistant message, bypassing the next model reasoning iteration. |
dangerousFiles | String[] | {} | 返回 `dangerousFiles` 结果。 Sensitive filenames that must require explicit permission for this tool. |
dangerousDirectories | String[] | {} | 返回 `dangerousDirectories` 结果。 Sensitive directory names whose presence in any path segment marks the path dangerous. |
converter | Class<? extends ToolResultConverter> | DefaultToolResultConverter.class | 用于此工具的自定义结果转换器。 Custom result converter for this tool. |
注解元素详情Annotation Element Detail
name
public String name()
工具的名称。
The name of the tool.
Stringio/agentscope/core/tool/Tool.java:70description
public String description()
返回 description 结果。
The description of the tool that explains its purpose and usage.
Stringio/agentscope/core/tool/Tool.java:87strict
public boolean strict()
返回 strict 结果。
Whether to enable strict schema mode for this tool.
booleanio/agentscope/core/tool/Tool.java:97readOnly
public boolean readOnly()
返回 readOnly 结果。
Whether the tool only reads data without observable side effects.
booleanio/agentscope/core/tool/Tool.java:107concurrencySafe
public boolean concurrencySafe()
返回 concurrencySafe 结果。
Whether the tool is safe to invoke concurrently with itself.
booleanio/agentscope/core/tool/Tool.java:117externalTool
public boolean externalTool()
返回外部工具。
Whether the tool is executed outside the framework.
booleanio/agentscope/core/tool/Tool.java:127stateInjected
public boolean stateInjected()
返回 stateInjected 结果。
Whether the tool requires the agent state to be injected at call time.
booleanio/agentscope/core/tool/Tool.java:138returnDirect
public boolean returnDirect()
返回 returnDirect 结果。
Whether to return this tool's result directly to the caller as the turn's final assistant message, bypassing the next model reasoning iteration.
booleanio/agentscope/core/tool/Tool.java:171dangerousFiles
public String[] dangerousFiles()
返回 dangerousFiles 结果。
Sensitive filenames that must require explicit permission for this tool.
String[]io/agentscope/core/tool/Tool.java:180dangerousDirectories
public String[] dangerousDirectories()
返回 dangerousDirectories 结果。
Sensitive directory names whose presence in any path segment marks the path dangerous.
String[]io/agentscope/core/tool/Tool.java:189converter
public Class<? extends ToolResultConverter> converter()
用于此工具的自定义结果转换器。
Custom result converter for this tool.
Class<? extends ToolResultConverter>io/agentscope/core/tool/Tool.java:224