程序包 io.agentscope.core.tool

接口 AgentTool

所有已知实现类:
McpTool, SchemaOnlyTool, ShellCommandTool, SubAgentTool, ToolBase
public interface AgentTool
Interface for agent tools that can be called by models.

Agent tools are functions that AI agents can invoke to perform actions or retrieve information. They bridge the gap between the agent's reasoning and the external world.

Implementation Guidelines:

  • Tools should have clear, descriptive names
  • Descriptions should explain what the tool does and when to use it
  • Parameter schemas must follow JSON Schema format
  • All operations should be implemented asynchronously using Reactor Mono
另请参阅:

  • 方法详细资料

    • getName

      String getName()
      Gets the name of the tool.

      The name should be unique within a toolkit and follow snake_case convention for compatibility with various LLM providers.

      返回:
      The tool name (never null)

    • getDescription

      String getDescription()
      Gets the description of the tool.

      The description should clearly explain what the tool does, when it should be used, and what kind of results it returns. This helps the LLM decide when to invoke the tool.

      返回:
      The tool description (never null)

    • getParameters

      Map<String,Object> getParameters()
      Gets the parameters schema for this tool in JSON Schema format.

      The schema defines the structure of the input parameters that this tool accepts. It should include:

      • type: "object"
      • properties: Map of parameter names to their schemas
      • required: List of required parameter names
      返回:
      Map representing the JSON Schema for tool parameters (never null)

    • getStrict

      default Boolean getStrict()
      Gets strict mode configuration for this tool schema.

      When strict mode is enabled, compatible model providers are expected to enforce stricter adherence to the tool parameter schema. Returning null means no explicit strict mode preference is provided.

      返回:
      strict mode value (true/false) or null when unspecified

    • getOutputSchema

      default Map<String,Object> getOutputSchema()
      Gets the optional output schema for this tool in JSON Schema format.

      Most tools do not expose a structured output schema to models, so the default implementation returns null. MCP tools can override this to surface the server-provided outputSchema definition.

      返回:
      Map representing the JSON Schema for tool outputs, or null if unsupported

    • isReadOnly

      default boolean isReadOnly()
      Returns whether this tool performs only read operations and never mutates state.

      Read-only tools are automatically permitted in restricted execution modes such as Plan Mode, where write operations require explicit approval.

      返回:
      true if the tool is read-only; false by default

    • callAsync

      reactor.core.publisher.Mono<ToolResultBlock> callAsync(ToolCallParam param)
      Execute the tool with the given parameters (asynchronous).

      This method accepts a ToolCallParam object containing all necessary context for tool execution, including:

      • toolUseBlock: Contains tool call ID and name for tracking
      • input: Input parameters for the tool
      • agent: The calling agent (may be null), provides access to agent context
      参数:
      param - The tool call parameters
      返回:
      Mono containing ToolResultBlock