类class agentscope.tool

ToolBase

class ToolBase(ABC)

源码Source agentscope/tool/_base.py:100–491

工具协议。位于 agentscope.tool 包，继承自 ABC。核心成员包括 call、check_permissions、check_external_result、check_read_only、match_rule、generate_suggestions。

The tool protocol. Declared in agentscope.tool. Extends ABC.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(middlewares: List['ToolMiddlewareBase'] \| None = None) -> None`	初始化 `ToolBase` 实例。 Initialize the tool with optional middlewares.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	—
`description`	str	`description` 字段。	—
`input_schema`	dict[str, Any]	输入模式字段。	—
`is_concurrency_safe`	bool	`is_concurrency_safe` 字段。	—
`is_read_only`	bool	`is_read_only` 字段。	—
`is_external_tool`	bool	是外部工具字段。	`False`
`is_state_injected`	bool	`is_state_injected` 字段。	`False`
`metadata_schema`	dict[str, Any] \| None	元数据模式字段。	`None`
`is_mcp`	bool	是 MCP字段。	`False`
`mcp_name`	str \| None	MCP 名称字段。	`None`
`dangerous_files`	list[str]	`dangerous_files` 字段。	`DEFAULT_DANGEROUS_FILES`
`dangerous_directories`	list[str]	`dangerous_directories` 字段。	`DEFAULT_DANGEROUS_DIRECTORIES`

方法摘要Method Summary

方法Method	说明Description
`async def call(args: Any, *kwargs: Any) ->` `ToolChunk \| AsyncGenerator[ToolChunk, None]`async	向智能体发送输入并返回最终回复。 Execute the tool logic.
`async def __call__(args: Any, *kwargs: Any) ->` `ToolChunk \| AsyncGenerator[ToolChunk, None]`async	以可调用对象方式执行。 Invoke the tool, layering any registered middlewares around :meth:`call`.
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`asyncabstractabstractmethod	检查权限用于工具用量。 Check permissions for the tool usage.
`async def check_external_result(result: 'ToolResultBlock') -> None`async	检查外部结果。 Reject a result an external executor sent back.
`async def check_read_only(tool_input: dict[str, Any]) -> bool`async	检查 `check_read_only` 条件。 Decide whether this specific invocation is read-only.
`async def match_rule(rule_content: str \| None, tool_input: dict[str, Any]) -> bool`async	执行 `match_rule` 方法。 Check if a permission rule matches the tool input.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]`async	设置该参数。 Generate suggested permission rules for the tool input.

构造器详情Constructor Detail

ToolBase

def __init__(middlewares: List['ToolMiddlewareBase'] | None = None) -> None

初始化 ToolBase 实例。

Initialize the tool with optional middlewares.

参数Parameters

名称Name	类型Type	说明Description
`middlewares`默认default `None`	List['ToolMiddlewareBase'] \| None	中间件列表（类型 `List['ToolMiddlewareBase'] \| None`）。A list of :class:`ToolMiddlewareBase` instances wrapping the tool execution in an onion fashion. Defaults to an empty list.

源码Source agentscope/tool/_base.py:144–157

属性详情Attribute Detail

name

str

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_base.py:103

description

str

description 字段。声明为 str。

The description field.

源码Source agentscope/tool/_base.py:105

input_schema

dict[str, Any]

输入模式字段。声明为 dict[str, Any]。

The input schema field.

源码Source agentscope/tool/_base.py:107

is_concurrency_safe

bool

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_base.py:109

is_read_only

bool

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_base.py:111

is_external_tool

bool = False

是外部工具字段。声明为 bool。

The is external tool field.

源码Source agentscope/tool/_base.py:114

is_state_injected

bool = False

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_base.py:117

metadata_schema

dict[str, Any] | None = None

元数据模式字段。声明为 dict[str, Any] | None。

The metadata schema field.

源码Source agentscope/tool/_base.py:122

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_base.py:131

mcp_name

str | None = None

MCP 名称字段。声明为 str | None。

The mcp name field.

源码Source agentscope/tool/_base.py:133

dangerous_files

list[str] = DEFAULT_DANGEROUS_FILES

dangerous_files 字段。声明为 list[str]。

The dangerous files field.

源码Source agentscope/tool/_base.py:138

dangerous_directories

list[str] = DEFAULT_DANGEROUS_DIRECTORIES

dangerous_directories 字段。声明为 list[str]。

The dangerous directories field.

源码Source agentscope/tool/_base.py:140

方法详情Method Detail

call

async def call(*args: Any, **kwargs: Any) -> ToolChunk | AsyncGenerator[ToolChunk, None]

async

向智能体发送输入并返回最终回复。

This is the new override point for tool implementations.

参数Parameters

名称Name	类型Type	说明Description
`args`	Any	参数（类型 `Any`）。The args.
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns ToolChunk | AsyncGenerator[ToolChunk, None]

返回ToolChunk|AsyncGenerator[ToolChunk,None]。`ToolChunk | AsyncGenerator[ToolChunk, None]`:

源码Source agentscope/tool/_base.py:159–188

call

async def __call__(*args: Any, **kwargs: Any) -> ToolChunk | AsyncGenerator[ToolChunk, None]

async

以可调用对象方式执行。

Tools are always invoked with keyword arguments only.

参数Parameters

名称Name	类型Type	说明Description
`args`	Any	参数（类型 `Any`）。The args.
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns ToolChunk | AsyncGenerator[ToolChunk, None]

返回ToolChunk|AsyncGenerator[ToolChunk,None]。Returns tool chunk async generator tool chunk none.

源码Source agentscope/tool/_base.py:190–263

check_permissions

async def check_permissions(tool_input: dict[str, Any], context: PermissionContext) -> PermissionDecision

asyncabstractabstractmethod

检查权限用于工具用量。

Check permissions for the tool usage.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input.
`context`	PermissionContext	上下文（类型 `PermissionContext`）。The context.

返回Returns PermissionDecision

返回PermissionDecision。Returns permission decision.

源码Source agentscope/tool/_base.py:266–271

check_external_result

async def check_external_result(result: 'ToolResultBlock') -> None

async

检查外部结果。

Called only for externally executed calls — a tool that produced its own result has nothing to check.

参数Parameters

名称Name	类型Type	说明Description
`result`	'ToolResultBlock'	结果（类型 `'ToolResultBlock'`）。The result.

返回Returns None

无返回值。No value is returned.

异常Raises

可能抛出 `Exception`。`jsonschema.ValidationError`:
可能抛出 `Exception`。If the metadata does not match what the tool promised its
可能抛出 `Exception`。caller. The reply stays parked, so the executor can fix
可能抛出 `Exception`。what it sent and try again.

源码Source agentscope/tool/_base.py:273–296

check_read_only

async def check_read_only(tool_input: dict[str, Any]) -> bool

async

检查 check_read_only 条件。

Returns the static :attr:is_read_only attribute by default.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input data for this invocation.

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/tool/_base.py:298–320

match_rule

async def match_rule(rule_content: str | None, tool_input: dict[str, Any]) -> bool

async

执行 match_rule 方法。

is a tool-name-level rule that matches every invocation; a rule with content requires the tool to override this method with its own matching logic, otherwise it returns False.

说明Notes

注意：该行为受运行时配置或底层实现影响，建议结合对应源码与版本说明确认。Note: This is an optional method. A rule with no content (`None`)

参数Parameters

名称Name	类型Type	说明Description
`rule_content`	str \| None	规则内容（类型 `str \| None`）。The rule pattern to match. `None` means "match all invocations of this tool" (tool-name-level rule).
`tool_input`	dict[str, Any]	工具输入数据。The tool input data

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/tool/_base.py:322–353

generate_suggestions

async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]

async

设置该参数。

that allows all invocations of this tool.

说明Notes

注意：该行为受运行时配置或底层实现影响，建议结合对应源码与版本说明确认。Note: Suggest a single tool-name-level rule (`rule_content=None`)

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入数据。The tool input data

返回Returns List[PermissionRule]

返回PermissionRule列表。`List[PermissionRule]`:

源码Source agentscope/tool/_base.py:355–388