The Toolkit is the central registry and execution engine for tools in AgentScope. It manages the lifecycle of tool functions, MCP (Model Context Protocol) clients, and Agent Skills, providing a unified interface for LLMs to consume tool schemas and execute actions.
The Toolkit operates by organizing tools into ToolGroup objects. By default, every Toolkit contains a "basic" group. Users can define additional groups to dynamically activate or deactivate sets of capabilities for an agent.
| Entity | Description | Source |
|---|---|---|
Toolkit | The main coordinator for tool registration, schema generation, and execution. | src/agentscope/tool/_toolkit.py66-86 |
ToolGroup | A logical container for ToolBase objects, Skill objects, and MCPClient instances. | src/agentscope/tool/_tool_group.py29-30 |
RegisteredTool | A wrapper for ToolBase that handles schema transformation and Pydantic model extensions. | src/agentscope/tool/_types.py25-42 |
ToolBase | The abstract base class for all tools (Function, MCP, Built-in). | src/agentscope/tool/_base.py7-22 |
The following diagram illustrates how tools move from code definitions to LLM-consumable schemas and back to execution results.
Diagram: Tool Schema and Execution Pipeline
Sources: src/agentscope/tool/_toolkit.py171-206 src/agentscope/tool/_toolkit.py273-315 src/agentscope/tool/_types.py56-85
AgentScope uses adapters to normalize different tool types into a common interface.
Wraps standard Python functions. It automatically parses docstrings to generate JSON schemas using _extract_func_description and _extract_input_schema src/agentscope/tool/_adapters.py78-82 It handles both synchronous and asynchronous functions, including those that return generators src/agentscope/tool/_adapters.py119-146
Integrates with Model Context Protocol (MCP) servers. It handles the translation between MCP's internal result format and AgentScope's ToolChunk format src/agentscope/tool/_adapters.py167-173 It supports both stateful sessions and stateless client generators src/agentscope/tool/_adapters.py180-203
When generating schemas via get_tool_schemas, the Toolkit preserves nested Pydantic models by merging $defs from the extended models into the final JSON schema src/agentscope/tool/_types.py118-151 It performs conflict checks to ensure that if multiple tools use the same sub-model definition, they are identical src/agentscope/tool/_types.py130-149 To avoid misleading the LLM, the Toolkit recursively removes the title field from all schema properties and $defs using _remove_title_field src/agentscope/tool/_utils.py10-43
call_tool)The call_tool method is an asynchronous generator that manages the execution of a ToolCallBlock.
Toolkit searches for the tool by name across all activated ToolGroups src/agentscope/tool/_toolkit.py291-305is_state_injected=True, the AgentState is passed into the tool call src/agentscope/tool/_toolkit.py311-313ToolChunk objects during execution and returns a final ToolResponse which aggregates all chunks src/agentscope/tool/_response.py72-74Tools can stream results using ToolChunk. The ToolResponse.append_chunk method handles the merging logic:
_merge_base64_chunks to avoid corrupting padding src/agentscope/tool/_response.py101-104RUNNING to SUCCESS, ERROR, DENIED, or INTERRUPTED based on the chunks received. ERROR is treated as the highest priority terminal state src/agentscope/tool/_response.py136-147Sources: src/agentscope/tool/_toolkit.py273-330 src/agentscope/tool/_response.py50-70 src/agentscope/tool/_response.py13-25
The Toolkit includes built-in meta-tools to allow agents to manage their own tool environment.
A meta-tool that allows the agent to activate or deactivate specific ToolGroups src/agentscope/tool/_builtin/_meta.py21-40 When an agent calls ResetTools, the Toolkit updates the activated_groups list in the AgentState src/agentscope/tool/_builtin/_meta.py142-143 The input schema for ResetTools is dynamically generated based on the group names provided to the Toolkit src/agentscope/tool/_builtin/_meta.py60-77
Diagram: ToolGroup Activation Flow
Sources: src/agentscope/tool/_toolkit.py156-163 src/agentscope/tool/_builtin/_meta.py141-154
Since Agent Skills are not tools but rather complex instructions, the SkillViewer tool allows agents to read the full instructions of a registered skill src/agentscope/tool/_toolkit.py165-169 The Toolkit provides a _get_available_skills method to the viewer to ensure it only accesses skills within currently activated groups src/agentscope/tool/_toolkit.py246-271
Sources: src/agentscope/tool/_toolkit.py51-63 src/agentscope/tool/_toolkit.py165-169 src/agentscope/tool/_builtin/_skill.py12-13
Refresh this wiki