ToolBase
public abstract class ToolBase implements AgentToolio/agentscope/core/tool/ToolBase.java:59–387工具基类，让智能体以受控方式调用外部能力。位于 io.agentscope.core.tool 包，实现 AgentTool。核心成员包括 getName、getDescription、getParameters、isConcurrencySafe、isReadOnly、isReturnDirect。
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));
`
嵌套类摘要Nested Class Summary
| 类Class | 类型Kind | 说明Description |
|---|---|---|
Builder | 类class | 构建器，用于构建并配置目标实例。 Fluent builder for `ToolBase` subclasses. |
字段摘要Field Summary
| 字段Field | 类型Type | 说明Description |
|---|---|---|
dangerousFiles | List<String> | `dangerousFiles` 字段。 Sensitive files; subclasses may replace this list to widen or narrow protection. |
dangerousDirectories | List<String> | `dangerousDirectories` 字段。 Sensitive directory names; segment-level matching applies to absolute paths. |
构造器摘要Constructor Summary
| 构造器Constructor | 说明Description |
|---|---|
protected ToolBase(Builder builder) | 初始化 `ToolBase` 实例。 Builder-based constructor (preferred). |
protected ToolBase(String name, String description, Map<String, Object> inputSchema, boolean readOnly, boolean concurrencySafe, boolean mcp, String mcpName, boolean externalTool, boolean stateInjected) | 初始化 `ToolBase` 实例。 Positional constructor used by built-in tools and any subclass that prefers explicit
arguments over `#builder()`. |
方法摘要Method Summary
| 方法Method | 说明Description |
|---|---|
public final String getName()final | 获取名称。 Returns the name. |
public final String getDescription()final | 获取 `getDescription`。 Returns the description. |
public final Map<String, Object> getParameters()final | 获取参数。 Returns the parameters. |
public final boolean isConcurrencySafe()final | 判断是否 `isConcurrencySafe`。 Returns whether the concurrency safe. |
public final boolean isReadOnly()final | 判断是否 `isReadOnly`。 Returns whether the read only. |
public final boolean isReturnDirect()final | 判断是否 `isReturnDirect`。 Whether this tool's result should short-circuit the ReAct loop and be returned directly
to the caller as the turn's final answer, instead of being fed back to the model for
another reasoning iteration. |
public final boolean isExternalTool()final | 判断是否外部工具。 Returns whether the external tool. |
public final boolean isStateInjected()final | 判断是否 `isStateInjected`。 Returns whether the state injected. |
public final boolean isMcp()final | 判断是否MCP。 Returns whether the mcp. |
public final String getMcpName()final | 获取MCP 名称。 Returns the mcp name. |
public Mono<ToolResultBlock> callAsync(ToolCallParam param) | 调用异步。 Default tool invocation. |
public 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. |
public boolean matchRule(String ruleContent, Map<String, Object> toolInput) | 执行 `matchRule` 方法。 Default rule matcher: a `null` `ruleContent` matches every invocation; any
non-null pattern is rejected so subclasses can layer their own semantics on top. |
public List<PermissionRule> generateSuggestions(Map<String, Object> toolInput) | 设置该参数。 Default suggestion: a single tool-name-level `PermissionBehavior#ALLOW` rule sourced
from `"suggested"`. |
protected boolean isDangerousPath(String filePath) | 判断是否 `isDangerousPath`。 Returns whether the dangerous path. |
public static Builder builder()static | 返回构建器实例。 Returns the builder. |
字段详情Field Detail
dangerousFiles
protected List<String> dangerousFilesdangerousFiles 字段。声明为 protected List dangerousFiles。
Sensitive files; subclasses may replace this list to widen or narrow protection.
io/agentscope/core/tool/ToolBase.java:73dangerousDirectories
protected List<String> dangerousDirectoriesdangerousDirectories 字段。声明为 protected List dangerousDirectories。
Sensitive directory names; segment-level matching applies to absolute paths.
io/agentscope/core/tool/ToolBase.java:76–77构造器详情Constructor Detail
ToolBase
protected ToolBase(Builder builder)初始化 ToolBase 实例。
Builder-based constructor (preferred).
| 名称Name | 类型Type | 说明Description |
|---|---|---|
builder | Builder | 构建器（类型 `Builder`）。The builder. |
io/agentscope/core/tool/ToolBase.java:80–98ToolBase
protected ToolBase(String name, String description, Map<String, Object> inputSchema, boolean readOnly, boolean concurrencySafe, boolean mcp, String mcpName, boolean externalTool, boolean stateInjected)初始化 ToolBase 实例。
Positional constructor used by built-in tools and any subclass that prefers explicit arguments over #builder().
| 名称Name | 类型Type | 说明Description |
|---|---|---|
name | String | 名称（类型 `String`）。The name. |
description | String | 描述（类型 `String`）。The description. |
inputSchema | Map<String, Object> | 输入模式（类型 `Map`）。The input schema. |
readOnly | boolean | 读取 Only（类型 `boolean`）。The read only. |
concurrencySafe | boolean | concurrency 安全（类型 `boolean`）。The concurrency safe. |
mcp | boolean | MCP（类型 `boolean`）。The mcp. |
mcpName | String | MCP 名称（类型 `String`）。The mcp name. |
externalTool | boolean | 外部工具（类型 `boolean`）。The external tool. |
stateInjected | boolean | 状态 Injected（类型 `boolean`）。The state injected. |
io/agentscope/core/tool/ToolBase.java:104–125方法详情Method Detail
getName
public final String getName()获取名称。
Returns the name.
Stringio/agentscope/core/tool/ToolBase.java:153–156getDescription
public final String getDescription()获取 getDescription。
Returns the description.
Stringio/agentscope/core/tool/ToolBase.java:158–161getParameters
public final Map<String, Object> getParameters()获取参数。
Returns the parameters.
Map<String, Object>io/agentscope/core/tool/ToolBase.java:163–166isConcurrencySafe
public final boolean isConcurrencySafe()判断是否 isConcurrencySafe。
Returns whether the concurrency safe.
booleanio/agentscope/core/tool/ToolBase.java:168–170isReadOnly
public final boolean isReadOnly()判断是否 isReadOnly。
Returns whether the read only.
booleanio/agentscope/core/tool/ToolBase.java:172–175isReturnDirect
public final boolean isReturnDirect()判断是否 isReturnDirect。
Whether this tool's result should short-circuit the ReAct loop and be returned directly to the caller as the turn's final answer, instead of being fed back to the model for another reasoning iteration.
booleanio/agentscope/core/tool/ToolBase.java:184–187isExternalTool
public final boolean isExternalTool()判断是否外部工具。
Returns whether the external tool.
booleanio/agentscope/core/tool/ToolBase.java:189–191isStateInjected
public final boolean isStateInjected()判断是否 isStateInjected。
Returns whether the state injected.
booleanio/agentscope/core/tool/ToolBase.java:193–195isMcp
public final boolean isMcp()判断是否MCP。
Returns whether the mcp.
booleanio/agentscope/core/tool/ToolBase.java:197–199getMcpName
public final String getMcpName()获取MCP 名称。
Returns the mcp name.
Stringio/agentscope/core/tool/ToolBase.java:201–203callAsync
public Mono<ToolResultBlock> callAsync(ToolCallParam param)调用异步。
Default tool invocation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
param | ToolCallParam | 参数（类型 `ToolCallParam`）。The param. |
Mono<ToolResultBlock>io/agentscope/core/tool/ToolBase.java:209–220checkPermissions
public 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.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
toolInput | Map<String, Object> | 已解析工具参数。the parsed tool arguments |
context | PermissionContextState | 上下文（类型 `PermissionContextState`）。current permission evaluation context |
Mono<PermissionDecision>io/agentscope/core/tool/ToolBase.java:235–238matchRule
public boolean matchRule(String ruleContent, Map<String, Object> toolInput)执行 matchRule 方法。
Default rule matcher: a null ruleContent matches every invocation; any non-null pattern is rejected so subclasses can layer their own semantics on top.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
ruleContent | String | 规则内容（类型 `String`）。The rule content. |
toolInput | Map<String, Object> | 工具输入（类型 `Map`）。The tool input. |
booleanio/agentscope/core/tool/ToolBase.java:244–246generateSuggestions
public List<PermissionRule> generateSuggestions(Map<String, Object> toolInput)设置该参数。
Default suggestion: a single tool-name-level PermissionBehavior#ALLOW rule sourced from "suggested".
| 名称Name | 类型Type | 说明Description |
|---|---|---|
toolInput | Map<String, Object> | 工具输入（类型 `Map`）。The tool input. |
List<PermissionRule>io/agentscope/core/tool/ToolBase.java:253–255isDangerousPath
protected boolean isDangerousPath(String filePath)判断是否 isDangerousPath。
Returns whether the dangerous path.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
filePath | String | 文件路径（类型 `String`）。The file path. |
booleanio/agentscope/core/tool/ToolBase.java:263–280builder
public static Builder builder()返回构建器实例。
Returns the builder.
Builderio/agentscope/core/tool/ToolBase.java:308–310嵌套类详情Nested Class Detail
Builder
public static final class Builder构建器，用于构建并配置目标实例。位于 io.agentscope.core.tool 包。核心成员包括 name、description、inputSchema、readOnly、concurrencySafe、externalTool。
Fluent builder for ToolBase subclasses.