AS AgentScopeAPI 手册 / API Reference
注解annotation io.agentscope.core.tool 2.x

Tool

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Tool
源码Source 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 (except ToolEmitter)

  • 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
nameString""
工具的名称。
The name of the tool.
descriptionString""
返回 `description` 结果。
The description of the tool that explains its purpose and usage.
strictbooleanfalse
返回 `strict` 结果。
Whether to enable strict schema mode for this tool.
readOnlybooleanfalse
返回 `readOnly` 结果。
Whether the tool only reads data without observable side effects.
concurrencySafebooleantrue
返回 `concurrencySafe` 结果。
Whether the tool is safe to invoke concurrently with itself.
externalToolbooleanfalse
返回外部工具。
Whether the tool is executed outside the framework.
stateInjectedbooleanfalse
返回 `stateInjected` 结果。
Whether the tool requires the agent state to be injected at call time.
returnDirectbooleanfalse
返回 `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.
dangerousFilesString[]{}
返回 `dangerousFiles` 结果。
Sensitive filenames that must require explicit permission for this tool.
dangerousDirectoriesString[]{}
返回 `dangerousDirectories` 结果。
Sensitive directory names whose presence in any path segment marks the path dangerous.
converterClass<? extends ToolResultConverter>DefaultToolResultConverter.class
用于此工具的自定义结果转换器。
Custom result converter for this tool.

注解元素详情Annotation Element Detail

name

public String name()

工具的名称。

The name of the tool.

返回Returns String
返回字符串结果。The tool name, or empty string to use method name
源码Source io/agentscope/core/tool/Tool.java:70

description

public String description()

返回 description 结果。

The description of the tool that explains its purpose and usage.

返回Returns String
返回字符串结果。The tool description, or empty string to auto-generate
源码Source io/agentscope/core/tool/Tool.java:87

strict

public boolean strict()

返回 strict 结果。

Whether to enable strict schema mode for this tool.

返回Returns boolean
返回布尔值,表示判断结果。true to enable strict mode for this tool
源码Source io/agentscope/core/tool/Tool.java:97

readOnly

public boolean readOnly()

返回 readOnly 结果。

Whether the tool only reads data without observable side effects.

返回Returns boolean
返回布尔值,表示判断结果。true if this tool performs no mutation
源码Source io/agentscope/core/tool/Tool.java:107

concurrencySafe

public boolean concurrencySafe()

返回 concurrencySafe 结果。

Whether the tool is safe to invoke concurrently with itself.

返回Returns boolean
返回布尔值,表示判断结果。true if multiple invocations may run in parallel without coordination
源码Source io/agentscope/core/tool/Tool.java:117

externalTool

public boolean externalTool()

返回外部工具。

Whether the tool is executed outside the framework.

返回Returns boolean
返回布尔值,表示判断结果。true if this tool should be surfaced as a suspended call
源码Source io/agentscope/core/tool/Tool.java:127

stateInjected

public boolean stateInjected()

返回 stateInjected 结果。

Whether the tool requires the agent state to be injected at call time.

返回Returns boolean
返回布尔值,表示判断结果。true if the tool method consumes the agent state
源码Source io/agentscope/core/tool/Tool.java:138

returnDirect

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.

返回Returns boolean
返回布尔值,表示判断结果。true to short-circuit the ReAct loop after execution
源码Source io/agentscope/core/tool/Tool.java:171

dangerousFiles

public String[] dangerousFiles()

返回 dangerousFiles 结果。

Sensitive filenames that must require explicit permission for this tool.

返回Returns String[]
返回String[]。additional dangerous filenames; empty means use defaults
源码Source io/agentscope/core/tool/Tool.java:180

dangerousDirectories

public String[] dangerousDirectories()

返回 dangerousDirectories 结果。

Sensitive directory names whose presence in any path segment marks the path dangerous.

返回Returns String[]
返回String[]。additional dangerous directory names; empty means use defaults
源码Source io/agentscope/core/tool/Tool.java:189

converter

public Class<? extends ToolResultConverter> converter()

用于此工具的自定义结果转换器。

Custom result converter for this tool.

返回Returns Class<? extends ToolResultConverter>
转换器。Converter class
源码Source io/agentscope/core/tool/Tool.java:224
基于官方固定版本源码静态生成Generated from pinned official sources · Python 2.0.11 · Java 2.0.4
签名与文档为静态抽取;如有疑问请以源码为准。Signatures and docs are extracted statically; verify against the source when in doubt.