类class agentscope.tool

Toolkit

class Toolkit

源码Source agentscope/tool/_toolkit.py:66–695

工具包是工具、技能与 MCP 客户端的统一注册表。它把 Python 函数或 MCP 工具转换成模型可理解的模式，并在调用时完成权限检查、并发调度与结果封装。位于 agentscope.tool 包。核心成员包括 get_tool_schemas、call_tool、get_skill_instructions、check_tool_available、get_tool、clear。

About tool functions:

Register and parse JSON schemas from their docstrings automatically.
Group-wise tools management, and agentic tools activation/deactivation.
Extend the tool function JSON schema dynamically with Pydantic BaseModel.
Tool function execution with unified streaming interface.

About MCP clients:

Register tool functions from MCP clients directly.
Client-level tool functions removal.

About Agent skills:

Register agent skills from the given directory.
Provide prompt for the registered skills to the agent.

核心精讲Deep dive

Toolkit：工具注册与执行Toolkit: registration and execution

Toolkit 是工具、技能与 MCP 客户端的统一注册表。它把 Python 函数或 MCP 工具转换成模型可理解的 schema，并在调用时完成权限检查、并发调度与结果封装。

Toolkit is the unified registry for tools, skills and MCP clients. It turns Python functions or MCP tools into model-readable schemas and handles permission checks, concurrency and result wrapping at call time.

用 FunctionTool 包装普通函数，或在构造时通过 mcps 接入 MCP 工具。Wrap plain functions with FunctionTool, or attach MCP tools through the mcps argument.
add_tool、remove_tool 支持运行时调整；工具可归入不同 group 动态启用。add_tool and remove_tool adjust the registry at runtime; tools can be grouped and activated dynamically.
call_tool 接收 ToolCallBlock，产出 ToolChunk 流或最终 ToolResponse。call_tool accepts a ToolCallBlock and produces a stream of ToolChunk or a final ToolResponse.

注册函数工具并查看 schemaRegister a function tool and inspect its schema

import asyncio

from agentscope.tool import FunctionTool, Toolkit


async def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    return f"{city}: sunny, 24C"


async def main() -> None:
    toolkit = Toolkit(tools=[FunctionTool(get_weather, is_read_only=True)])
    schemas = await toolkit.get_tool_schemas()
    print(schemas)


asyncio.run(main())

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(tools: list[ToolBase] \| None = None, skills_or_loaders: Sequence[str \| Skill \| SkillLoaderBase] \| None = N…`	创建工具注册表，可同时传入工具、技能、MCP 客户端与工具分组。 Initialize the toolkit.

方法摘要Method Summary

方法Method	说明Description
`async def get_tool_schemas(groups: list[str] \| None = None) -> list[dict]`async	生成模型可读的工具模式列表，可按分组过滤。 Get the JSON schemas of the currently available tool functions based on the given activated tool groups.
`async def call_tool(tool_call:` `ToolCallBlock, state: AgentState) -> AsyncGenerator[ToolChunk \| ToolResponse, None]`async	执行一次工具调用，流式产出 ToolChunk 或最终 ToolResponse。 Call the tool function, return the incremental tool result in a ToolChunk stream, and finally return the complete tool result in a ToolResponse object. Note the accumulation process occurs within this function, so the tool functions only need to return/yield the ToolChunk objects in an incremental manner.
`async def get_skill_instructions(activated_groups: list[str] \| None = None) -> str \| None`async	汇总已激活技能的说明文本。 Get the prompt for all registered agent skills, which can be attached to the system prompt for the agent.
`async def check_tool_available(tool_name: str, activated_groups: list[str]) ->` `ToolBase`async	检查工具是否在已激活分组中可用。 Check if the tool is available now. If not, raise the agent-oriented exception.
`async def get_tool(name: str) ->` `ToolBase \| None`async	按名称查找工具实例。 Get tool instance by its name.
`def clear() -> None`	清空全部工具与分组注册。 Clear the registered tools, skills and MCPs.
`async def add_tool(tool:` `ToolBase \| list[ToolBase], group_name: str = 'basic') -> None`async	注册一个或多个工具，并归入指定分组。 Add tool to the toolkit on-the-fly.
`async def remove_tool(tool_name: str \| list[str]) -> None`async	按名称移除已注册的工具。 Remove tool from the toolkit on-the-fly.

构造器详情Constructor Detail

Toolkit

def __init__(tools: list[ToolBase] | None = None, skills_or_loaders: Sequence[str | Skill | SkillLoaderBase] | None = None, mcps: list[MCPClient] | None = None, tool_groups: list[ToolGroup] | None = None, meta_tool_response_template: str = DEFAULT_META_TOOL_RESPONSE_TEMPLATE, skill_instruction_template: str = DEFAULT_SKILL_INSTRUCTION) -> None

初始化 Toolkit 实例。

Initialize the toolkit.

参数Parameters

名称Name	类型Type	说明Description
`tools`默认default `None`	list[ToolBase] \| None	工具列表（类型 `list[ToolBase] \| None`）。The tool objects that belong to the "basic" tool group.
`skills_or_loaders`默认default `None`	Sequence[str \| Skill \| SkillLoaderBase] \| None	技能或 loaders（类型 `Sequence[str \| Skill \| SkillLoaderBase] \| None`）。The agent skill directories to be registered in the "basic" tool group.
`mcps`默认default `None`	list[MCPClient] \| None	MCP 客户端到为已注册 in"基础"工具组。The mcp clients to be registered in the "basic" tool group.
`tool_groups`默认default `None`	list[ToolGroup] \| None	工具组到为已注册。The tool groups to be registered.
`meta_tool_response_template`默认default `DEFAULT_META_TOOL_RESPONSE_TEMPLATE`	str	元数据工具响应模板（类型 `str`）。The template for meta tool responses.
`skill_instruction_template`默认default `DEFAULT_SKILL_INSTRUCTION`	str	技能指令模板（类型 `str`）。A Jinja2 template for generating the agent skill instruction.

源码Source agentscope/tool/_toolkit.py:88–169

方法详情Method Detail

get_tool_schemas

async def get_tool_schemas(groups: list[str] | None = None) -> list[dict]

async

获取工具模式列表。

Get the JSON schemas of the currently available tool functions based on the given activated tool groups.

示例Example

:caption: Example of tool function JSON schemas

[
    {
        "type": "function",
        "function": {
            "name": "google_search",
            "description": "Search on Google.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query."
                    }
                },
                "required": ["query"]
            }
        }
    },
    ...
]

说明Notes

注意：该行为受运行时配置或底层实现影响，建议结合对应源码与版本说明确认。Note: The preset keyword arguments is removed from the JSON schema, and the extended model is applied if it is set.

参数Parameters

名称Name	类型Type	说明Description
`groups`默认default `None`	list[str] \| None	组（类型 `list[str] \| None`）。A list of group names to filter the tool function. The "basic" group will always be included regardless of the filter. If not provided, only the "basic" group will be included.

返回Returns list[dict]

模型可读的工具模式列表。`list[dict]`:

源码Source agentscope/tool/_toolkit.py:171–223

call_tool

async def call_tool(tool_call: ToolCallBlock, state: AgentState) -> AsyncGenerator[ToolChunk | ToolResponse, None]

async

执行单个工具调用。

Call the tool function, return the incremental tool result in a ToolChunk stream, and finally return the complete tool result in a ToolResponse object.

参数Parameters

名称Name	类型Type	说明Description
`tool_call`	ToolCallBlock	模型产生的工具调用块。A tool call block.
`state`	AgentState	当前智能体状态，供有状态工具读取。The current agent state, used to state injection.

返回Returns AsyncGenerator[ToolChunk | ToolResponse, None]

以异步流的形式返回ToolChunk|ToolResponse,None。`ToolChunk | ToolResponse`:

源码Source agentscope/tool/_toolkit.py:225–392

get_skill_instructions

async def get_skill_instructions(activated_groups: list[str] | None = None) -> str | None

async

获取技能指令。

The prompt is consisted of an overall instruction and the detailed descriptions of each skill, including its name, description, and directory.

说明Notes

注意：该行为受运行时配置或底层实现影响，建议结合对应源码与版本说明确认。Note: If no skill is registered, None will be returned.

参数Parameters

名称Name	类型Type	说明Description
`activated_groups`默认default `None`	list[str] \| None	activated 组（类型 `list[str] \| None`）。The currently activated tool groups. If omitted, all groups will be included for backwards compatibility.

返回Returns str | None

返回str|None。`str | None`:

源码Source agentscope/tool/_toolkit.py:431–471

check_tool_available

async def check_tool_available(tool_name: str, activated_groups: list[str]) -> ToolBase

async

检查工具是否可用。

Check if the tool is available now.

参数Parameters

名称Name	类型Type	说明Description
`tool_name`	str	工具名称（类型 `str`）。The name of the tool to be checked.
`activated_groups`	list[str]	activated 组（类型 `list[str]`）。The currently activated tool groups.

返回Returns ToolBase

返回ToolBase。`ToolBase`:

源码Source agentscope/tool/_toolkit.py:556–600

get_tool

async def get_tool(name: str) -> ToolBase | None

async

按名称获取工具。

Get tool instance by its name.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。The name of the tool to be checked.

返回Returns ToolBase | None

返回ToolBase|None。`ToolBase | None`:

源码Source agentscope/tool/_toolkit.py:602–619

clear

def clear() -> None

清空或重置内部状态。

Clear the registered tools, skills and MCPs.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/tool/_toolkit.py:636–638

add_tool

async def add_tool(tool: ToolBase | list[ToolBase], group_name: str = 'basic') -> None

async

添加工具。

Add tool to the toolkit on-the-fly.

参数Parameters

名称Name	类型Type	说明Description
`tool`	ToolBase \| list[ToolBase]	工具到为已添加。The tool to be added.
`group_name`默认default `'basic'`	str	工具到为已添加的组名称。The group name of the tool to be added.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/tool/_toolkit.py:640–680

remove_tool

async def remove_tool(tool_name: str | list[str]) -> None

async

移除工具。

Remove tool from the toolkit on-the-fly.

参数Parameters

名称Name	类型Type	说明Description
`tool_name`	str \| list[str]	工具到为已移除的名称。The name of the tool to be removed.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/tool/_toolkit.py:682–695