类class agentscope.tool

FunctionTool

class FunctionTool(ToolBase)

源码Source agentscope/tool/_adapters.py:39–194

FunctionTool 从普通 Python 函数的签名、类型注解和 docstring 生成工具模式，并把调用结果封装成 ToolResponse。它是最常用的自定义工具方式。位于 agentscope.tool 包，继承自 ToolBase。核心成员包括 check_permissions、call。

This class wraps a regular Python function and makes it compatible with the ToolProtocol interface. It automatically extracts metadata from the function's signature and docstring, and normalizes the return value to ToolChunk or AsyncGenerator[ToolChunk, None].

核心精讲Deep dive

FunctionTool：把函数变成工具FunctionTool: turn functions into tools

FunctionTool 从普通 Python 函数的签名、类型注解和 docstring 生成工具 schema，并把调用结果封装成 ToolResponse。它是最常用的自定义工具方式。

FunctionTool derives a tool schema from a Python function's signature, type hints and docstring, and wraps results into ToolResponse. It is the most common way to add custom tools.

Google 风格 docstring 的 Args 段会变成参数说明。The Args section of a Google-style docstring becomes parameter documentation.
is_read_only、is_concurrency_safe 影响调度与权限策略。is_read_only and is_concurrency_safe influence scheduling and permission policy.
permission 可为单个工具指定默认权限决策。permission assigns a default permission decision to an individual tool.

带参数说明的自定义工具A custom tool with parameter docs

from agentscope.tool import FunctionTool, Toolkit


async def search_docs(query: str, limit: int = 5) -> str:
    """Search the internal documentation.

    Args:
        query: Keywords to search for.
        limit: Maximum number of results.
    """
    return f"top {limit} results for {query}"


toolkit = Toolkit(tools=[FunctionTool(search_docs, is_read_only=True)])

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(func: Function, name: str \| None = None, description: str \| None = None, input_schema: dict \| type[BaseMod…`	从函数签名、类型注解与 docstring 构建工具。 Initialize the FunctionTool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`is_external_tool`	bool	是外部工具字段。	`False`
`is_mcp`	bool	是 MCP字段。	`False`
`mcp_name`	str \| None	MCP 名称字段。	`None`

方法摘要Method Summary

方法Method	说明Description
`async def check_permissions(_args: Any, *_kwargs: Any) ->` `PermissionDecision`async	按工具权限策略检查本次调用。 Check permissions for the tool usage.
`async def call(**kwargs: Any) ->` `ToolChunk \| AsyncGenerator[ToolChunk, None]`async	执行工具函数并返回结果块或结果流。 Invoke the wrapped function in an async style.

构造器详情Constructor Detail

FunctionTool

def __init__(func: Function, name: str | None = None, description: str | None = None, input_schema: dict | type[BaseModel] | None = None, is_concurrency_safe: bool = True, is_read_only: bool = False, is_state_injected: bool = False, middlewares: list[ToolMiddlewareBase] | None = None, permission: PermissionDecision | None = None) -> None

初始化 FunctionTool 实例。

Initialize the FunctionTool.

参数Parameters

名称Name	类型Type	说明Description
`func`	Function	func（类型 `Function`）。The Python function to wrap.
`name`默认default `None`	str \| None	名称（类型 `str \| None`）。Custom tool name. If None, uses the function name.
`description`默认default `None`	str \| None	描述（类型 `str \| None`）。Custom tool description. If None, extracts from docstring.
`input_schema`默认default `None`	dict \| type[BaseModel] \| None	输入模式（类型 `dict \| type[BaseModel] \| None`）。Custom input schema for the tool, either a JSON schema dict or a pydantic `BaseModel` subclass (converted via its `model_json_schema()`). If None, generates the schema from the function's type annotations and docstring, where constraints (e.g. enums, value ranges) can be expressed with `typing.Literal` and `typing.Annotated` with `pydantic.Field`.
`is_concurrency_safe`默认default `True`	bool	是 concurrency 安全（类型 `bool`）。Whether this tool is safe to call concurrently.
`is_read_only`默认default `False`	bool	是读取 only（类型 `bool`）。Whether this tool only reads data without side effects.
`is_state_injected`默认default `False`	bool	是状态 injected（类型 `bool`）。Whether this tool requires agent state injection.
`middlewares`默认default `None`	list[ToolMiddlewareBase] \| None	中间件列表（类型 `list[ToolMiddlewareBase] \| None`）。Tool middlewares wrapping the tool execution.
`permission`默认default `None`	PermissionDecision \| None	权限（类型 `PermissionDecision \| None`）。The permission decision of this tool. If not provided, the user will be asked to confirm the tool call.

源码Source agentscope/tool/_adapters.py:57–117

属性详情Attribute Detail

is_external_tool

bool = False

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

The is external tool field.

源码Source agentscope/tool/_adapters.py:48

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_adapters.py:51

mcp_name

str | None = None

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

The mcp name field.

源码Source agentscope/tool/_adapters.py:53

方法详情Method Detail

check_permissions

async def check_permissions(*_args: Any, **_kwargs: Any) -> PermissionDecision

async

检查权限用于工具用量。

Check permissions for the tool usage.

参数Parameters

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

返回Returns PermissionDecision

返回PermissionDecision。`PermissionDecision`:

源码Source agentscope/tool/_adapters.py:119–138

call

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

async

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

Invoke the wrapped function in an async style.

参数Parameters

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

返回Returns ToolChunk | AsyncGenerator[ToolChunk, None]

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

源码Source agentscope/tool/_adapters.py:140–176

继承成员Inherited Members

继承自Inherited from ToolBase

__call__, check_external_result, check_read_only, match_rule, generate_suggestions, name, description, input_schema, is_concurrency_safe, is_read_only, is_state_injected, metadata_schema, dangerous_files, dangerous_directories