程序包 io.agentscope.core.tool

类 ToolBase

java.lang.Object
io.agentscope.core.tool.ToolBase
所有已实现的接口:
AgentTool
直接已知子类:
McpTool, SchemaOnlyTool
public abstract class ToolBase extends Object implements AgentTool
Abstract base class for tools that participate in permission evaluation and ReAct execution.

Concrete subclasses describe themselves via the builder (name, description, input schema, safety flags) and may override checkPermissions(Map, PermissionContextState) to plug their own self-check into the permission engine. The default implementation returns PermissionDecision.passthrough(String), which lets the engine fall back to its rule tables and mode-based defaults.

ToolBase implements AgentTool so instances plug directly into the existing Toolkit dispatch. Tools that produce results outside the framework (external tools) should mark externalTool=true; the ToolExecutor surfaces the call through a ToolSuspendException instead of invoking it locally.

Builder usage: 


 super(ToolBase.builder()
         .name("read")
         .description("Read a file")
         .inputSchema(schema)
         .readOnly(true)
         .concurrencySafe(true)
         .build());

  • 字段详细资料

    • dangerousFiles

      protected List<String> dangerousFiles
      Sensitive files; subclasses may replace this list to widen or narrow protection.

    • dangerousDirectories

      protected List<String> dangerousDirectories
      Sensitive directory names; segment-level matching applies to absolute paths.

  • 构造器详细资料

    • ToolBase

      protected ToolBase(ToolBase.Builder builder)
      Builder-based constructor (preferred).

    • ToolBase

      protected ToolBase(String name, String description, Map<String,Object> inputSchema, boolean readOnly, boolean concurrencySafe, boolean mcp, String mcpName, boolean externalTool, boolean stateInjected)
      Positional constructor used by built-in tools and any subclass that prefers explicit arguments over builder(). New code is encouraged to use the builder for clarity.

  • 方法详细资料

    • getName

      public final String getName()
      从接口复制的说明: AgentTool
      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.

      指定者:
      getName 在接口中 AgentTool
      返回:
      The tool name (never null)

    • getDescription

      public final String getDescription()
      从接口复制的说明: AgentTool
      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.

      指定者:
      getDescription 在接口中 AgentTool
      返回:
      The tool description (never null)

    • getParameters

      public final Map<String,Object> getParameters()
      从接口复制的说明: AgentTool
      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
      指定者:
      getParameters 在接口中 AgentTool
      返回:
      Map representing the JSON Schema for tool parameters (never null)

    • isConcurrencySafe

      public final boolean isConcurrencySafe()

    • isReadOnly

      public final boolean isReadOnly()
      从接口复制的说明: AgentTool
      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.

      指定者:
      isReadOnly 在接口中 AgentTool
      返回:
      true if the tool is read-only; false by default

    • isExternalTool

      public final boolean isExternalTool()

    • isStateInjected

      public final boolean isStateInjected()

    • isMcp

      public final boolean isMcp()

    • getMcpName

      public final String getMcpName()

    • callAsync

      public reactor.core.publisher.Mono<ToolResultBlock> callAsync(ToolCallParam param)
      Default tool invocation. External tools must not be invoked locally; non-external subclasses must override this method.
      指定者:
      callAsync 在接口中 AgentTool
      参数:
      param - The tool call parameters
      返回:
      Mono containing ToolResultBlock

    • checkPermissions

      public reactor.core.publisher.Mono<PermissionDecision> checkPermissions(Map<String,Object> toolInput, PermissionContextState context)
      Tool self-check invoked by the permission engine when allowRules/askRules neither allow nor reject the call outright.

      The default implementation returns PermissionDecision.passthrough(String), delegating the decision to the engine's rule tables and mode defaults. Tools with fine-grained semantics (Bash, file writers, MCP tools) should override this to surface their own ALLOW / ASK / DENY policy.

      参数:
      toolInput - the parsed tool arguments
      context - current permission evaluation context
      返回:
      a Mono emitting the decision; never null

    • matchRule

      public boolean matchRule(String ruleContent, Map<String,Object> toolInput)
      Default rule matcher: a null ruleContent matches every invocation; any non-null pattern is rejected so subclasses can layer their own semantics on top.

    • generateSuggestions

      public List<PermissionRule> generateSuggestions(Map<String,Object> toolInput)
      Default suggestion: a single tool-name-level PermissionBehavior.ALLOW rule sourced from "suggested". Subclasses with finer-grained context (file paths, command prefixes) override this to produce more specific patterns.

    • isDangerousPath

      protected boolean isDangerousPath(String filePath)
      返回:
      true when filePath's filename matches one of dangerousFiles (case-insensitive), or when any segment matches one of dangerousDirectories. Also resolves symlinks and re-checks the real path to prevent bypass via symlink pointing at a dangerous target.

    • builder

      public static ToolBase.Builder builder()