程序包 io.agentscope.core.tool

批注接口 Tool

@Target({METHOD,ANNOTATION_TYPE}) @Retention(RUNTIME) @Documented public @interface Tool
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
另请参阅:

  • 可选元素概要

    可选元素
    修饰符和类型
    可选元素
    说明
    boolean
    concurrencySafe
    Whether the tool is safe to invoke concurrently with itself.
    Class<? extends ToolResultConverter>
    converter
    Custom result converter for this tool.
    String[]
    dangerousDirectories
    Sensitive directory names whose presence in any path segment marks the path dangerous.
    String[]
    dangerousFiles
    Sensitive filenames that must require explicit permission for this tool.
    String
    description
    The description of the tool that explains its purpose and usage.
    boolean
    externalTool
    Whether the tool is executed outside the framework.
    String
    name
    The name of the tool.
    boolean
    readOnly
    Whether the tool only reads data without observable side effects.
    boolean
    stateInjected
    Whether the tool requires the agent state to be injected at call time.
    boolean
    strict
    Whether to enable strict schema mode for this tool.

  • 元素详细资料

    • name

      String name
      The name of the tool.

      If not provided, the method name will be used. Tool names should follow snake_case convention (e.g., "get_weather", "send_email") for compatibility with various LLM providers.

      返回:
      The tool name, or empty string to use method name
      默认值:
      ""

    • description

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

      This description is sent to the LLM to help it decide when to invoke the tool. It should clearly explain:

      • What the tool does
      • When it should be used
      • What kind of results it returns

      If not provided, a generic description based on the method name will be generated.

      返回:
      The tool description, or empty string to auto-generate
      默认值:
      ""

    • strict

      boolean strict
      Whether to enable strict schema mode for this tool.

      When enabled, compatible model providers can enforce stronger adherence to the declared JSON schema for tool arguments.

      返回:
      true to enable strict mode for this tool
      默认值:
      false

    • readOnly

      boolean readOnly
      Whether the tool only reads data without observable side effects.

      Read-only tools are auto-allowed under PermissionMode.EXPLORE and ACCEPT_EDITS, mirroring the ToolBase.isReadOnly() contract.

      返回:
      true if this tool performs no mutation
      默认值:
      false

    • concurrencySafe

      boolean concurrencySafe
      Whether the tool is safe to invoke concurrently with itself.

      When false, the framework serialises invocations of this tool inside a parallel batch. Defaults to true to match the typical pure-function shape of @Tool methods.

      返回:
      true if multiple invocations may run in parallel without coordination
      默认值:
      true

    • externalTool

      boolean externalTool
      Whether the tool is executed outside the framework.

      External tools never run their callAsync body. Instead the framework throws a ToolSuspendException so the agent loop can surface the call to the caller via a TOOL_SUSPENDED message.

      返回:
      true if this tool should be surfaced as a suspended call
      默认值:
      false

    • stateInjected

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

      When true, the method signature must declare exactly one io.agentscope.core.state.AgentState parameter; the framework excludes that parameter from the JSON schema and binds the live state at invocation.

      返回:
      true if the tool method consumes the agent state
      默认值:
      false

    • dangerousFiles

      String[] dangerousFiles
      Sensitive filenames that must require explicit permission for this tool.

      An empty array sticks with the default list maintained by ToolBase.

      返回:
      additional dangerous filenames; empty means use defaults
      默认值:
      {}

    • dangerousDirectories

      String[] dangerousDirectories
      Sensitive directory names whose presence in any path segment marks the path dangerous.

      An empty array sticks with the default list maintained by ToolBase.

      返回:
      additional dangerous directory names; empty means use defaults
      默认值:
      {}

    • converter

      Class<? extends ToolResultConverter> converter
      Custom result converter for this tool.

      Converters transform tool method return values into ToolResultBlock instances suitable for LLM consumption. Use custom converters to:

      • Filter sensitive data from results
      • Format output in specific ways
      • Add metadata to results
      • Compress or summarize large outputs

      Usage Example: 

      
 @Tool(
     name = "get_data",
     converter = CustomJsonConverter.class
 )
 public MyData getData(String id) {
     return dataService.findById(id);
 }

      If not specified, the default converter (DefaultToolResultConverter) is used, which provides JSON serialization with schema information.

      Note: If you need complex processing with multiple steps, implement your own converter that combines the necessary logic.

      返回:
      Converter class
      另请参阅:
      默认值:
      io.agentscope.core.tool.DefaultToolResultConverter.class