Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
refactor(tool): refactor the tool module, including providing new base class and toolkit logic (#1493)
DavdGao0d8931a6d7ce
diff --git a/docs/tutorial/en/src/task_middleware.py b/docs/tutorial/en/src/task_middleware.pyindex de984c8a5..1c7880ac3 100644--- a/docs/tutorial/en/src/task_middleware.py+++ b/docs/tutorial/en/src/task_middleware.py@@ -136,7 +136,7 @@ async def example_logging_middleware() -> None:toolkit.register_middleware(logging_middleware)# Call the tool- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="1",@@ -187,7 +187,7 @@ async def example_transform_middleware() -> None:toolkit.register_tool_function(search_tool)toolkit.register_middleware(transform_middleware)- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="2",@@ -268,7 +268,7 @@ async def example_authorization_middleware() -> None:# Try authorized toolprint("\nCalling authorized tool:")- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="3",@@ -281,7 +281,7 @@ async def example_authorization_middleware() -> None:# Try unauthorized toolprint("\nCalling unauthorized tool:")- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="4",@@ -360,7 +360,7 @@ async def example_multiple_middleware() -> None:toolkit.register_middleware(middleware_1)toolkit.register_middleware(middleware_2)- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="5",diff --git a/docs/tutorial/en/src/task_tool.py b/docs/tutorial/en/src/task_tool.pyindex 927346f69..aca7b5073 100644--- a/docs/tutorial/en/src/task_tool.py+++ b/docs/tutorial/en/src/task_tool.py@@ -125,7 +125,7 @@ print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))async def example_tool_execution() -> None:"""Example of executing a tool call."""- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="123",@@ -224,7 +224,7 @@ async def example_tool_interruption() -> None:"""Example of tool interruption."""toolkit = Toolkit()toolkit.register_tool_function(non_streaming_function)- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="123",@@ -282,7 +282,7 @@ async def example_streaming_tool_interruption() -> None:toolkit = Toolkit()toolkit.register_tool_function(streaming_function)- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="xxx",@@ -408,7 +408,7 @@ print(async def mock_agent_reset_tools() -> None:"""Mock agent to reset tool groups."""# Call the meta tool function- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="154",diff --git a/docs/tutorial/zh_CN/src/task_middleware.py b/docs/tutorial/zh_CN/src/task_middleware.pyindex da9f27c9c..2f02a0384 100644--- a/docs/tutorial/zh_CN/src/task_middleware.py+++ b/docs/tutorial/zh_CN/src/task_middleware.py@@ -136,7 +136,7 @@ async def example_logging_middleware() -> None:toolkit.register_middleware(logging_middleware)# 调用工具- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="1",@@ -187,7 +187,7 @@ async def example_transform_middleware() -> None:toolkit.register_tool_function(search_tool)toolkit.register_middleware(transform_middleware)- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="2",@@ -268,7 +268,7 @@ async def example_authorization_middleware() -> None:# 尝试授权的工具print("\n调用已授权的工具:")- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="3",@@ -281,7 +281,7 @@ async def example_authorization_middleware() -> None:# 尝试未授权的工具print("\n调用未授权的工具:")- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="4",@@ -360,7 +360,7 @@ async def example_multiple_middleware() -> None:toolkit.register_middleware(middleware_1)toolkit.register_middleware(middleware_2)- result = await toolkit.call_tool_function(+ result = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="5",diff --git a/docs/tutorial/zh_CN/src/task_tool.py b/docs/tutorial/zh_CN/src/task_tool.pyindex 6e0fabfb9..ae8b80d75 100644--- a/docs/tutorial/zh_CN/src/task_tool.py+++ b/docs/tutorial/zh_CN/src/task_tool.py@@ -129,7 +129,7 @@ print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))async def example_tool_execution() -> None:"""工具调用执行示例。"""- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="123",@@ -228,7 +228,7 @@ async def example_tool_interruption() -> None:"""工具中断示例。"""toolkit = Toolkit()toolkit.register_tool_function(non_streaming_function)- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="123",@@ -286,7 +286,7 @@ async def example_streaming_tool_interruption() -> None:toolkit = Toolkit()toolkit.register_tool_function(streaming_function)- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="xxx",@@ -412,7 +412,7 @@ print(async def mock_agent_reset_tools() -> None:"""模拟智能体调用 reset_equipped_tools 函数。"""- res = await toolkit.call_tool_function(+ res = await toolkit.call_tool(ToolUseBlock(type="tool_use",id="456",diff --git a/pyproject.toml b/pyproject.tomlindex c663875c4..0d836afb3 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -38,6 +38,7 @@ dependencies = ["python-socketio","shortuuid","python-frontmatter",+ "jinja2","aiofiles","tree_sitter","tree_sitter_bash",diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.pyindex 995954f74..118e23213 100644--- a/src/agentscope/_utils/_common.py+++ b/src/agentscope/_utils/_common.py@@ -9,15 +9,12 @@ import osimport typesimport uuidfrom datetime import datetime-from typing import Any, Callable, Type, Dict+from typing import Any, Callableimport requests-from docstring_parser import parsefrom json_repair import repair_json-from pydantic import BaseModel, Field, create_model, ConfigDictfrom .._logging import logger-from ..types import ToolFunctiondef _json_loads_with_repair(@@ -147,92 +144,6 @@ def _get_bytes_from_web_url()-def _remove_title_field(schema: dict) -> None:- """Remove the title field from the JSON schema to avoid- misleading the LLM."""- # The top level title field- if "title" in schema:- schema.pop("title")-- # properties- if "properties" in schema:- for prop in schema["properties"].values():- if isinstance(prop, dict):- _remove_title_field(prop)-- # items- if "items" in schema and isinstance(schema["items"], dict):- _remove_title_field(schema["items"])-- # additionalProperties- if "additionalProperties" in schema and isinstance(- schema["additionalProperties"],- dict,- ):- _remove_title_field(- schema["additionalProperties"],- )---def _create_tool_from_base_model(- structured_model: Type[BaseModel],- tool_name: str = "generate_structured_output",-) -> Dict[str, Any]:- """Create a function tool definition from a Pydantic BaseModel.- This function converts a Pydantic BaseModel class into a tool definition- that can be used with function calling API. The resulting tool- definition includes the model's JSON schema as parameters, enabling- structured output generation by forcing the model to call this function- with properly formatted data.-- Args:- structured_model (`Type[BaseModel]`):- A Pydantic BaseModel class that defines the expected structure- for the tool's output.- tool_name (`str`, default `"generate_structured_output"`):- The tool name that used to force the LLM to generate structured- output by calling this function.-- Returns:- `Dict[str, Any]`: A tool definition dictionary compatible with- function calling API, containing type ("function") and- function dictionary with name, description, and parameters- (JSON schema).-- .. code-block:: python- :caption: Example usage-- from pydantic import BaseModel-- class PersonInfo(BaseModel):- name: str- age: int- email: str-- tool = _create_tool_from_base_model(PersonInfo, "extract_person")- print(tool["function"]["name"]) # extract_person- print(tool["type"]) # function-- .. note:: The function automatically removes the 'title' field from- the JSON schema to ensure compatibility with function calling- format. This is handled by the internal ``_remove_title_field()``- function.- """- schema = structured_model.model_json_schema()-- _remove_title_field(schema)- tool_definition = {- "type": "function",- "function": {- "name": tool_name,- "description": "Generate the required structured output with "- "this function",- "parameters": schema,- },- }- return tool_definition--def _map_text_to_uuid(text: str) -> str:"""Map the given text to a deterministic UUID string.@@ -245,122 +156,3 @@ def _map_text_to_uuid(text: str) -> str:A deterministic UUID string derived from the input text."""return str(uuid.uuid3(uuid.NAMESPACE_DNS, text))---def _parse_tool_function(- tool_func: ToolFunction,- include_long_description: bool,- include_var_positional: bool,- include_var_keyword: bool,-) -> dict:- """Extract JSON schema from the tool function's docstring-- Args:- tool_func (`ToolFunction`):- The tool function to extract the JSON schema from.- include_long_description (`bool`):- Whether to include the long description in the JSON schema.- include_var_positional (`bool`):- Whether to include variable positional arguments in the JSON- schema.- include_var_keyword (`bool`):- Whether to include variable keyword arguments in the JSON schema.-- Returns:- `dict`:- The extracted JSON schema.- """- docstring = parse(tool_func.__doc__)- params_docstring = {_.arg_name: _.description for _ in docstring.params}-- # Function description- descriptions = []- if docstring.short_description is not None:- descriptions.append(docstring.short_description)-- if include_long_description and docstring.long_description is not None:- descriptions.append(docstring.long_description)-- func_description = "\n".join(descriptions)-- # Create a dynamic model with the function signature- fields = {}- for name, param in inspect.signature(tool_func).parameters.items():- # Skip the `self` and `cls` parameters- if name in ["self", "cls"]:- continue-- # Handle `**kwargs`- if param.kind == inspect.Parameter.VAR_KEYWORD:- if not include_var_keyword:- continue-- fields[name] = (- Dict[str, Any]- if param.annotation == inspect.Parameter.empty- else Dict[str, param.annotation], # type: ignore- Field(- description=params_docstring.get(- f"**{name}",- params_docstring.get(name, None),- ),- default={}- if param.default is param.empty- else param.default,- ),- )-- elif param.kind == inspect.Parameter.VAR_POSITIONAL:- if not include_var_positional:- continue-- fields[name] = (- list[Any]- if param.annotation == inspect.Parameter.empty- else list[param.annotation], # type: ignore- Field(- description=params_docstring.get(- f"*{name}",- params_docstring.get(name, None),- ),- default=[]- if param.default is param.empty- else param.default,- ),- )-- else:- fields[name] = (- Any- if param.annotation == inspect.Parameter.empty- else param.annotation,- Field(- description=params_docstring.get(name, None),- default=...- if param.default is param.empty- else param.default,- ),- )-- base_model = create_model(- "_StructuredOutputDynamicClass",- __config__=ConfigDict(arbitrary_types_allowed=True),- **fields,- )- params_json_schema = base_model.model_json_schema()-- # Remove the title from the json schema- _remove_title_field(params_json_schema)-- func_json_schema: dict = {- "type": "function",- "function": {- "name": tool_func.__name__,- "parameters": params_json_schema,- },- }-- if func_description not in [None, ""]:- func_json_schema["function"]["description"] = func_description-- return func_json_schemadiff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.pyindex d65420dde..f7b16dfc3 100644--- a/src/agentscope/agent/__init__.py+++ b/src/agentscope/agent/__init__.py@@ -1,5 +1,6 @@# -*- coding: utf-8 -*-"""Initialize the agent module."""+from ._state import AgentStatefrom ._agent import Agent-__all__ = ["Agent"]+__all__ = ["Agent", "AgentState"]diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex dae40adda..c7356feb0 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -1,7 +1,6 @@# -*- coding: utf-8 -*-"""The unified agent class in AgentScope library."""import uuid-from dataclasses import dataclassfrom typing import AsyncGenerator, Literalfrom ..event import (@@ -29,11 +28,9 @@ from ..event import (ExternalExecutionResultEvent,UserConfirmResultEvent,)-from ..message import Msg-from ..model import ChatResponse-from ..model import ChatUsage-+from ..model import ChatResponse, ChatUsage, ChatModelBasefrom ..message import (+ Msg,TextBlock,ThinkingBlock,ToolCallBlock,@@ -43,8 +40,6 @@ from ..message import (URLSource,)-from ..model import ChatModelBase-DEFAULT_COMPRESSION_PROMPT = ("<system-hint>You have been working on the task described above but have "@@ -56,25 +51,6 @@ DEFAULT_COMPRESSION_PROMPT = ()-@dataclass-class AgentState:- """The agent state that should be saved and loaded from storage."""-- context: list[Msg]- """The uncompressed conversation context, that will be feed into the LLM"""-- reply_id: str- """The id of the current reply, which is also used as the id of the- final message of the reply."""-- cur_iter: int = 0- """The current iteration of the agent's reasoning-acting loop."""-- cur_summary: str = ""- """The current compressed summary of the context, which will be prepended- to the context when feed into the LLM."""--class Agent:"""The unified agent class in AgentScope library."""diff --git a/src/agentscope/agent/_state.py b/src/agentscope/agent/_state.pynew file mode 100644index 000000000..7b4a15054--- /dev/null+++ b/src/agentscope/agent/_state.py@@ -0,0 +1,34 @@+# -*- coding: utf-8 -*-+"""The agent state class."""+import uuid++from pydantic import BaseModel, Field++from ..message import TextBlock, DataBlock, Msg+from ..tool import PermissionContext+++class AgentState(BaseModel):+ """The agent state that should be saved and loaded from storage."""++ summary: str | list[TextBlock | DataBlock] = ""+ """The compressed summary of the context, which will be prepended to the+ context when feed into the LLM."""+ context: list[Msg] = Field(default_factory=list)+ """The uncompressed conversation context, that will be feed into the LLM"""+ reply_id: str = Field(default_factory=lambda: uuid.uuid4().hex)+ """The id of the current reply, which is also used as the id of the+ final message of the reply."""+ cur_iter: int = 0+ """The current iteration of the agent's reasoning-acting loop."""++ # The tool state, e.g. the active tool groups+ activated_groups: list[str] = Field(default_factory=list)+ """The names of the activated tool groups, each group contains a set of+ tools."""++ permission_context: PermissionContext = Field(+ default_factory=PermissionContext,+ )+ """The permission context that will be passed to the toolkit to determine+ the tool permissions."""diff --git a/src/agentscope/exception/__init__.py b/src/agentscope/exception/__init__.pyindex 49f6670d3..9a9edc47d 100644--- a/src/agentscope/exception/__init__.py+++ b/src/agentscope/exception/__init__.py@@ -1,7 +1,10 @@# -*- coding: utf-8 -*-"""The exception module in agentscope."""-from ._exception_base import AgentOrientedExceptionBase+from ._base import (+ AgentOrientedExceptionBase,+ DeveloperOrientedException,+)from ._tool import (ToolInterruptedError,ToolNotFoundError,@@ -10,6 +13,7 @@ from ._tool import (__all__ = ["AgentOrientedExceptionBase",+ "DeveloperOrientedException","ToolInterruptedError","ToolNotFoundError","ToolInvalidArgumentsError",diff --git a/src/agentscope/exception/_exception_base.py b/src/agentscope/exception/_base.pysimilarity index 71%rename from src/agentscope/exception/_exception_base.pyrename to src/agentscope/exception/_base.pyindex c00481d18..d14eaad7b 100644--- a/src/agentscope/exception/_exception_base.py+++ b/src/agentscope/exception/_base.py@@ -16,3 +16,12 @@ class AgentOrientedExceptionBase(Exception):def __str__(self) -> str:"""Return the string representation of the exception."""return f"{self.__class__.__name__}: {self.message}"+++class DeveloperOrientedException(Exception):+ """The exception should be raised to the developers."""++ def __init__(self, message: str):+ """Initialize the exception with a message."""+ super().__init__(message)+ self.message = messagediff --git a/src/agentscope/exception/_tool.py b/src/agentscope/exception/_tool.pyindex ac313d028..1ea3b2965 100644--- a/src/agentscope/exception/_tool.py+++ b/src/agentscope/exception/_tool.py@@ -1,7 +1,7 @@# -*- coding: utf-8 -*-"""The tool-related exceptions in agentscope."""-from ._exception_base import AgentOrientedExceptionBase+from ._base import AgentOrientedExceptionBaseclass ToolNotFoundError(AgentOrientedExceptionBase):diff --git a/src/agentscope/mcp/__init__.py b/src/agentscope/mcp/__init__.pyindex 1ede1344a..813bd9df1 100644--- a/src/agentscope/mcp/__init__.py+++ b/src/agentscope/mcp/__init__.py@@ -3,7 +3,6 @@the MCP servers."""from ._client_base import MCPClientBase-from ._mcp_function import MCPToolFunctionfrom ._stateful_client_base import StatefulClientBasefrom ._stdio_stateful_client import StdIOStatefulClientfrom ._http_stateless_client import HttpStatelessClient@@ -11,7 +10,6 @@ from ._http_stateful_client import HttpStatefulClient__all__ = [- "MCPToolFunction","MCPClientBase","StatefulClientBase","StdIOStatefulClient",diff --git a/src/agentscope/mcp/_client_base.py b/src/agentscope/mcp/_client_base.pyindex c9a70a627..b38d9ad84 100644--- a/src/agentscope/mcp/_client_base.py+++ b/src/agentscope/mcp/_client_base.py@@ -1,16 +1,12 @@# -*- coding: utf-8 -*-"""The base class for MCP clients in AgentScope."""from abc import abstractmethod-from typing import Callable, List+from typing import Any, TYPE_CHECKING-import mcp.types--from .._logging import logger-from ..message import (- Base64Source,- TextBlock,- DataBlock,-)+if TYPE_CHECKING:+ from ..tool import MCPTool+else:+ MCPTool = Anyclass MCPClientBase:@@ -27,59 +23,17 @@ class MCPClientBase:self.name = name@abstractmethod- async def get_callable_function(+ async def get_tool(self,- func_name: str,- wrap_tool_result: bool = True,- ) -> Callable:- """Get a tool function by its name."""-- @staticmethod- def _convert_mcp_content_to_as_blocks(- mcp_content_blocks: list,- ) -> List[TextBlock | DataBlock]:- """Convert MCP content to AgentScope blocks."""+ name: str,+ ) -> MCPTool:+ """Get a tool object by its name.- as_content: list = []- for content in mcp_content_blocks:- if isinstance(content, mcp.types.TextContent):- as_content.append(TextBlock(text=content.text))- elif isinstance(- content,- (mcp.types.ImageContent, mcp.types.AudioContent),- ):- as_content.append(- DataBlock(- source=Base64Source(- type="base64",- media_type=content.mimeType,- data=content.data,- ),- ),- )- elif isinstance(content, mcp.types.EmbeddedResource):- if isinstance(- content.resource,- mcp.types.TextResourceContents,- ):- as_content.append(- TextBlock(- text=content.resource.model_dump_json(indent=2),- ),- )- else:- # TODO: support the BlobResourceContents in the future,- # which is a base64-encoded string representing the- # binary data- logger.error(- "Unsupported EmbeddedResource content type: %s. "- "Skipping this content.",- type(content.resource),- )+ Args:+ name (`str`):+ The name of the tool to get.- else:- logger.warning(- "Unsupported content type: %s. Skipping this content.",- type(content),- )- return as_content+ Returns:+ `MCPTool`:+ A tool object that implements ToolProtocol.+ """diff --git a/src/agentscope/mcp/_http_stateless_client.py b/src/agentscope/mcp/_http_stateless_client.pyindex dbeab5686..3e2b43ff3 100644--- a/src/agentscope/mcp/_http_stateless_client.py+++ b/src/agentscope/mcp/_http_stateless_client.py@@ -1,16 +1,19 @@# -*- coding: utf-8 -*-"""The MCP streamable HTTP server."""from contextlib import _AsyncGeneratorContextManager-from typing import Any, Callable, Awaitable, Literal, List+from typing import Any, Literal, List, TYPE_CHECKINGimport mcp.typesfrom mcp import ClientSessionfrom mcp.client.sse import sse_clientfrom mcp.client.streamable_http import streamable_http_client-from . import MCPToolFunctionfrom ._client_base import MCPClientBase-from ..tool import ToolResponse++if TYPE_CHECKING:+ from ..tool import MCPTool+else:+ MCPTool = Anyclass HttpStatelessClient(MCPClientBase):@@ -89,29 +92,26 @@ class HttpStatelessClient(MCPClientBase):"Supported types are 'sse' and 'streamable_http'.",)- async def get_callable_function(+ async def get_tool(self,- func_name: str,- wrap_tool_result: bool = True,+ name: str,execution_timeout: float | None = None,- ) -> Callable[..., Awaitable[mcp.types.CallToolResult | ToolResponse]]:- """Get a tool function by its name.+ ) -> MCPTool:+ """Get a tool object by its name.++ The returned MCPTool object implements ToolProtocol and can be:+ - Called directly: `await tool(arg1=val1)`+ - Registered to toolkit: `toolkit.register_tool(tool)`Args:- func_name (`str`):+ name (`str`):The name of the tool function.- wrap_tool_result (`bool`, defaults to `True`):- Whether to wrap the tool result into agentscope's- `ToolResponse` object. If `False`, the raw result type- `mcp.types.CallToolResult` will be returned.execution_timeout (`float | None`, optional):The preset timeout in seconds for calling the tool function.Returns:- `Callable[..., Awaitable[mcp.types.CallToolResult | \- ToolResponse]]`:- An async tool function that returns either- `mcp.types.CallToolResult` or `ToolResponse` when called.+ `MCPTool`:+ A tool object that implements ToolProtocol."""if self._tools is None:@@ -119,19 +119,20 @@ class HttpStatelessClient(MCPClientBase):target_tool = Nonefor tool in self._tools:- if tool.name == func_name:+ if tool.name == name:target_tool = toolbreakif target_tool is None:raise ValueError(- f"Tool '{func_name}' not found in the MCP server ",+ f"Tool '{name}' not found in the MCP server ",)- return MCPToolFunction(+ from ..tool import MCPTool++ return MCPTool(mcp_name=self.name,tool=target_tool,- wrap_tool_result=wrap_tool_result,client_gen=self.get_client,timeout=execution_timeout,)diff --git a/src/agentscope/mcp/_mcp_function.py b/src/agentscope/mcp/_mcp_function.pydeleted file mode 100644index d205a1e5b..000000000--- a/src/agentscope/mcp/_mcp_function.py+++ /dev/null@@ -1,137 +0,0 @@-# -*- coding: utf-8 -*--"""The MCP tool function class in AgentScope."""-from contextlib import _AsyncGeneratorContextManager-from datetime import timedelta-from typing import Any, Callable--import mcp-from mcp import ClientSession, Tool--from ._client_base import MCPClientBase-from ..tool import ToolResponse---def _extract_json_schema_from_mcp_tool(tool: Tool) -> dict[str, Any]:- """Extract JSON schema from MCP tool."""-- return {- "type": "function",- "function": {- "name": tool.name,- "description": tool.description,- "parameters": {- "type": "object",- "properties": tool.inputSchema.get(- "properties",- {},- ),- "required": tool.inputSchema.get(- "required",- [],- ),- },- },- }---class MCPToolFunction:- """An MCP tool function class that can be called directly."""-- name: str- """The name of the tool function."""-- description: str- """The description of the tool function."""-- json_schema: dict[str, Any]- """JSON schema of the tool function"""-- def __init__(- self,- mcp_name: str,- tool: mcp.types.Tool,- wrap_tool_result: bool,- client_gen: Callable[..., _AsyncGeneratorContextManager[Any]]- | None = None,- session: ClientSession | None = None,- timeout: float | None = None,- ) -> None:- """Initialize the MCP function.-- Args:- mcp_name (`str`):- The name of the MCP instance.- tool (`mcp.types.Tool`):- The MCP tool definition.- wrap_tool_result (`bool`):- Whether to wrap the tool result into `ToolResponse` in- AgentScope.- client_gen (`Callable[..., _AsyncGeneratorContextManager[Any]] | \- None`, *optional*):- The MCP client generator function. Either this or `session`- must be provided.- session (`ClientSession | None`, *optional*):- The MCP client session. Either this or `client_gen` must be- provided.- timeout (`float | None`, *optional*):- The timeout in seconds for tool execution. If not provided,- no timeout will be set.- """- self.mcp_name = mcp_name- self.name = tool.name- self.description = tool.description- self.json_schema = _extract_json_schema_from_mcp_tool(tool)- self.wrap_tool_result = wrap_tool_result-- if timeout:- self.timeout = timedelta(seconds=timeout)- else:- self.timeout = None-- # Cannot be None at the same time- if (- client_gen is None- and session is None- or (client_gen is not None and session is not None)- ):- raise ValueError(- "Either client or session must be provided, but not both.",- )-- self.client_gen = client_gen- self.session = session-- async def __call__(- self,- **kwargs: Any,- ) -> mcp.types.CallToolResult | ToolResponse:- """Call the MCP tool function with the given arguments, and return- the result."""- if self.client_gen:- async with self.client_gen() as cli:- read_stream, write_stream = cli[0], cli[1]- async with ClientSession(read_stream, write_stream) as session:- await session.initialize()- res = await session.call_tool(- self.name,- arguments=kwargs,- read_timeout_seconds=self.timeout,- )-- else:- res = await self.session.call_tool(- self.name,- arguments=kwargs,- read_timeout_seconds=self.timeout,- )-- if self.wrap_tool_result:- as_content = MCPClientBase._convert_mcp_content_to_as_blocks(- res.content,- )- return ToolResponse(- content=as_content,- metadata=res.meta,- )-- return resdiff --git a/src/agentscope/mcp/_stateful_client_base.py b/src/agentscope/mcp/_stateful_client_base.pyindex 03c96db41..97a150c9d 100644--- a/src/agentscope/mcp/_stateful_client_base.py+++ b/src/agentscope/mcp/_stateful_client_base.py@@ -3,15 +3,19 @@functionality for stateful MCP clients."""from abc import ABCfrom contextlib import AsyncExitStack-from typing import List+from typing import List, TYPE_CHECKING, Anyimport mcpfrom mcp import ClientSessionfrom ._client_base import MCPClientBase-from ._mcp_function import MCPToolFunctionfrom .._logging import logger+if TYPE_CHECKING:+ from ..tool import MCPTool+else:+ MCPTool = Any+class StatefulClientBase(MCPClientBase, ABC):"""The base class for stateful MCP clients in AgentScope, which maintains@@ -109,33 +113,26 @@ class StatefulClientBase(MCPClientBase, ABC):self._cached_tools = res.toolsreturn res.tools- async def get_callable_function(+ async def get_tool(self,- func_name: str,- wrap_tool_result: bool = True,+ name: str,execution_timeout: float | None = None,- ) -> MCPToolFunction:- """Get an async tool function from the MCP server by its name, so- that you can call it directly, wrap it into your own function, or- anyway you like.+ ) -> MCPTool:+ """Get a tool object from the MCP server by its name.- .. note:: Currently, only the text, image, and audio results are- supported in this function.+ The returned MCPTool object implements ToolProtocol and can be:+ - Called directly: `await tool(arg1=val1)`+ - Registered to toolkit: `toolkit.register_tool(tool)`Args:- func_name (`str`):+ name (`str`):The name of the tool function to get.- wrap_tool_result (`bool`):- Whether to wrap the tool result into agentscope's- `ToolResponse` object. If `False`, the raw result type- `mcp.types.CallToolResult` will be returned.execution_timeout (`float | None`, optional):The preset timeout in seconds for calling the tool function.Returns:- `MCPToolFunction`:- A callable async function that returns either- `mcp.types.CallToolResult` or `ToolResponse` when called.+ `MCPTool`:+ A tool object that implements ToolProtocol."""self._validate_connection()@@ -144,19 +141,20 @@ class StatefulClientBase(MCPClientBase, ABC):target_tool = Nonefor tool in self._cached_tools:- if tool.name == func_name:+ if tool.name == name:target_tool = toolbreakif target_tool is None:raise ValueError(- f"Tool '{func_name}' not found in the MCP server",+ f"Tool '{name}' not found in the MCP server",)- return MCPToolFunction(+ from ..tool import MCPTool++ return MCPTool(mcp_name=self.name,tool=target_tool,- wrap_tool_result=wrap_tool_result,session=self.session,timeout=execution_timeout,)diff --git a/src/agentscope/model/_anthropic_model.py b/src/agentscope/model/_anthropic_model.pyindex 744c7526e..ab8e5359f 100644--- a/src/agentscope/model/_anthropic_model.py+++ b/src/agentscope/model/_anthropic_model.py@@ -17,8 +17,9 @@ from ._model_response import ChatResponsefrom ._model_usage import ChatUsagefrom ..formatter import FormatterBase, AnthropicChatFormatterfrom ..message import TextBlock, ToolCallBlock, ThinkingBlock+from ..tool import ToolChoicefrom ..tracing import trace_llm-from ..types import JSONSerializableObject, ToolChoice+from ..types import JSONSerializableObjectif TYPE_CHECKING:from anthropic.types.message import Messagediff --git a/src/agentscope/model/_dashscope_model.py b/src/agentscope/model/_dashscope_model.pyindex 255448e76..dc6ab55c6 100644--- a/src/agentscope/model/_dashscope_model.py+++ b/src/agentscope/model/_dashscope_model.py@@ -21,8 +21,9 @@ from ._model_response import ChatResponsefrom ._model_usage import ChatUsagefrom ..formatter import FormatterBase, DashScopeChatFormatterfrom ..message import TextBlock, ToolCallBlock, ThinkingBlock, Msg+from ..tool import ToolChoicefrom ..tracing import trace_llm-from ..types import JSONSerializableObject, ToolChoice+from ..types import JSONSerializableObjectfrom .._logging import loggerdiff --git a/src/agentscope/model/_gemini_model.py b/src/agentscope/model/_gemini_model.pyindex e5d2bd33e..087144173 100644--- a/src/agentscope/model/_gemini_model.py+++ b/src/agentscope/model/_gemini_model.py@@ -22,7 +22,8 @@ from ._model_usage import ChatUsagefrom ._model_base import ChatModelBasefrom ._model_response import ChatResponsefrom ..tracing import trace_llm-from ..types import JSONSerializableObject, ToolChoice+from ..types import JSONSerializableObject+from ..tool import ToolChoiceif TYPE_CHECKING:from google.genai.types import GenerateContentResponsediff --git a/src/agentscope/model/_model_base.py b/src/agentscope/model/_model_base.pyindex 7553e2057..3a5de8de4 100644--- a/src/agentscope/model/_model_base.py+++ b/src/agentscope/model/_model_base.py@@ -2,13 +2,17 @@"""The chat model base class."""from abc import abstractmethod-from typing import AsyncGenerator, Any+from typing import AsyncGenerator, Any, TYPE_CHECKINGfrom ._model_response import ChatResponsefrom .._logging import loggerfrom ..formatter import FormatterBasefrom ..message import Msg-from ..types import ToolChoice++if TYPE_CHECKING:+ from ..tool import ToolChoice+else:+ ToolChoice = Any_TOOL_CHOICE_MODES = ["auto", "none", "required"]diff --git a/src/agentscope/model/_openai_model.py b/src/agentscope/model/_openai_model.pyindex 1b6da8fb7..e1a9c266e 100644--- a/src/agentscope/model/_openai_model.py+++ b/src/agentscope/model/_openai_model.py@@ -25,8 +25,9 @@ from ..message import (DataBlock,ToolCallBlock,)+from ..tool import ToolChoicefrom ..tracing import trace_llm-from ..types import JSONSerializableObject, ToolChoice+from ..types import JSONSerializableObjectif TYPE_CHECKING:from openai.types.chat import ChatCompletiondiff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.pyindex 74c17257f..a9d4c1906 100644--- a/src/agentscope/tool/__init__.py+++ b/src/agentscope/tool/__init__.py@@ -1,8 +1,11 @@# -*- coding: utf-8 -*-"""The tool module in agentscope."""-from ._response import ToolResponse+from ._types import ToolChoice, Function+from ._response import ToolResponse, ToolChunkfrom ._toolkit import Toolkit+from ._base import ToolBase+from ._adapters import MCPToolfrom ._permission import (PermissionContext,AdditionalWorkingDirectory,@@ -24,4 +27,9 @@ __all__ = ["PermissionRule","PermissionMode","PermissionBehavior",+ "ToolChunk",+ "ToolBase",+ "MCPTool",+ "ToolChoice",+ "Function",]diff --git a/src/agentscope/tool/_adapters.py b/src/agentscope/tool/_adapters.pynew file mode 100644index 000000000..ea409dd7c--- /dev/null+++ b/src/agentscope/tool/_adapters.py@@ -0,0 +1,300 @@+# -*- coding: utf-8 -*-+"""Adapters to convert functions and MCP tools to ToolProtocol."""+import inspect+from contextlib import _AsyncGeneratorContextManager+from datetime import timedelta+from typing import Callable, Any, AsyncGenerator++from mcp import ClientSession+import mcp++from ._types import Function+from ._base import ToolBase+from ._permission import (+ PermissionBehavior,+ PermissionDecision,+)+from ._response import ToolChunk+from ._utils import _extract_func_description, _extract_input_schema+from .._logging import logger+from ..message import TextBlock, DataBlock, Base64Source, URLSource+++class _FunctionTool(ToolBase):+ """Adapter to convert a Python function to ToolProtocol.++ 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+ AsyncGenerator[ToolChunk, None].+ """++ def __init__(+ self,+ func: Function,+ name: str | None = None,+ description: str | None = None,+ is_concurrency_safe: bool = True,+ is_read_only: bool = False,+ ):+ """Initialize the FunctionTool.++ Args:+ func (`Callable`):+ The Python function to wrap.+ name (`str | None`, optional):+ Custom tool name. If None, uses the function name.+ description (`str | None`, optional):+ Custom tool description. If None, extracts from docstring.+ is_concurrency_safe (`bool`, optional):+ Whether this tool is safe to call concurrently.+ is_read_only (`bool`, optional):+ Whether this tool only reads data without side effects.+ """+ self.name = name or func.__name__+ self.description = description or _extract_func_description(+ func.__doc__ or "",+ )+ self.input_schema = _extract_input_schema(func)+ self.is_concurrency_safe = is_concurrency_safe+ self.is_read_only = is_read_only+ self.is_mcp = False+ self._func = func++ async def check_permissions(+ self,+ *_args: Any,+ **_kwargs: Any,+ ) -> PermissionDecision:+ """Check permissions for the tool usage.++ Default implementation allows all operations.++ Returns:+ `PermissionDecision`:+ Permission decision (default: allowed).+ """+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="Custom function tools must be explicitly allowed "+ "by the user.",+ )++ async def __call__(+ self,+ **kwargs: Any,+ ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:+ """Invoke the wrapped function in an async style.++ Returns:+ `ToolChunk` or `AsyncGenerator[ToolChunk, None]`:+ The normalized result of the function execution.+ """+ if inspect.iscoroutinefunction(self._func):+ result = await self._func(**kwargs)+ else:+ result = self._func(**kwargs)++ return result+++class MCPTool(ToolBase):+ """Adapter to convert an MCP tool to ToolProtocol.++ This class wraps an MCP tool and makes it compatible with the ToolProtocol+ interface. It handles the conversion between MCP's result format and+ AgentScope's ToolChunk format.+ """++ is_mcp: bool = True+ """Whether this tool is an MCP tool."""++ def __init__(+ self,+ mcp_name: str,+ tool: Any,+ client_gen: Callable[..., _AsyncGeneratorContextManager[Any]]+ | None = None,+ session: Any | None = None,+ timeout: float | None = None,+ ):+ """Initialize the MCPTool.++ Args:+ mcp_name (`str`):+ The name of the MCP server instance.+ tool (`mcp.types.Tool`):+ The MCP tool definition.+ client_gen (`Callable[..., _AsyncGeneratorContextManager[Any]] \+ | None`, optional):+ The MCP client generator function for stateless clients.+ Either this or ``session`` must be provided.+ session (`mcp.ClientSession | None`, optional):+ The MCP client session for stateful clients.+ Either this or ``client_gen`` must be provided.+ timeout (`float | None`, optional):+ The timeout in seconds for tool execution.+ """+ self.mcp_name = mcp_name+ self.name = tool.name+ self.description = tool.description or ""++ # Extract input schema+ self.input_schema = {+ "type": "object",+ "properties": tool.inputSchema.get("properties", {}),+ "required": tool.inputSchema.get("required", []),+ }++ self.is_concurrency_safe = True++ # Extract is_read_only from MCP tool annotations+ self.is_read_only = False+ if tool.annotations and hasattr(tool.annotations, "readOnlyHint"):+ self.is_read_only = tool.annotations.readOnlyHint or False++ # Store MCP tool and connection info+ self._tool = tool+ self._client_gen = client_gen+ self._session = session++ if timeout:+ self._timeout = timedelta(seconds=timeout)+ else:+ self._timeout = None++ # Validate that either client_gen or session is provided+ if (client_gen is None and session is None) or (+ client_gen is not None and session is not None+ ):+ raise ValueError(+ "Either client_gen or session must be provided, but not both.",+ )++ async def check_permissions(+ self,+ *_args: Any,+ **_kwargs: Any,+ ) -> PermissionDecision:+ """Check permissions for the MCP tool usage.++ Default implementation allows all operations.++ Returns:+ `PermissionDecision`:+ Permission decision (default: ask for confirmation).+ """+ if self.is_read_only:+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="This is a read-only MCP tool. Allowing execution.",+ )+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="MCP tools must be explicitly allowed by the user.",+ )++ async def __call__(+ self,+ **kwargs: Any,+ ) -> ToolChunk:+ """Invoke the MCP tool and convert the result to ToolChunk.++ Args:+ **kwargs: Arguments to pass to the MCP tool.++ Returns:+ `ToolChunk`: The converted tool execution result.+ """++ # Call the MCP tool+ if self._client_gen:+ # Stateless client: create temporary session+ async with self._client_gen() as cli:+ read_stream, write_stream = cli[0], cli[1]+ async with ClientSession(read_stream, write_stream) as session:+ await session.initialize()+ result = await session.call_tool(+ self.name,+ arguments=kwargs,+ read_timeout_seconds=self._timeout,+ )+ else:+ # Stateful client: use existing session+ result = await self._session.call_tool(+ self.name,+ arguments=kwargs,+ read_timeout_seconds=self._timeout,+ )++ # Convert MCP result to AgentScope blocks+ return ToolChunk(+ content=self._convert_mcp_content_to_blocks(result.content),+ state="error" if result.isError else "running",+ )++ @staticmethod+ def _convert_mcp_content_to_blocks(+ mcp_content_blocks: list,+ ) -> list[TextBlock | DataBlock]:+ """Convert MCP content to AgentScope blocks.++ Args:+ mcp_content_blocks (`list`):+ The MCP content blocks to convert.++ Returns:+ `list[TextBlock | DataBlock]`: Converted AgentScope blocks.+ """++ as_content = []+ for content in mcp_content_blocks:+ if isinstance(content, mcp.types.TextContent):+ as_content.append(TextBlock(text=content.text))+ elif isinstance(+ content,+ (mcp.types.ImageContent, mcp.types.AudioContent),+ ):+ as_content.append(+ DataBlock(+ source=Base64Source(+ type="base64",+ media_type=content.mimeType,+ data=content.data,+ ),+ ),+ )++ elif isinstance(content, mcp.types.EmbeddedResource):+ if isinstance(+ content.resource,+ mcp.types.TextResourceContents,+ ):+ as_content.append(+ TextBlock(+ text=content.resource.model_dump_json(indent=2),+ ),+ )+ else:+ logger.error(+ "Unsupported EmbeddedResource content type: %s. "+ "Skipping this content.",+ type(content.resource),+ )++ elif isinstance(content, mcp.types.ResourceContents):+ as_content.append(+ DataBlock(+ source=URLSource(+ media_type=content.mimeType,+ url=content.uri,+ ),+ ),+ )++ else:+ logger.warning(+ "Unsupported content type: %s. Skipping this content.",+ type(content),+ )+ return as_contentdiff --git a/src/agentscope/tool/_async_wrapper.py b/src/agentscope/tool/_async_wrapper.pydeleted file mode 100644index 20edd40a6..000000000--- a/src/agentscope/tool/_async_wrapper.py+++ /dev/null@@ -1,109 +0,0 @@-# -*- coding: utf-8 -*--"""The functions that wrap object, sync generator, and async generator-into async generators.--TODO: handle the exception raised when yielding from async generator- into a normal ToolResponse instance.-"""-import asyncio-from typing import AsyncGenerator, Generator, Callable, Awaitable--from ._response import ToolResponse-from ..message import TextBlock-from .._utils._common import _execute_async_or_sync_func---async def _postprocess_tool_response(- tool_response: ToolResponse,- postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- )- | None,-) -> ToolResponse:- """Post-process a ToolResponse object with the given function.-- Supports both sync and async postprocess_func.- """- if postprocess_func:- processed_response = await _execute_async_or_sync_func(- postprocess_func,- tool_response,- )- if processed_response:- return processed_response- return tool_response---async def _object_wrapper(- obj: ToolResponse,- postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- )- | None,-) -> AsyncGenerator[ToolResponse, None]:- """Wrap a ToolResponse object to an async generator."""- yield await _postprocess_tool_response(obj, postprocess_func)---async def _sync_generator_wrapper(- sync_generator: Generator[ToolResponse, None, None],- postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- )- | None,-) -> AsyncGenerator[ToolResponse, None]:- """Wrap a sync generator to an async generator."""- for chunk in sync_generator:- yield await _postprocess_tool_response(chunk, postprocess_func)---async def _async_generator_wrapper(- async_func: AsyncGenerator[ToolResponse, None],- postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- )- | None,-) -> AsyncGenerator[ToolResponse, None]:- """When the function is interrupted during generating the tool- response, add an interrupted message to the response, and postpone- the CancelledError to the caller."""-- last_chunk = None- try:- async for chunk in async_func:- processed_chunk = await _postprocess_tool_response(- chunk,- postprocess_func,- )- yield processed_chunk- last_chunk = processed_chunk-- except asyncio.CancelledError:- interrupted_info = TextBlock(- type="text",- text="<system-info>"- "The tool call has been interrupted by the user."- "</system-info>",- )- if last_chunk:- last_chunk.content.append(interrupted_info)- last_chunk.is_interrupted = True- last_chunk.is_last = True- yield await _postprocess_tool_response(- last_chunk,- postprocess_func,- )-- else:- yield await _postprocess_tool_response(- ToolResponse(- content=[interrupted_info],- is_interrupted=True,- is_last=True,- ),- postprocess_func,- )diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.pynew file mode 100644index 000000000..9c1be0822--- /dev/null+++ b/src/agentscope/tool/_base.py@@ -0,0 +1,44 @@+# -*- coding: utf-8 -*-+"""The tool protocol in agentscope."""+from abc import abstractmethod, ABC+from typing import AsyncGenerator, Any++from ._permission import PermissionContext, PermissionDecision+from ._response import ToolChunk+++class ToolBase(ABC):+ """The tool protocol."""++ name: str+ """The name presented to the agent."""+ description: str+ """The agent-oriented tool description."""+ input_schema: dict[str, Any]+ """The input schema of the tool, following JSON schema format."""+ is_concurrency_safe: bool+ """If this tool is concurrency safe."""+ is_read_only: bool+ """If this tool is read-only, which will be used in the permission+ checking."""+ is_mcp: bool+ """If this tool is an MCP tool, which will be used in the permission"""+ mcp_name: str | None = None+ """The name of the MCP server this tool belongs to, which is required if+ this tool is an MCP tool."""++ @abstractmethod+ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Check permissions for the tool usage."""++ @abstractmethod+ async def __call__(+ self,+ *args: Any,+ **kwargs: Any,+ ) -> ToolChunk | AsyncGenerator[ToolChunk, None]:+ """Invoke the tool with the given arguments."""diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.pynew file mode 100644index 000000000..34dedf851--- /dev/null+++ b/src/agentscope/tool/_builtin/__init__.py@@ -0,0 +1,6 @@+# -*- coding: utf-8 -*-+"""The builtin tools in agentscope."""++from ._meta import ResetTools++__all__ = ["ResetTools"]diff --git a/src/agentscope/tool/_builtin/_meta.py b/src/agentscope/tool/_builtin/_meta.pynew file mode 100644index 000000000..33630491f--- /dev/null+++ b/src/agentscope/tool/_builtin/_meta.py@@ -0,0 +1,123 @@+# -*- coding: utf-8 -*-+"""The meta tool class."""+from typing import Any, TYPE_CHECKING++from pydantic import Field, create_model+from jinja2 import Template++from .._permission import (+ PermissionContext,+ PermissionDecision,+ PermissionBehavior,+)+from .._response import ToolChunk+from .._base import ToolBase+from .._types import ToolGroup+from ...message import TextBlock+++if TYPE_CHECKING:+ from ...agent import AgentState+else:+ AgentState = "AgentState"+++class ResetTools(ToolBase):+ """A meta tool allows agent to self-manage its equipped tools by+ activating or deactivating tool groups dynamically."""++ name: str = "reset_tools"+ description: str = (+ "This tool allows you to reset your equipped tools based on your "+ "current task requirements. These tools are organized into different "+ "groups, and you can activate/deactivate them by specifying the "+ "boolean values for each group in the input.\n\n"+ "**Important: The input booleans are the final state of their "+ "corresponding tool groups, not incremental changes.** Any group not "+ "explicitly set to True will be deactivated, regardless of its "+ "previous state.\n\n"+ "**Best practice**: Actively manage your tool groups——activate only "+ "what you need for the current task, and promptly deactivate groups "+ "as soon as they are no longer needed to conserve context space.\n\n"+ "This tool will return the usage instructions for the activated tool "+ "groups, which you **MUST pay attention to and follow**. You can "+ "also reuse this tool to re-check the instructions."+ )+ is_mcp: bool = False+ is_read_only: bool = False+ is_concurrency_safe: bool = True++ def __init__(+ self,+ groups: dict[str, ToolGroup],+ response_template: str,+ ) -> None:+ """Initialize the meta tool with the current tool groups."""+ self.groups = groups+ self.response_template = response_template++ @property+ def input_schema(self) -> dict[str, Any]: # type: ignore[override]+ """Dynamically generate the input schema based on the current+ available tool groups."""+ fields = {}+ for group_name, group in self.groups.items():+ if group_name == "basic":+ continue+ fields[group_name] = (+ bool,+ Field(+ default=False,+ description=group.description,+ ),+ )++ model = create_model("_DynamicModel", **fields)+ schema = model.model_json_schema()+ return schema++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """The meta tool is always allowed to be called."""+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="The meta tool is always allowed to be called.",+ )++ async def __call__(self, state: AgentState, **kwargs: Any) -> ToolChunk:+ """Activate or deactivate tool groups based on the input arguments,+ and return their usage instructions."""+ # Deactivate all tool groups first+ state.activated_groups.clear()++ to_activate = []+ for key, value in kwargs.items():+ if not isinstance(value, bool):+ return ToolChunk(+ content=[+ TextBlock(+ text=f"Invalid arguments: the argument {key} "+ f"should be a bool value, but got {type(value)}.",+ ),+ ],+ )++ if value:+ to_activate.append(key)++ state.activated_groups.extend(to_activate)++ template = Template(self.response_template)+ activated_groups = [+ self.groups[_] for _ in to_activate if _ in self.groups+ ]+ return ToolChunk(+ content=[+ TextBlock(+ text=template.render(groups=activated_groups),+ ),+ ],+ )diff --git a/src/agentscope/tool/_permission/_context.py b/src/agentscope/tool/_permission/_context.pyindex 9093c66da..dd46e57f8 100644--- a/src/agentscope/tool/_permission/_context.py+++ b/src/agentscope/tool/_permission/_context.py@@ -28,7 +28,7 @@ class PermissionContext(BaseModel):permission rules organized by behavior type (allow, deny, ask)."""- mode: PermissionMode+ mode: PermissionMode = PermissionMode.DEFAULT"""The current permission mode."""working_directories: dict[str, AdditionalWorkingDirectory] = Field(diff --git a/src/agentscope/tool/_response.py b/src/agentscope/tool/_response.pyindex 77ab38188..5ecb8bcf4 100644--- a/src/agentscope/tool/_response.py+++ b/src/agentscope/tool/_response.py@@ -1,31 +1,138 @@# -*- coding: utf-8 -*-"""The tool response class."""import uuid-from dataclasses import dataclass, field-from typing import Optional, List+from typing import List, Literal, Self-from ..message import DataBlock, TextBlock+from pydantic import BaseModel, Field+from ..message import DataBlock, TextBlock, Base64Source-@dataclass-class ToolResponse:- """The result chunk of a tool call."""++class ToolChunk(BaseModel):+ """The tool result chunk from a tool execution."""content: List[TextBlock | DataBlock]- """The execution output of the tool function."""+ """The chunk data blocks, note for one multimodal data, the DataBlock+ instance should have the same block id, so that the agent can group them+ together."""++ state: Literal["error", "interrupted", "running"] = "running"+ """The execution state of the tool chunk."""++ is_last: bool = True+ """Whether this is the last response in a stream tool execution."""- metadata: Optional[dict] = None+ metadata: dict = Field(default_factory=dict)"""The metadata to be accessed within the agent, so that we don't need toparse the tool result block."""- stream: bool = False- """Whether the tool output is streamed."""+ id: str = Field(default_factory=lambda: uuid.uuid4().hex)+ """The identity of the tool response."""+- is_last: bool = True- """Whether this is the last response in a stream tool execution."""+class ToolResponse(BaseModel):+ """The tool response from a tool execution, which contains the completed+ tool result (compared to ToolChunk)."""- is_interrupted: bool = False- """Whether the tool execution is interrupted."""+ content: List[TextBlock | DataBlock] = Field(default_factory=list)+ """The completed tool result data blocks."""- id: str = field(default_factory=lambda: uuid.uuid4().hex)+ state: Literal["error", "interrupted", "finished"] = "finished"+ """The execution state of the tool response."""++ metadata: dict = Field(default_factory=dict)+ """The metadata to be accessed within the agent, so that we don't need to+ parse the tool result block."""++ id: str = Field(default_factory=lambda: uuid.uuid4().hex)"""The identity of the tool response."""++ def append_chunk(self, chunk: ToolChunk) -> Self:+ """Append a tool chunk to the current tool response, accumulate the+ data blocks and update the state and metadata."""++ # Update content blocks+ current_ids_to_index = {+ _.id: index for index, _ in enumerate(self.content)+ }+ for chunk_block in chunk.content:+ if chunk_block.id in current_ids_to_index:+ # Append to the existing block+ target_block = self.content[+ current_ids_to_index[chunk_block.id]+ ]++ if isinstance(target_block, TextBlock) and isinstance(+ chunk_block,+ TextBlock,+ ):+ target_block.text += chunk_block.text+ elif isinstance(target_block, DataBlock) and isinstance(+ chunk_block,+ DataBlock,+ ):+ if isinstance(+ target_block.source,+ Base64Source,+ ) and isinstance(chunk_block.source, Base64Source):+ # Accumulate the base64 data+ target_block.source.data += chunk_block.source.data+ # Update the newest media type and name if provided+ target_block.name = (+ chunk_block.name or target_block.name+ )+ target_block.source.media_type = (+ chunk_block.source.media_type+ or target_block.source.media_type+ )+ else:+ raise ValueError(+ "Cannot append DataBlock with URL source or "+ f"different source types: {target_block.source} "+ f"vs {chunk_block.source}",+ )+ else:+ # For different block types with the same ID, we just+ # append the new block with a new ID to avoid the conflict+ new_chunk_block = chunk_block.model_copy(deep=True)+ new_chunk_block.id = uuid.uuid4().hex+ self.content.append(new_chunk_block)++ else:+ # Append a copy to avoid modifying the original chunk+ self.content.append(chunk_block.model_copy(deep=True))++ # Update the index mapping for the new block+ current_ids_to_index[chunk_block.id] = len(self.content) - 1++ # Update id, state and metadata+ # TODO: what's the relationship between the chunk id and response id?+ # Only reserve the failure state and keep the previous state if not+ # worse.+ if chunk.state == "error":+ self.state = "error"+ elif chunk.state == "interrupted":+ self.state = "interrupted"++ self.metadata.update(chunk.metadata)++ # Post-processing: merge consecutive TextBlocks+ # DataBlocks are kept separate and only merged by explicit id matching+ merged_content: List[TextBlock | DataBlock] = []+ for block in self.content:+ if isinstance(block, TextBlock) and merged_content:+ # Check if the last block is also a TextBlock+ last_block = merged_content[-1]+ if isinstance(last_block, TextBlock):+ # Merge consecutive TextBlocks+ last_block.text += block.text+ else:+ # Last block is DataBlock, append current TextBlock+ merged_content.append(block)+ else:+ # First block or current block is DataBlock+ merged_content.append(block)++ self.content = merged_content++ return selfdiff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.pyindex 87e2c6bdd..59ffaca82 100644--- a/src/agentscope/tool/_toolkit.py+++ b/src/agentscope/tool/_toolkit.py@@ -1,43 +1,36 @@# -*- coding: utf-8 -*--"""The toolkit class for tool calls in agentscope.--TODO: We should consider to split this `Toolkit` class in the future.-"""-# pylint: disable=too-many-lines+"""The toolkit class for tool calls in AgentScope."""import asyncioimport inspectimport os+from collections import OrderedDictfrom copy import deepcopy-from functools import partial, wraps+from functools import wrapsfrom typing import (AsyncGenerator,- Literal,Any,Type,Generator,Callable,- Awaitable,Coroutine,+ TYPE_CHECKING,)import mcp-import shortuuidfrom pydantic import (BaseModel,Field,create_model,)-from ._async_wrapper import (- _async_generator_wrapper,- _object_wrapper,- _sync_generator_wrapper,-)-from ._response import ToolResponse-from ._types import ToolGroup, AgentSkill, RegisteredToolFunction-from .._utils._common import _parse_tool_function+from ._builtin import ResetTools+from ._base import ToolBase+from ._adapters import _FunctionTool+from ._response import ToolResponse, ToolChunk+from ._types import ToolGroup, AgentSkill, RegisteredTool+from .._utils._common import _json_loads_with_repair+from ..exception import DeveloperOrientedExceptionfrom ..mcp import (- MCPToolFunction,MCPClientBase,StatefulClientBase,)@@ -45,13 +38,13 @@ from ..message import (ToolCallBlock,TextBlock,)-from ..types import (- JSONSerializableObject,- ToolFunction,-)-from ..tracing._trace import trace_toolkitfrom .._logging import logger+if TYPE_CHECKING:+ from ..agent import AgentState+else:+ AgentState = "AgentState"+def _apply_middlewares(func: Callable[@@ -113,7 +106,15 @@ def _apply_middlewares(return wrapper-class Toolkit: # pylint: disable=too-many-public-methods+# pylint: disable=line-too-long+DEFAULT_META_TOOL_RESPONSE_TEMPLATE = """{% if groups | length == 0 %}All tool groups are currently deactivated.{% else %}The currently activated tool group(s): {{ groups | map(attribute='name') | join(', ') }}.{% if groups | selectattr('instructions', 'ne', None) | list | length > 0 %}+<tool-instructions>+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.+{% for group in groups %}{% if group.instructions %}<group name="{{ group.name }}">{{ group.instructions }}</group>{% endif %}{% endfor %}+</tool-instructions>{% endif %}{% endif %}""" # noqa: E501+++class Toolkit:"""Toolkit is the core module to register, manage and delete toolfunctions, MCP clients, Agent skills in AgentScope.@@ -148,14 +149,38 @@ class Toolkit: # pylint: disable=too-many-public-methods{description}Check "{dir}/SKILL.md" for how to use this skill"""+ def _get_meta_tool_schema(self) -> Type[BaseModel]:+ """Get the meta tool schema based on the current tool groups."""+ fields = {}+ for group_name, group in self.groups.items():+ if group_name == "basic":+ continue+ fields[group_name] = (+ bool,+ Field(+ default=False,+ description=group.description,+ ),+ )+ return create_model("_DynamicModel", **fields)+def __init__(self,+ tools: list[ToolBase] | None = None,+ meta_tool_response_template: str = DEFAULT_META_TOOL_RESPONSE_TEMPLATE,+ mcp_tool_name: str = "mcp__{server}__{tool}",agent_skill_instruction: str | None = None,agent_skill_template: str | None = None,) -> None:"""Initialize the toolkit.Args:+ tools (`list[ToolProtocol] | None`, optional):+ The tool objects that implement the ToolProtocol interface.+ meta_tool_response_template (`str`, optional):+ The template for meta tool responses.+ mcp_tool_name (`str`, optional):+ The naming pattern for MCP tools.agent_skill_instruction (`str | None`, optional):The instruction for agent skills in the system prompt. If notprovided, a default instruction will be used.@@ -166,7 +191,16 @@ Check "{dir}/SKILL.md" for how to use this skill""""""super().__init__()- self.tools: dict[str, RegisteredToolFunction] = {}+ self.tools: dict[str, RegisteredTool] = OrderedDict()+ if tools:+ for tool in tools:+ # TODO: handle the name conflict here+ self.tools[tool.name] = RegisteredTool(tool=tool)++ self.meta_tool_response_template = meta_tool_response_template++ self.mcp_tool_name = mcp_tool_name+self.groups: dict[str, ToolGroup] = {}self.skills: dict[str, AgentSkill] = {}self._middlewares: list = [] # Store registered middlewares@@ -178,17 +212,21 @@ Check "{dir}/SKILL.md" for how to use this skill"""agent_skill_template or self._DEFAULT_AGENT_SKILL_TEMPLATE)- # This is an experimental feature to allow the tool function to be- # executed in an async way- self._async_tasks: dict[str, asyncio.Task] = {}- self._async_results: dict[str, ToolResponse] = {}+ self.builtin_meta_tool = RegisteredTool(+ tool=ResetTools(+ # An inference value for groups so that it can generate the+ # corresponding input schema.+ groups=self.groups,+ response_template=meta_tool_response_template,+ ),+ )def create_tool_group(self,group_name: str,description: str,- active: bool = False,- notes: str | None = None,+ instructions: str | None = None,+ tools: list[ToolBase] | None = None,) -> None:"""Create a tool group to organize tool functions@@ -197,13 +235,13 @@ Check "{dir}/SKILL.md" for how to use this skill"""The name of the tool group.description (`str`):The description of the tool group.- active (`bool`, defaults to `False`):- If the group is active, meaning the tool functions in this- group are included in the JSON schema.- notes (`str | None`, optional):- The notes used to remind the agent how to use the tool- functions properly, which can be combined into the system- prompt.+ instructions (`str | None`, optional):+ The instructions about how to use the tool functions in this+ group.+ tools (`list[ToolProtocol] | None`, optional):+ The tool objects that implement the ToolProtocol interface to+ be added into this group. Note that these tools will also be+ added to the toolkit if they are not already in the toolkit."""if group_name in self.groups or group_name == "basic":raise ValueError(@@ -214,28 +252,18 @@ Check "{dir}/SKILL.md" for how to use this skill"""self.groups[group_name] = ToolGroup(name=group_name,description=description,- notes=notes,- active=active,+ instructions=instructions,)- def update_tool_groups(self, group_names: list[str], active: bool) -> None:- """Update the activation status of the given tool groups.-- Args:- group_names (`list[str]`):- The list of tool group names to be updated.- active (`bool`):- If the tool groups should be activated or deactivated.- """-- for group_name in group_names:- if group_name == "basic":- logger.warning(- "The 'basic' tool group is always active, skipping it.",+ if isinstance(tools, list) and all(+ isinstance(_, ToolBase) for _ in tools+ ):+ for tool in tools:+ registered = RegisteredTool(+ tool=tool,+ group=group_name,)-- if group_name in self.groups:- self.groups[group_name].active = active+ self.tools[tool.name] = registereddef remove_tool_groups(self, group_names: str | list[str]) -> None:"""Remove tool functions from the toolkit by their group names.@@ -269,270 +297,62 @@ Check "{dir}/SKILL.md" for how to use this skill"""if self.tools[tool_name].group in group_names:self.tools.pop(tool_name)- # pylint: disable=too-many-branches, too-many-statements- def register_tool_function(+ def register_function(self,- tool_func: ToolFunction,- group_name: str | Literal["basic"] = "basic",- preset_kwargs: dict[str, JSONSerializableObject] | None = None,- func_name: str | None = None,- func_description: str | None = None,- json_schema: dict | None = None,- include_long_description: bool = True,- include_var_positional: bool = False,- include_var_keyword: bool = False,- postprocess_func: (- Callable[- [ToolCallBlock, ToolResponse],- ToolResponse | None,- ]- | Callable[- [ToolCallBlock, ToolResponse],- Awaitable[ToolResponse | None],- ]- )- | None = None,- namesake_strategy: Literal[- "override",- "skip",- "raise",- "rename",- ] = "raise",- async_execution: bool = False,+ func: Callable,+ group: str = "basic",+ name: str | None = None,+ description: str | None = None,+ is_concurrency_safe: bool = True,+ is_read_only: bool = False,) -> None:- """Register a tool function to the toolkit.+ """Register a Python function as a tool in the toolkit.++ This method wraps a regular Python function into a FunctionTool and+ registers it to the toolkit.Args:- tool_func (`ToolFunction`):- The tool function, which can be async or sync, streaming or- not-streaming, but the response must be a `ToolResponse`- object.- group_name (`str | Literal["basic"]`, defaults to `"basic"`):- The belonging group of the tool function. Tools in "basic"- group is always included in the JSON schema, while the others- are only included when their group is active.- preset_kwargs (`dict[str, JSONSerializableObject] | None`, \- optional):- Preset arguments by the user, which will not be included in- the JSON schema, nor exposed to the agent.- func_name (`str | None`, optional):- The custom function name, which should be consistent with the- name in function_description and json_schema (if provided).- By default, the function name will be extracted from the- function automatically.- func_description (`str | None`, optional):- The function description. If not provided, the description- will be extracted from the docstring automatically.- json_schema (`dict | None`, optional):- Manually provided JSON schema for the tool function, which- should be `{"type": "function", "function": {"name":- "function_name": "xx", "description": "xx",- "parameters": {...}}}`- include_long_description (`bool`, defaults to `True`):- When extracting function description from the docstring, if- the long description will be included.- include_var_positional (`bool`, defaults to `False`):- Whether to include the variable positional arguments (`*args`)- in the function schema.- include_var_keyword (`bool`, defaults to `False`):- Whether to include the variable keyword arguments (`**kwargs`)- in the function schema.- postprocess_func (`(Callable[[ToolCallBlock, ToolResponse], \- ToolResponse | None] | Callable[[ToolCallBlock, ToolResponse], \- Awaitable[ToolResponse | None]]) | None`, optional):- A post-processing function that will be called after the tool- function is executed, taking the tool call block and tool- response as arguments. The function can be either sync or- async. If it returns `None`, the tool result will be- returned as is. If it returns a `ToolResponse`,- the returned block will be used as the final tool result.- namesake_strategy (`Literal['raise', 'override', 'skip', \- 'rename']`, defaults to `'raise'`):- The strategy to handle the tool function name conflict:- - 'raise': raise a ValueError (default behavior).- - 'override': override the existing tool function with the new- one.- - 'skip': skip the registration of the new tool function.- - 'rename': rename the new tool function by appending a random- suffix to make it unique.- async_execution (`bool`, defaults to `False`):- If this tool function is executed in an async manner, a- reminder with task id will be sent to the agent, allowing the- agent to view, cancel or check the status of the async task.- **This is an experimental feature and may cause unexpected- issues, please use it with caution.**+ func (`Callable`):+ A Python function to be registered as a tool.+ group (`str`, defaults to `"basic"`):+ The belonging group of the tool. Tools in "basic" group are+ always included in the JSON schema, while others are only+ included when their group is active.+ name (`str | None`, optional):+ Custom tool name. If None, uses the function name.+ description (`str | None`, optional):+ Custom tool description. If None, extracts from docstring.+ is_concurrency_safe (`bool`, defaults to `True`):+ Whether this tool is safe to call concurrently.+ is_read_only (`bool`, defaults to `False`):+ Whether this tool only reads data without side effects."""- # Arguments checking- if group_name not in self.groups and group_name != "basic":- raise ValueError(- f"Tool group '{group_name}' not found.",- )-- # Check the manually provided JSON schema if provided- if json_schema:- assert (- isinstance(json_schema, dict)- and "type" in json_schema- and json_schema["type"] == "function"- and "function" in json_schema- and isinstance(json_schema["function"], dict)- ), "Invalid JSON schema for the tool function."-- # Handle MCP tool function and regular function respectively- mcp_name = None- if isinstance(tool_func, MCPToolFunction):- input_func_name = tool_func.name- original_func = tool_func.__call__- json_schema = json_schema or tool_func.json_schema- mcp_name = tool_func.mcp_name-- elif isinstance(tool_func, partial):- # partial function- kwargs = tool_func.keywords- # Turn args into keyword arguments- if tool_func.args:- param_names = list(- inspect.signature(tool_func.func).parameters.keys(),- )- for i, arg in enumerate(tool_func.args):- if i < len(param_names):- kwargs[param_names[i]] = arg-- preset_kwargs = {- **kwargs,- **(preset_kwargs or {}),- }-- input_func_name = tool_func.func.__name__- original_func = tool_func.func- json_schema = json_schema or _parse_tool_function(- tool_func.func,- include_long_description=include_long_description,- include_var_positional=include_var_positional,- include_var_keyword=include_var_keyword,- )+ # Wrap the function into a FunctionTool+ tool = _FunctionTool(+ func,+ name=name,+ description=description,+ is_concurrency_safe=is_concurrency_safe,+ is_read_only=is_read_only,+ )- else:- # normal function- input_func_name = tool_func.__name__- original_func = tool_func- json_schema = json_schema or _parse_tool_function(- tool_func,- include_long_description=include_long_description,- include_var_positional=include_var_positional,- include_var_keyword=include_var_keyword,+ # Check if the group exists+ groups = ["basic"] + list(self.groups.keys())+ if group not in groups:+ raise ValueError(+ f"Tool group '{group}' does not exist. Available groups: "+ f"{groups}. You can create a new group by calling "+ "`toolkit.create_tool_group()` method.",)- # Record the original function name if the func_name is given- original_name = input_func_name if func_name else None-- # Use the given function name if provided- func_name = func_name or input_func_name-- # Always set the function name in json_schema- json_schema["function"]["name"] = func_name-- # Override the description if provided- if func_description:- json_schema["function"]["description"] = func_description-- # Remove the preset kwargs from the JSON schema- for arg_name in preset_kwargs or {}:- if arg_name in json_schema["function"]["parameters"]["properties"]:- json_schema["function"]["parameters"]["properties"].pop(- arg_name,- )-- if "required" in json_schema["function"]["parameters"]:- for arg_name in preset_kwargs or {}:- if (- arg_name- in json_schema["function"]["parameters"]["required"]- ):- json_schema["function"]["parameters"]["required"].remove(- arg_name,- )-- # Remove the required field if it is empty- if len(json_schema["function"]["parameters"]["required"]) == 0:- json_schema["function"]["parameters"].pop("required", None)-- func_obj = RegisteredToolFunction(- name=func_name,- group=group_name,- source="function",- original_func=original_func,- json_schema=json_schema,- preset_kwargs=preset_kwargs or {},- original_name=original_name,- extended_model=None,- mcp_name=mcp_name,- postprocess_func=postprocess_func,- async_execution=async_execution,+ # Register the tool+ registered = RegisteredTool(+ tool=tool,+ group=group,)+ self.tools[tool.name] = registered- if func_name in self.tools:- if namesake_strategy == "raise":- raise ValueError(- f"A function with name '{func_name}' is already "- f"registered in the toolkit.",- )-- if namesake_strategy == "skip":- logger.warning(- "A function with name '%s' is already "- "registered in the toolkit. Skipping registration.",- func_name,- )-- elif namesake_strategy == "override":- logger.warning(- "A function with name '%s' is already registered "- "in the toolkit. Overriding with the new function.",- func_name,- )- self.tools[func_name] = func_obj-- elif namesake_strategy == "rename":- new_func_name = func_name- for _ in range(100):- suffix = shortuuid.uuid()[:5]- new_func_name = f"{func_name}_{suffix}"- if new_func_name not in self.tools:- break-- # Raise error if failed to find a unique name- if new_func_name in self.tools:- raise RuntimeError(- f"Failed to register tool function '{func_name}' with "- "a unique name after 100 attempts.",- )- logger.warning(- "A function with name '%s' is already "- "registered in the toolkit. Renaming the new function to "- "'%s'.",- func_name,- new_func_name,- )-- # Replace the function name with the new one- func_obj.original_name = original_name or func_name- func_obj.name = new_func_name- func_obj.json_schema["function"]["name"] = new_func_name-- self.tools[new_func_name] = func_obj-- else:- raise ValueError(- f"Invalid namesake_strategy: {namesake_strategy}. "- "Supported strategies are 'raise', 'override', 'skip', "- "and 'rename'.",- )-- else:- self.tools[func_name] = func_obj-- def remove_tool_function(+ def unregister_tool(self,tool_name: str,allow_not_exist: bool = True,@@ -554,15 +374,21 @@ Check "{dir}/SKILL.md" for how to use this skill"""self.tools.pop(tool_name, None)- def get_json_schemas(+ def get_function_schemas(self,+ groups: list[str] | None = None,) -> list[dict]:- """Get the JSON schemas from the tool functions that belong to the- active groups.+ """Get the function JSON schemas... note:: The preset keyword arguments is removed from the JSONschema, and the extended model is applied if it is set.+ Args:+ groups (`list[str] | None`, optional):+ 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.+Example:.. code-block:: JSON:caption: Example of tool function JSON schemas@@ -592,30 +418,12 @@ Check "{dir}/SKILL.md" for how to use this skill"""`list[dict]`:A list of function JSON schemas."""- # If meta tool is set here, update its extended model here- if "reset_equipped_tools" in self.tools:- fields = {}- for group_name, group in self.groups.items():- if group_name == "basic":- continue- fields[group_name] = (- bool,- Field(- default=False,- description=group.description,- ),- )- extended_model = create_model("_DynamicModel", **fields)- self.set_extended_model(- "reset_equipped_tools",- extended_model,- )+ function_schemas = []- return [- tool.extended_json_schema- for tool in self.tools.values()- if tool.group == "basic" or self.groups[tool.group].active- ]+ for tool in self._get_available_tools(groups).values():+ function_schemas.append(tool.get_function_schema())++ return function_schemasdef set_extended_model(self,@@ -670,7 +478,7 @@ Check "{dir}/SKILL.md" for how to use this skill"""to_removed = []func_names = deepcopy(list(self.tools.keys()))for func_name in func_names:- if self.tools[func_name].mcp_name in client_names:+ if self.tools[func_name].tool.mcp_name in client_names:self.tools.pop(func_name)to_removed.append(func_name)@@ -681,355 +489,164 @@ Check "{dir}/SKILL.md" for how to use this skill"""", ".join(to_removed),)- async def _execute_tool_in_background(- self,- task_id: str,- tool_func: RegisteredToolFunction,- kwargs: dict,- partial_postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- )- | None,- ) -> None:- """Execute a tool function in the background and store the result.-- This function handles both streaming and non-streaming tool functions.- For streaming functions (generators/async generators), it accumulates- all chunks into a single final ToolResponse.-- Args:- task_id (`str`):- The unique identifier for this async task.- tool_func (`RegisteredToolFunction`):- The registered tool function to execute.- kwargs (`dict`):- The keyword arguments to pass to the tool function.- partial_postprocess_func (`Callable | None`):- Optional postprocess function to apply to the result.- """- try:- # Execute the tool function- if inspect.iscoroutinefunction(tool_func.original_func):- try:- res = await tool_func.original_func(**kwargs)- except asyncio.CancelledError:- res = ToolResponse(- content=[- TextBlock(- type="text",- text="<system-info>"- "The tool call has been interrupted "- "by the user."- "</system-info>",- ),- ],- stream=True,- is_last=True,- is_interrupted=True,- )- else:- # When `tool_func.original_func` is Async generator function or- # Sync function- res = tool_func.original_func(**kwargs)-- except mcp.shared.exceptions.McpError as e:- res = ToolResponse(- content=[- TextBlock(- type="text",- text=f"Error occurred when calling MCP tool: {e}",- ),- ],- )-- except Exception as e:- res = ToolResponse(- content=[- TextBlock(- type="text",- text=f"Error: {e}",- ),- ],- )-- # Handle different return types and accumulate streaming results- final_result: ToolResponse = ToolResponse(content=[])-- try:- # If return an async generator - accumulate all chunks- if isinstance(res, AsyncGenerator):- accumulated_content = []- last_chunk = None- async for chunk in res:- accumulated_content.extend(chunk.content)- last_chunk = chunk-- # Create final accumulated response- final_result = ToolResponse(- content=accumulated_content,- stream=False,- is_last=True,- is_interrupted=last_chunk.is_interrupted- if last_chunk- else False,- )-- # If return a sync generator - accumulate all chunks- elif isinstance(res, Generator):- accumulated_content = []- last_chunk = None- for chunk in res:- accumulated_content.extend(chunk.content)- last_chunk = chunk-- # Create final accumulated response- final_result = ToolResponse(- content=accumulated_content,- stream=False,- is_last=True,- is_interrupted=last_chunk.is_interrupted- if last_chunk- else False,- )-- elif isinstance(res, ToolResponse):- final_result = res-- else:- raise TypeError(- "The tool function must return a ToolResponse "- "object, or an AsyncGenerator/Generator of "- "ToolResponse objects, "- f"but got {type(res)}.",- )-- # Apply postprocess function if provided- if partial_postprocess_func:- from .._utils._common import _execute_async_or_sync_func-- processed_result = await _execute_async_or_sync_func(- partial_postprocess_func,- final_result,- )- if processed_result:- final_result = processed_result-- except asyncio.CancelledError:- # Handle cancellation during execution- final_result = ToolResponse(- content=[- TextBlock(- type="text",- text="<system-info>"- "The tool call has been cancelled by the user."- "</system-info>",- ),- ],- is_interrupted=True,- is_last=True,- )-- except Exception as e:- # Handle any other errors during execution- final_result = ToolResponse(- content=[- TextBlock(- type="text",- text=f"Error during async execution: {e}",- ),- ],- )-- finally:- # Store the result and remove from active tasks- self._async_results[task_id] = final_result- if task_id in self._async_tasks:- self._async_tasks.pop(task_id)-- @trace_toolkit- @_apply_middlewares- async def call_tool_function(+ # @trace_toolkit+ # @_apply_middlewares+ async def call_tool(self,tool_call: ToolCallBlock,- ) -> AsyncGenerator[ToolResponse, None]:- """Execute the tool function by the `ToolCallBlock` and return the- tool response chunk in unified streaming mode, i.e. an async- generator of `ToolResponse` objects.-- .. note:: The tool response chunk is **accumulated**.+ state: AgentState,+ ) -> AsyncGenerator[ToolChunk | ToolResponse, None]:+ """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.**Args:tool_call (`ToolCallBlock`):A tool call block.+ state: AgentState:+ The current agent state, used to state injection.Yields:- `ToolResponse`:- The tool response chunk, in accumulative manner.+ `ToolChunk | ToolResponse`:+ The incremental tool result in a ToolChunk stream, and finally+ the complete tool result in a ToolResponse object."""+ tool_response = ToolResponse(id=tool_call.id)# Check- if tool_call["name"] not in self.tools:- return _object_wrapper(- ToolResponse(+ available_tools = self._get_available_tools(state.activated_groups)++ if tool_call.name not in available_tools:+ # Not activate+ if tool_call.name in self.tools:+ group_name = self.tools[tool_call.name].group+ chunk = ToolChunk(content=[TextBlock(- type="text",- text="FunctionNotFoundError: Cannot find the "- f"function named {tool_call['name']}",+ text=(+ "ToolGroupInactiveError: The tool "+ f"'{tool_call.name}' in group '{group_name}' "+ "is currently inactive. You should first "+ "activate the group by calling the "+ f"'{self.builtin_meta_tool.tool.name}' tool."+ ),),],- ),- None,+ state="error",+ )+ yield chunk+ yield tool_response.append_chunk(chunk)+ return++ # Not exist+ chunk = ToolChunk(+ content=[+ TextBlock(+ text=f"ToolNotFoundError: The tool named "+ f"'{tool_call.name}' doesn't exist.",+ ),+ ],+ state="error",)+ yield chunk+ yield tool_response.append_chunk(chunk)+ return# Obtain the tool function- tool_func = self.tools[tool_call["name"]]-- # Check if the tool function is in an inactive group- if (- tool_func.group != "basic"- and not self.groups[tool_func.group].active- ):- return _object_wrapper(- ToolResponse(- content=[- TextBlock(- type="text",- text="FunctionInactiveError: The function "- f"'{tool_call['name']}' is in the inactive "- f"group '{tool_func.group}'. Activate the tool "- "group by calling 'reset_equipped_tools' "- "first to use this tool.",- ),- ],- ),- None,- )+ tool_func = available_tools[tool_call.name].tool# Prepare keyword arguments- kwargs = {- **tool_func.preset_kwargs,- **(tool_call.get("input", {}) or {}),- }-- # Prepare postprocess function- if tool_func.postprocess_func:- # Type: partial wraps the postprocess_func with tool_call bound,- # reducing it from (ToolCallBlock, ToolResponse) to (ToolResponse)- partial_postprocess_func: (- Callable[[ToolResponse], ToolResponse | None]- | Callable[[ToolResponse], Awaitable[ToolResponse | None]]- ) | None = partial(- tool_func.postprocess_func,- tool_call,- )- else:- partial_postprocess_func = None-- # Check if async execution is enabled- if tool_func.async_execution:- # Generate a unique task ID- task_id = shortuuid.uuid()-- # Create and store the background task- task = asyncio.create_task(- self._execute_tool_in_background(- task_id=task_id,- tool_func=tool_func,- kwargs=kwargs,- partial_postprocess_func=partial_postprocess_func,- ),- )- self._async_tasks[task_id] = task+ kwargs = _json_loads_with_repair(tool_call.input)- # Return a response with the task ID- return _object_wrapper(- ToolResponse(- content=[- TextBlock(- type="text",- text=f"<system-reminder>"- f"Tool '{tool_call['name']}' is executing "- f"asynchronously. "- f"Task ID: {task_id}. "- f"Use view_task('{task_id}') to check "- f"status, "- f"wait_task('{task_id}') to wait for "- f"completion, "- f"or cancel_task('{task_id}') to cancel "- f"the task."- f"</system-reminder>",- ),- ],- ),- None,- )+ # TODO: we should be build a mechanism to support state injection in+ # the future instead of hard coding here.+ if tool_call.name == self.builtin_meta_tool.tool.name:+ kwargs["state"] = state# Async functiontry:- if inspect.iscoroutinefunction(tool_func.original_func):- try:- res = await tool_func.original_func(**kwargs)- except asyncio.CancelledError:- res = ToolResponse(- content=[- TextBlock(- type="text",- text="<system-info>"- "The tool call has been interrupted "- "by the user."- "</system-info>",- ),- ],- stream=True,- is_last=True,- is_interrupted=True,- )-+ if inspect.iscoroutinefunction(tool_func.__call__):+ res = await tool_func(**kwargs)else:# When `tool_func.original_func` is Async generator function or# Sync function- res = tool_func.original_func(**kwargs)+ res = tool_func(**kwargs)++ if isinstance(res, ToolChunk):+ yield res+ tool_response.append_chunk(res)++ # If return an async generator+ elif isinstance(res, AsyncGenerator):+ async for chunk in res:+ yield chunk+ tool_response.append_chunk(chunk)++ # If return a sync generator+ elif isinstance(res, Generator):+ for chunk in res:+ yield chunk+ tool_response.append_chunk(chunk)++ else:+ raise DeveloperOrientedException(+ "The tool function must return a ToolChunk object, or an "+ "AsyncGenerator/Generator of ToolChunk objects, "+ f"but got {type(res)}.",+ )except mcp.shared.exceptions.McpError as e:- res = ToolResponse(+ chunk = ToolChunk(content=[TextBlock(type="text",text=f"Error occurred when calling MCP tool: {e}",),],+ state="error",)+ yield chunk+ tool_response.append_chunk(chunk)except Exception as e:- res = ToolResponse(+ # Raise the developer-oriented exception+ if isinstance(e, DeveloperOrientedException):+ raise e from None++ # The exceptions should be handled by the agent+ chunk = ToolChunk(content=[TextBlock(type="text",text=f"Error: {e}",),],+ state="error",)+ yield chunk+ tool_response.append_chunk(chunk)- # Handle different return type-- # If return an async generator- if isinstance(res, AsyncGenerator):- return _async_generator_wrapper(res, partial_postprocess_func)-- # If return a sync generator- if isinstance(res, Generator):- return _sync_generator_wrapper(res, partial_postprocess_func)-- if isinstance(res, ToolResponse):- return _object_wrapper(res, partial_postprocess_func)+ except asyncio.CancelledError:+ chunk = ToolChunk(+ content=[+ TextBlock(+ type="text",+ text="<system-reminder>"+ "The tool call has been interrupted "+ "by the user."+ "</system-reminder>",+ ),+ ],+ state="interrupted",+ )+ yield chunk+ tool_response.append_chunk(chunk)- raise TypeError(- "The tool function must return a ToolResponse object, or an "- "AsyncGenerator/Generator of ToolResponse objects, "- f"but got {type(res)}.",- )+ finally:+ # Finally, yield the complete tool response+ yield tool_responseasync def register_mcp_client(self,@@ -1037,24 +654,6 @@ Check "{dir}/SKILL.md" for how to use this skill"""group_name: str = "basic",enable_funcs: list[str] | None = None,disable_funcs: list[str] | None = None,- preset_kwargs_mapping: dict[str, dict[str, Any]] | None = None,- postprocess_func: (- Callable[- [ToolCallBlock, ToolResponse],- ToolResponse | None,- ]- | Callable[- [ToolCallBlock, ToolResponse],- Awaitable[ToolResponse | None],- ]- )- | None = None,- namesake_strategy: Literal[- "override",- "skip",- "raise",- "rename",- ] = "raise",) -> None:"""Register tool functions from an MCP client.@@ -1069,28 +668,6 @@ Check "{dir}/SKILL.md" for how to use this skill"""disable_funcs (`list[str] | None`, optional):The functions that will be filtered out. If `None`, notool functions will be filtered out.- preset_kwargs_mapping: (`Optional[dict[str, dict[str, Any]]]`, \- defaults to `None`):- The preset keyword arguments mapping, whose keys are the tool- function names and values are the preset keyword arguments.- postprocess_func (`(Callable[[ToolCallBlock, ToolResponse], \- ToolResponse | None] | Callable[[ToolCallBlock, ToolResponse], \- Awaitable[ToolResponse | None]]) | None`, optional):- A post-processing function that will be called after the tool- function is executed, taking the tool call block and tool- response as arguments. The function can be either sync or- async. If it returns `None`, the tool result will be- returned as is. If it returns a `ToolResponse`,- the returned block will be used as the final tool result.- namesake_strategy (`Literal['raise', 'override', 'skip', \- 'rename']`, defaults to `'raise'`):- The strategy to handle the tool function name conflict:- - 'raise': raise a ValueError (default behavior).- - 'override': override the existing tool function with the new- one.- - 'skip': skip the registration of the new tool function.- - 'rename': rename the new tool function by appending a random- suffix to make it unique."""if (isinstance(mcp_client, StatefulClientBase)@@ -1124,15 +701,6 @@ Check "{dir}/SKILL.md" for how to use this skill"""f"should not overlap, but got {intersection}.")- if not (- preset_kwargs_mapping is None- or isinstance(preset_kwargs_mapping, dict)- ):- raise TypeError(- f"The preset_kwargs_mapping must be a dictionary or None, "- f"but got {type(preset_kwargs_mapping)}.",- )-tool_names = []for mcp_tool in await mcp_client.list_tools():# Skip the functions that are not in the enable_funcs if@@ -1147,164 +715,24 @@ Check "{dir}/SKILL.md" for how to use this skill"""tool_names.append(mcp_tool.name)# Obtain callable function object- func_obj = await mcp_client.get_callable_function(- func_name=mcp_tool.name,- wrap_tool_result=True,+ tool_obj = await mcp_client.get_tool(+ name=mcp_tool.name,)- # Prepare preset kwargs- preset_kwargs = None- if preset_kwargs_mapping is not None:- preset_kwargs = preset_kwargs_mapping.get(mcp_tool.name, {})-- self.register_tool_function(- tool_func=func_obj,- group_name=group_name,- preset_kwargs=preset_kwargs,- postprocess_func=postprocess_func,- namesake_strategy=namesake_strategy,+ # Register the tool function to the toolkit+ registered = RegisteredTool(+ tool=tool_obj,+ group=group_name,)+ self.tools[tool_obj.name] = registered+logger.info("Registered %d tool functions from MCP: %s.",len(tool_names),", ".join(tool_names),)- def state_dict(self) -> dict[str, Any]:- """Get the state dictionary of the toolkit.-- Returns:- `dict[str, Any]`:- A dictionary containing the active tool group names.- """- return {- "active_groups": [- name for name, group in self.groups.items() if group.active- ],- }-- def load_state_dict(- self,- state_dict: dict[str, Any],- strict: bool = True,- ) -> None:- """Load the state dictionary into the toolkit.-- Args:- state_dict (`dict`):- The state dictionary to load, which should have "active_groups"- key and its value must be a list of group names.- strict (`bool`, defaults to `True`):- If `True`, raises an error if any key in the module is not- found in the state_dict. If `False`, skips missing keys.- """- if (- not isinstance(state_dict, dict)- or "active_groups" not in state_dict- or not isinstance(state_dict["active_groups"], list)- ):- raise ValueError(- "The state_dict for toolkit must be a dictionary with "- "active_groups key and its value must be a list, "- f"but got {type(state_dict)}.",- )-- if strict and list(state_dict.keys()) != ["active_groups"]:- raise ValueError(- "Get additional keys in the state_dict: "- f'{list(state_dict.keys())}, but only "active_groups" '- "is expected.",- )-- for group_name, group in self.groups.items():- if group_name in state_dict["active_groups"]:- group.active = True- else:- group.active = False-- def get_activated_notes(self) -> str:- """Get the notes from the active tool groups, which can be used to- construct the system prompt for the agent.-- Returns:- `str`:- The combined notes from the active tool groups.- """- collected_notes = []- for group_name, group in self.groups.items():- if group.active and group.notes:- collected_notes.append(- "\n".join(- [f"## About Tool Group '{group_name}'", group.notes],- ),- )- return "\n".join(collected_notes)-- def reset_equipped_tools(self, **kwargs: Any) -> ToolResponse:- """This function allows you to activate or deactivate tool groups- dynamically based on your current task requirements.- **Important: Each call sets the absolute final state of ALL tool- groups, not incremental changes**. Any group not explicitly set to True- will be deactivated, regardless of its previous state.-- **Best practice**: Actively manage your tool groups——activate only- what you need for the current task, and promptly deactivate groups as- soon as they are no longer needed to conserve context space.-- The function will return the usage instructions for the activated tool- groups, which you **MUST pay attention to and follow**. You can also- reuse this function to check the notes of the tool groups."""-- # Deactivate all tool groups first- self.update_tool_groups(list(self.groups.keys()), active=False)-- to_activate = []- for key, value in kwargs.items():- if not isinstance(value, bool):- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"Invalid arguments: the argument {key} "- f"should be a bool value, but got {type(value)}.",- ),- ],- )-- if value:- to_activate.append(key)-- self.update_tool_groups(to_activate, active=True)-- notes = self.get_activated_notes()-- text_response = ""- if to_activate:- text_response += (- "Now tool groups "- + ", ".join([f"'{_}'" for _ in to_activate])- + " are activated."- )-- if notes:- text_response += (- f" You MUST follow these notes to use these tools:\n"- f"<notes>{notes}</notes>"- )-- if not text_response:- text_response = "All tool groups are now deactivated currently."-- return ToolResponse(- content=[- TextBlock(- type="text",- text=text_response,- ),- ],- )-def clear(self) -> None:"""Clear the toolkit, removing all tool functions and groups."""self.tools.clear()@@ -1532,147 +960,33 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):# The @apply_middlewares decorator will handle the executionself._middlewares.append(middleware)- async def view_task(self, task_id: str) -> ToolResponse:- """View the status of an async tool task by its task ID.-- Args:- task_id (`str`):- The ID of the async tool task.-- Returns:- `ToolResponse`:- The tool response containing the status information of the- async task.- """- if (- task_id not in self._async_tasks- and task_id not in self._async_results- ):- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"InvalidTaskIdError: Cannot find async "- f"task with ID {task_id}.",- ),- ],- )-- if task_id in self._async_tasks:- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"Task {task_id} is still running.",- ),- ],- )-- # If the task is completed, return the result or error- return self._async_results.pop(task_id)-- async def cancel_task(self, task_id: str) -> ToolResponse:- """Cancel an async tool task by its task ID.-- Args:- task_id (`str`):- The ID of the async tool task.-- Returns:- `ToolResponse`:- The tool response indicating whether the cancellation was- successful.- """- if (- task_id not in self._async_tasks- and task_id not in self._async_results- ):- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"InvalidTaskIdError: Cannot find async "- f"task with ID {task_id}.",- ),- ],- )-- if task_id in self._async_results:- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"Task {task_id} has already completed "- f"and cannot be cancelled.",- ),- ],- )-- # Cancel the running task- task = self._async_tasks.pop(task_id)- task.cancel()-- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"Task {task_id} has been cancelled.",- ),- ],- )-- async def wait_task(+ def _get_available_tools(self,- task_id: str,- timeout: float = 10,- ) -> ToolResponse:- """Wait for an async tool execution to complete by its task ID. Note- the timeout shouldn't be too large, you can check the task status- by this tool every short period of time to avoid long waiting time.+ groups: list[str] | None,+ ) -> dict[str, RegisteredTool]:+ """Return the currently available tools based on the given+ activated tool groups. Tools in the ``"basic"`` group are always+ included. When at least one tool group is registered, the built-in+ meta tool is also included.Args:- task_id (`str`):- The ID of the async tool task.- timeout (`float`, defaults to `10`):- The maximum time to wait for the task to complete, in seconds.+ groups (`list[str]`):+ The list of currently activated tool group names.Returns:- `ToolResponse`:- The tool response containing the result of the async task if- it completes within the timeout, or an error message if the- task is still running after the timeout.+ `dict[str, RegisteredTool]`:+ The dictionary of available tool name and their corresponding+ RegisteredTool objects."""- if (- task_id not in self._async_tasks- and task_id not in self._async_results- ):- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"InvalidTaskIdError: Cannot find async "- f"task with ID {task_id}.",- ),- ],- )-- if task_id in self._async_results:- return self._async_results.pop(task_id)-- # Wait for the running task to complete or timeout- task = self._async_tasks[task_id]- try:- await asyncio.wait_for(asyncio.shield(task), timeout=timeout)- except asyncio.TimeoutError:- return ToolResponse(- content=[- TextBlock(- type="text",- text=f"Task {task_id} is still running after "- f"waiting for {timeout} seconds.",- ),- ],- )-- # If the task is completed, return the result or error- return self._async_results.pop(task_id)+ available_tools = {}+ if len(self.groups) > 0:+ available_tools[+ self.builtin_meta_tool.tool.name+ ] = self.builtin_meta_tool++ groups_filter = ["basic"] + (groups or [])+ for tool_name, tool in self.tools.items():+ if tool.group in groups_filter:+ available_tools[tool_name] = tool++ return available_toolsdiff --git a/src/agentscope/tool/_types.py b/src/agentscope/tool/_types.pyindex 386fea4c8..7b5ae2b62 100644--- a/src/agentscope/tool/_types.py+++ b/src/agentscope/tool/_types.py@@ -2,98 +2,122 @@"""The types for the tool module in AgentScope."""from copy import deepcopyfrom dataclasses import dataclass, field-from typing import TypedDict, Literal, Type, Callable, Awaitable+from typing import (+ Literal,+ Type,+ Any,+ TypedDict,+ TypeAlias,+ Coroutine,+ AsyncGenerator,+ Generator,+ Awaitable,+ Callable,+)from pydantic import BaseModel-from . import ToolResponse-from .._utils._common import _remove_title_field-from ..message import ToolCallBlock-from ..types import ToolFunction, JSONSerializableObject+from ._response import ToolChunk+from ._base import ToolBase+from ._utils import _remove_title_field@dataclass-class RegisteredToolFunction:- """The registered tool function class."""+class RegisteredTool:+ """The registered tool function class, used to store the tool function and+ its registration information."""- name: str- """The name of the tool function."""- group: str | Literal["basic"]- """The belonging group of the tool function"""- source: Literal["function", "mcp_server", "function_group"]- """"The type of the tool function, can be `function` or `mcp_server`."""- original_func: ToolFunction- """The original function"""- json_schema: dict- """The JSON schema of the tool function, which is used to validate the """- preset_kwargs: dict[str, JSONSerializableObject] = field(- default_factory=dict,- )- """The preset keyword arguments, which won't be presented in the JSON- schema and exposed to the user."""- original_name: str | None = None- """The original name of the tool function when it has been renamed."""- extended_model: Type[BaseModel] | None = None+ tool: ToolBase+ """The original tool function."""++ # Execution related fields+ extended_model: Type[BaseModel] | None = field(init=False, default=None)"""The base model used to extend the JSON schema of the original toolfunction, so that we can dynamically adjust the tool function."""- mcp_name: str | None = None- """The name of the MCP, if the tool function comes from an MCP server."""- postprocess_func: (- Callable[- [ToolCallBlock, ToolResponse],- ToolResponse | None,- ]- | Callable[- [ToolCallBlock, ToolResponse],- Awaitable[ToolResponse | None],- ]- ) | None = None- """The post-processing function that will be called after the tool- function is executed, taking the tool call block and tool- response as arguments. The function can be either sync or async. If it- returns `None`, the tool result will be returned as is. If it returns a- `ToolResponse`, the returned block will be used as the final tool- response."""- async_execution: bool = False- """If this tool function is executed in an async manner, a reminder with- task id will be sent to the agent, allowing the agent to view, cancel or- check the status of the async task."""-- @property- def extended_json_schema(self) -> dict:- """Get the JSON schema of the tool function, if an extended model is- set, the merged JSON schema will be returned."""- if self.extended_model is None:- return self.json_schema- # Merge the extended model with the original JSON schema- extended_schema = self.extended_model.model_json_schema()+ # Tools management fields+ group: str | Literal["basic"] = "basic"+ """The belonging group of the tool function"""+ original_name: str | None = field(default=None)+ """The original name of the tool function when it has been renamed."""- merged_schema = deepcopy(self.json_schema)+ def __post_init__(self) -> None:+ """Validate the registered tool function after initialization."""+ # validate schema+ if self.tool.input_schema is not None:+ if not (+ isinstance(self.tool.input_schema, dict)+ and self.tool.input_schema.get("type") == "object"+ and isinstance(self.tool.input_schema.get("properties"), dict)+ ):+ raise ValueError(+ f"Invalid input_schema: {self.tool.input_schema}. ",+ )++ def get_function_schema(+ self,+ extended_model: Type[BaseModel] | None = None,+ ) -> dict:+ """Get the JSON schema of the tool function via the following steps:++ 1. Remove preset_kwargs from the JSON schema, since they are not+ exposed to the agent.+ 2. If extended_model is provided, merge its schema with the+ current function schema.++ Args:+ extended_model (`Type[BaseModel] | None`, optional):+ The dynamic BaseModel used to extend the original function. If+ provided, the given BaseModel will be merged into the original+ function schema instead of the extended_model field.++ Returns:+ `dict`: The JSON schema of the tool function.+ """+ input_schema = deepcopy(self.tool.input_schema)+ _remove_title_field(input_schema)+ function_schema: dict = {+ "type": "function",+ "function": {+ "name": self.tool.name,+ "description": self.tool.description,+ "parameters": input_schema,+ },+ }++ extended_model = extended_model or self.extended_model++ if extended_model is None:+ return function_schema++ # Merge the extended model with the original JSON schema+ extended_schema = extended_model.model_json_schema()- _remove_title_field( # pylint: disable=protected-access- extended_schema,- )+ _remove_title_field(extended_schema)# Merge properties from extended schemafor key, value in extended_schema["properties"].items():- if key in self.json_schema["function"]["parameters"]["properties"]:+ if key in function_schema["function"]["parameters"]["properties"]:raise ValueError(f"The field `{key}` already exists in the original "- f"function schema of `{self.name}`. Try to use a "+ f"function schema of `{self.tool.name}`. Try to use a ""different name.",)- merged_schema["function"]["parameters"]["properties"][key] = value+ function_schema["function"]["parameters"]["properties"][+ key+ ] = valueif key in extended_schema.get("required", []):- if "required" not in merged_schema["function"]["parameters"]:- merged_schema["function"]["parameters"]["required"] = []- merged_schema["function"]["parameters"]["required"].append(key)+ if "required" not in function_schema["function"]["parameters"]:+ function_schema["function"]["parameters"]["required"] = []+ function_schema["function"]["parameters"]["required"].append(+ key,+ )# Merge $defs from extended schema to support nested modelsif "$defs" in extended_schema:- merged_params = merged_schema["function"]["parameters"]+ merged_params = function_schema["function"]["parameters"]if "$defs" not in merged_params:merged_params["$defs"] = {}@@ -112,16 +136,14 @@ class RegisteredToolFunction:existing_def_copy = deepcopy(merged_params["$defs"][def_key],)- _remove_title_field(- existing_def_copy,- ) # pylint: disable=protected-access+ _remove_title_field(existing_def_copy)if existing_def_copy != def_value_copy:# The definitions are different, raise an errorraise ValueError(f"The $defs key `{def_key}` conflicts with "f"existing definition in function schema of "- f"`{self.name}`.",+ f"`{self.tool.name}`.",)# The definitions are the same (from the same BaseModel),# skip merging this key@@ -129,24 +151,23 @@ class RegisteredToolFunction:merged_params["$defs"][def_key] = def_value_copy- return merged_schema+ return function_schema@dataclassclass ToolGroup:- """The tool group class"""+ """The tool group abstraction that provides a higher level of organization+ for tools."""name: str"""The group name, which will be used in the reset function as the groupidentifier."""- active: bool- """If the tool group is active, meaning the tool functions in this group- is included in the JSON schema"""description: str"""The description of the tool group to tell the agent what the toolgroup is about."""- notes: str | None = None- """The using notes of the tool group, to remind the agent how to use"""+ instructions: str | None = None+ """The instructions that will be contained when this tool group is+ activated."""class AgentSkill(TypedDict):@@ -158,3 +179,28 @@ class AgentSkill(TypedDict):"""The description of the skill."""dir: str"""The directory of the agent skill."""+++# The function types that can be registered as tools in AgentScope.+Function: TypeAlias = (+ # Sync function+ Callable[..., ToolChunk]+ |+ # Async function+ Callable[..., Awaitable[ToolChunk]]+ |+ # Sync generator function+ Callable[..., Generator[ToolChunk, None, None]]+ |+ # Async generator function+ Callable[..., AsyncGenerator[ToolChunk, None]]+ |+ # Async function that returns async generator+ Callable[..., Coroutine[Any, Any, AsyncGenerator[ToolChunk, None]]]+ |+ # Async function that returns sync generator+ Callable[..., Coroutine[Any, Any, Generator[ToolChunk, None, None]]]+)+++ToolChoice: TypeAlias = Literal["auto", "none", "required"] | strdiff --git a/src/agentscope/tool/_utils.py b/src/agentscope/tool/_utils.pynew file mode 100644index 000000000..6061626c6--- /dev/null+++ b/src/agentscope/tool/_utils.py@@ -0,0 +1,151 @@+# -*- coding: utf-8 -*-+"""The tool module utils."""+import inspect+from typing import Any, Dict, Callable++from docstring_parser import parse+from pydantic import Field, create_model, ConfigDict+++def _remove_title_field(schema: dict) -> None:+ """Remove the title field from the JSON schema to avoid+ misleading the LLM."""+ # The top level title field+ if "title" in schema:+ schema.pop("title")++ # properties+ if "properties" in schema:+ for prop in schema["properties"].values():+ if isinstance(prop, dict):+ _remove_title_field(prop)++ # items+ if "items" in schema and isinstance(schema["items"], dict):+ _remove_title_field(schema["items"])++ # additionalProperties+ if "additionalProperties" in schema and isinstance(+ schema["additionalProperties"],+ dict,+ ):+ _remove_title_field(+ schema["additionalProperties"],+ )+++def _extract_func_description(docstring: str) -> str:+ """Extract the function description from the docstring.++ Args:+ docstring (`str`):+ The docstring to extract the function description from.++ Returns:+ `str`:+ The extracted function description.+ """+ parsed_docstring = parse(docstring or "")+ descriptions = []+ if parsed_docstring.short_description is not None:+ descriptions.append(parsed_docstring.short_description)++ if parsed_docstring.long_description is not None:+ descriptions.append(parsed_docstring.long_description)++ return "\n".join(descriptions)+++def _extract_input_schema(+ tool_func: Callable,+ include_var_positional: bool = False,+ include_var_keyword: bool = False,+) -> dict:+ """Extract input schema from the tool function's docstring++ Args:+ tool_func (`ToolFunction`):+ The tool function to extract the JSON schema from.+ include_var_positional (`bool`):+ Whether to include variable positional arguments in the JSON+ schema.+ include_var_keyword (`bool`):+ Whether to include variable keyword arguments in the JSON schema.++ Returns:+ `dict`:+ The extracted input JSON schema.+ """+ docstring = parse(tool_func.__doc__ or "")+ params_docstring = {_.arg_name: _.description for _ in docstring.params}++ # Create a dynamic model with the function signature+ fields = {}+ for name, param in inspect.signature(tool_func).parameters.items():+ # Skip the `self` and `cls` parameters+ if name in ["self", "cls"]:+ continue++ # Handle `**kwargs`+ if param.kind == inspect.Parameter.VAR_KEYWORD:+ if not include_var_keyword:+ continue++ fields[name] = (+ Dict[str, Any]+ if param.annotation == inspect.Parameter.empty+ else Dict[str, param.annotation], # type: ignore+ Field(+ description=params_docstring.get(+ f"**{name}",+ params_docstring.get(name, None),+ ),+ default={}+ if param.default is param.empty+ else param.default,+ ),+ )++ elif param.kind == inspect.Parameter.VAR_POSITIONAL:+ if not include_var_positional:+ continue++ fields[name] = (+ list[Any]+ if param.annotation == inspect.Parameter.empty+ else list[param.annotation], # type: ignore+ Field(+ description=params_docstring.get(+ f"*{name}",+ params_docstring.get(name, None),+ ),+ default=[]+ if param.default is param.empty+ else param.default,+ ),+ )++ else:+ fields[name] = (+ Any+ if param.annotation == inspect.Parameter.empty+ else param.annotation,+ Field(+ description=params_docstring.get(name, None),+ default=...+ if param.default is param.empty+ else param.default,+ ),+ )++ base_model = create_model(+ "_StructuredOutputDynamicClass",+ __config__=ConfigDict(arbitrary_types_allowed=True),+ **fields,+ )+ params_json_schema = base_model.model_json_schema()++ # Remove the title from the json schema+ _remove_title_field(params_json_schema)++ return params_json_schemadiff --git a/src/agentscope/types/__init__.py b/src/agentscope/types/__init__.pyindex b8da5ac65..03ff21f23 100644--- a/src/agentscope/types/__init__.py+++ b/src/agentscope/types/__init__.py@@ -10,7 +10,6 @@ from ._json import (JSONPrimitive,JSONSerializableObject,)-from ._tool import ToolFunction, ToolChoice__all__ = ["AgentHookTypes",@@ -18,6 +17,4 @@ __all__ = ["Embedding","JSONPrimitive","JSONSerializableObject",- "ToolFunction",- "ToolChoice",]diff --git a/src/agentscope/types/_tool.py b/src/agentscope/types/_tool.pydeleted file mode 100644index f80ec483d..000000000--- a/src/agentscope/types/_tool.py+++ /dev/null@@ -1,41 +0,0 @@-# -*- coding: utf-8 -*--"""The tool related types"""--from typing import (- Callable,- Union,- Awaitable,- AsyncGenerator,- Generator,- Coroutine,- Any,- TYPE_CHECKING,- TypeAlias,- Literal,-)--if TYPE_CHECKING:- from ..tool import ToolResponse-else:- ToolResponse = "ToolResponse"--ToolFunction = Callable[- ...,- Union[- # sync function- ToolResponse,- # async function- Awaitable[ToolResponse],- # sync generator function- Generator[ToolResponse, None, None],- # async generator function- AsyncGenerator[ToolResponse, None],- # async function that returns async generator- Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],- # async function that returns sync generator- Coroutine[Any, Any, Generator[ToolResponse, None, None]],- ],-]---ToolChoice: TypeAlias = Literal["auto", "none", "required"] | strdiff --git a/tests/toolkit_test.py b/tests/toolkit_test.pynew file mode 100644index 000000000..e91151600--- /dev/null+++ b/tests/toolkit_test.py@@ -0,0 +1,1026 @@+# -*- coding: utf-8 -*-+"""Toolkit test case."""+import json+from typing import Any, AsyncGenerator, Generator+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.agent import AgentState+from agentscope.message import (+ TextBlock,+ ToolCallBlock,+ DataBlock,+ Base64Source,+)+from agentscope.tool import (+ Toolkit,+ ToolBase,+ ToolChunk,+ PermissionContext,+ PermissionDecision,+ PermissionBehavior,+ ToolResponse,+)+from tests.utils import AnyString+++class Tool1(ToolBase):+ """A simple tool for testing."""++ name: str = "tool_1"+ description: str = "A simple tool for testing."+ input_schema: dict = {+ "type": "object",+ "properties": {},+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Check permissions for the tool."""+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="Do you want to use my_tool?",+ )++ async def __call__(self, **kwargs: Any) -> ToolChunk:+ """Run the tool."""+ return ToolChunk(+ content=[TextBlock(text="Hello, world!")],+ )+++class Tool2(ToolBase):+ """Test tool 2"""++ name: str = "tool_2"+ description: str = "Test tool 2."+ input_schema: dict = {+ "type": "object",+ "properties": {},+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_mcp: bool = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Check permissions for the tool."""+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="Do you want to use my_tool?",+ )++ async def __call__(self, **kwargs: Any) -> AsyncGenerator[ToolChunk, None]:+ """Run the tool."""+ yield ToolChunk(+ content=[TextBlock(text="123", id="a")],+ )+ yield ToolChunk(+ content=[TextBlock(text="456", id="b")],+ )+ yield ToolChunk(+ content=[TextBlock(text="789", id="b")],+ )+ yield ToolChunk(+ content=[+ DataBlock(+ id="1",+ source=Base64Source(+ data="abc",+ media_type="image/jpeg",+ ),+ ),+ ],+ )+ yield ToolChunk(+ content=[+ DataBlock(+ id="2",+ source=Base64Source(+ data="***",+ media_type="image/jpeg",+ ),+ ),+ ],+ )+ yield ToolChunk(+ content=[+ DataBlock(+ id="1",+ source=Base64Source(+ data="def",+ media_type="image/jpeg",+ ),+ ),+ ],+ )+++class ToolkitTest(IsolatedAsyncioTestCase):+ """The toolkit test case."""++ async def asyncSetUp(self) -> None:+ """The async setup method."""++ async def test_initialize(self) -> None:+ """The template test."""++ # Initialize the toolkit+ toolkit = Toolkit()++ # No tools+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 0)++ # Initialize the toolkit with tools+ toolkit = Toolkit(tools=[Tool1(), Tool2()])+ schemas = toolkit.get_function_schemas()+ self.assertListEqual(+ schemas,+ [+ {+ "type": "function",+ "function": {+ "name": "tool_1",+ "description": "A simple tool for testing.",+ "parameters": {+ "type": "object",+ "properties": {},+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "tool_2",+ "description": "Test tool 2.",+ "parameters": {+ "type": "object",+ "properties": {},+ },+ },+ },+ ],+ )++ async def test_tool(self) -> None:+ """Test executing a tool."""+ toolkit = Toolkit(tools=[Tool1(), Tool2()])+ state = AgentState()++ # Test Tool1 (returns single ToolChunk)+ tool_call_1 = ToolCallBlock(+ id="test_1",+ name="tool_1",+ input=json.dumps({}),+ )++ chunks_1 = []+ response_1 = None+ async for result in toolkit.call_tool(tool_call_1, state):+ if isinstance(result, ToolChunk):+ chunks_1.append(result)+ elif isinstance(result, ToolResponse):+ response_1 = result++ # Verify Tool1 chunks+ self.assertEqual(len(chunks_1), 1)+ self.assertDictEqual(+ chunks_1[0].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Hello, world!",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify Tool1 response+ self.assertIsNotNone(response_1)+ self.assertDictEqual(+ response_1.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Hello, world!",+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_1",+ },+ )++ # Test Tool2 (returns async generator of ToolChunks)+ tool_call_2 = ToolCallBlock(+ id="test_2",+ name="tool_2",+ input=json.dumps({}),+ )++ chunks_2 = []+ response_2 = None+ async for result in toolkit.call_tool(tool_call_2, state):+ if isinstance(result, ToolChunk):+ chunks_2.append(result)+ elif isinstance(result, ToolResponse):+ response_2 = result++ # Verify Tool2 chunks+ self.assertEqual(len(chunks_2), 6)++ # First chunk - TextBlock id="a"+ self.assertDictEqual(+ chunks_2[0].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": "a",+ "text": "123",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Second chunk - TextBlock id="b"+ self.assertDictEqual(+ chunks_2[1].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": "b",+ "text": "456",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Third chunk - TextBlock id="b" (same id as second)+ self.assertDictEqual(+ chunks_2[2].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": "b",+ "text": "789",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Fourth chunk - DataBlock id="1"+ self.assertDictEqual(+ chunks_2[3].model_dump(),+ {+ "content": [+ {+ "type": "data",+ "id": "1",+ "name": None,+ "source": {+ "type": "base64",+ "media_type": "image/jpeg",+ "data": "abc",+ },+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Fifth chunk - DataBlock id="2"+ self.assertDictEqual(+ chunks_2[4].model_dump(),+ {+ "content": [+ {+ "type": "data",+ "id": "2",+ "name": None,+ "source": {+ "type": "base64",+ "media_type": "image/jpeg",+ "data": "***",+ },+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Sixth chunk - DataBlock id="1" (same id as fourth)+ self.assertDictEqual(+ chunks_2[5].model_dump(),+ {+ "content": [+ {+ "type": "data",+ "id": "1",+ "name": None,+ "source": {+ "type": "base64",+ "media_type": "image/jpeg",+ "data": "def",+ },+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify Tool2 response - blocks with same id are merged,+ # and consecutive TextBlocks are also merged+ # TextBlock id="a" (123) + id="b" (456) + id="b" (789) -> merged to+ # "123456789" with id="a"+ # DataBlock id="1" appears twice, should be merged to "abcdef"+ self.assertIsNotNone(response_2)+ self.assertDictEqual(+ response_2.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": "a",+ # All consecutive TextBlocks merged+ "text": "123456789",+ },+ {+ "type": "data",+ "id": "1",+ "name": None,+ "source": {+ "type": "base64",+ "media_type": "image/jpeg",+ "data": "abcdef", # Merged: "abc" + "def"+ },+ },+ {+ "type": "data",+ "id": "2",+ "name": None,+ "source": {+ "type": "base64",+ "media_type": "image/jpeg",+ "data": "***",+ },+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_2",+ },+ )+++class RegisterFunctionTest(IsolatedAsyncioTestCase):+ """Test registering different functions in the toolkit."""++ async def test_sync_non_streaming_function(self) -> None:+ """Test registering a synchronous non-streaming function."""++ def add_numbers(a: int, b: int) -> ToolChunk:+ """Add two numbers together.++ Args:+ a: The first number+ b: The second number+ """+ result = a + b+ return ToolChunk(+ content=[TextBlock(text=f"Result: {result}")],+ )++ toolkit = Toolkit()+ toolkit.register_function(add_numbers, group="basic")++ # Test schema+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 1)+ self.assertDictEqual(+ schemas[0],+ {+ "type": "function",+ "function": {+ "name": "add_numbers",+ "description": "Add two numbers together.",+ "parameters": {+ "type": "object",+ "properties": {+ "a": {+ "type": "integer",+ "description": "The first number",+ },+ "b": {+ "type": "integer",+ "description": "The second number",+ },+ },+ "required": ["a", "b"],+ },+ },+ },+ )++ # Test execution+ state = AgentState()+ tool_call = ToolCallBlock(+ id="test_add",+ name="add_numbers",+ input=json.dumps({"a": 3, "b": 5}),+ )++ chunks = []+ response = None+ async for result in toolkit.call_tool(tool_call, state):+ if isinstance(result, ToolChunk):+ chunks.append(result)+ elif isinstance(result, ToolResponse):+ response = result++ # Verify chunks+ self.assertEqual(len(chunks), 1)+ self.assertDictEqual(+ chunks[0].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Result: 8",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify response+ self.assertIsNotNone(response)+ self.assertDictEqual(+ response.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Result: 8",+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_add",+ },+ )++ async def test_sync_streaming_function(self) -> None:+ """Test registering a synchronous streaming function."""++ def count_to_n(n: int) -> Generator[ToolChunk, None, None]:+ """Count from 1 to n.++ Args:+ n: The number to count to+ """+ for i in range(1, n + 1):+ yield ToolChunk(+ content=[TextBlock(text=str(i))],+ )++ toolkit = Toolkit()+ toolkit.register_function(count_to_n, group="basic")++ # Test schema+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 1)+ self.assertDictEqual(+ schemas[0],+ {+ "type": "function",+ "function": {+ "name": "count_to_n",+ "description": "Count from 1 to n.",+ "parameters": {+ "type": "object",+ "properties": {+ "n": {+ "type": "integer",+ "description": "The number to count to",+ },+ },+ "required": ["n"],+ },+ },+ },+ )++ # Test execution+ state = AgentState()+ tool_call = ToolCallBlock(+ id="test_count",+ name="count_to_n",+ input=json.dumps({"n": 3}),+ )++ chunks = []+ response = None+ async for result in toolkit.call_tool(tool_call, state):+ if isinstance(result, ToolChunk):+ chunks.append(result)+ elif isinstance(result, ToolResponse):+ response = result++ # Verify chunks+ self.assertEqual(len(chunks), 3)+ for i, chunk in enumerate(chunks, 1):+ self.assertDictEqual(+ chunk.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": str(i),+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify response - consecutive TextBlocks are merged+ self.assertIsNotNone(response)+ self.assertDictEqual(+ response.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "123", # All consecutive TextBlocks merged+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_count",+ },+ )++ async def test_async_non_streaming_function(self) -> None:+ """Test registering an asynchronous non-streaming function."""++ async def multiply_numbers(x: float, y: float) -> ToolChunk:+ """Multiply two numbers.++ Args:+ x: The first number+ y: The second number+ """+ result = x * y+ return ToolChunk(+ content=[TextBlock(text=f"Product: {result}")],+ )++ toolkit = Toolkit()+ toolkit.register_function(multiply_numbers, group="basic")++ # Test schema+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 1)+ self.assertDictEqual(+ schemas[0],+ {+ "type": "function",+ "function": {+ "name": "multiply_numbers",+ "description": "Multiply two numbers.",+ "parameters": {+ "type": "object",+ "properties": {+ "x": {+ "type": "number",+ "description": "The first number",+ },+ "y": {+ "type": "number",+ "description": "The second number",+ },+ },+ "required": ["x", "y"],+ },+ },+ },+ )++ # Test execution+ state = AgentState()+ tool_call = ToolCallBlock(+ id="test_multiply",+ name="multiply_numbers",+ input=json.dumps({"x": 2.5, "y": 4.0}),+ )++ chunks = []+ response = None+ async for result in toolkit.call_tool(tool_call, state):+ if isinstance(result, ToolChunk):+ chunks.append(result)+ elif isinstance(result, ToolResponse):+ response = result++ # Verify chunks+ self.assertEqual(len(chunks), 1)+ self.assertDictEqual(+ chunks[0].model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Product: 10.0",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify response+ self.assertIsNotNone(response)+ self.assertDictEqual(+ response.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "Product: 10.0",+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_multiply",+ },+ )++ async def test_async_streaming_function(self) -> None:+ """Test registering an asynchronous streaming function."""++ async def generate_sequence(+ start: int,+ end: int,+ ) -> AsyncGenerator[ToolChunk, None]:+ """Generate a sequence of numbers.++ Args:+ start: The starting number+ end: The ending number+ """+ for i in range(start, end + 1):+ yield ToolChunk(+ content=[TextBlock(text=f"Number: {i}")],+ )++ toolkit = Toolkit()+ toolkit.register_function(generate_sequence, group="basic")++ # Test schema+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 1)+ self.assertDictEqual(+ schemas[0],+ {+ "type": "function",+ "function": {+ "name": "generate_sequence",+ "description": "Generate a sequence of numbers.",+ "parameters": {+ "type": "object",+ "properties": {+ "start": {+ "type": "integer",+ "description": "The starting number",+ },+ "end": {+ "type": "integer",+ "description": "The ending number",+ },+ },+ "required": ["start", "end"],+ },+ },+ },+ )++ # Test execution+ state = AgentState()+ tool_call = ToolCallBlock(+ id="test_sequence",+ name="generate_sequence",+ input=json.dumps({"start": 5, "end": 7}),+ )++ chunks = []+ response = None+ async for result in toolkit.call_tool(tool_call, state):+ if isinstance(result, ToolChunk):+ chunks.append(result)+ elif isinstance(result, ToolResponse):+ response = result++ # Verify chunks+ self.assertEqual(len(chunks), 3)+ for chunk, num in zip(chunks, [5, 6, 7]):+ self.assertDictEqual(+ chunk.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": f"Number: {num}",+ },+ ],+ "state": "running",+ "is_last": True,+ "metadata": {},+ "id": AnyString(),+ },+ )++ # Verify response - consecutive TextBlocks are merged+ self.assertIsNotNone(response)+ self.assertDictEqual(+ response.model_dump(),+ {+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ # All consecutive TextBlocks merged+ "text": "Number: 5Number: 6Number: 7",+ },+ ],+ "state": "finished",+ "metadata": {},+ "id": "test_sequence",+ },+ )+++class ToolGroupTest(IsolatedAsyncioTestCase):+ """The tool group test case."""++ async def asyncSetUp(self) -> None:+ """The async setup method."""+ self.meta_tool_description = (+ "This tool allows you to reset your equipped tools based on your "+ "current task requirements. These tools are organized into "+ "different groups, and you can activate/deactivate them "+ "by specifying the boolean values for each group in the input.\n\n"+ "**Important: The input booleans are the final state of their "+ "corresponding tool groups, not incremental changes.** Any "+ "group not explicitly set to True will be deactivated, "+ "regardless of its previous state.\n\n"+ "**Best practice**: Actively manage your tool groups——activate "+ "only what you need for the current task, and promptly "+ "deactivate groups as soon as they are no longer needed to"+ " conserve context space.\n\n"+ "This tool will return the usage instructions for the activated "+ "tool groups, which you **MUST pay attention to and follow**. "+ "You can also reuse this tool to re-check the instructions."+ )++ async def test_meta_tool(self) -> None:+ """Test creating a tool group."""+ toolkit = Toolkit()++ # Test meta tool when no groups exist+ schemas = toolkit.get_function_schemas()+ self.assertEqual(len(schemas), 0)++ # Without tools+ toolkit.create_tool_group(+ group_name="group_1",+ description="Group 1",+ )++ # The group is created successfully+ self.assertEqual(len(toolkit.groups), 1)+ # The builtin meta tool is activated+ schemas = toolkit.get_function_schemas()++ self.assertListEqual(+ schemas,+ [+ {+ "type": "function",+ "function": {+ "name": "reset_tools",+ "description": self.meta_tool_description,+ "parameters": {+ "properties": {+ "group_1": {+ "default": False,+ "description": "Group 1",+ "type": "boolean",+ },+ },+ "type": "object",+ },+ },+ },+ ],+ )++ # Name conflict+ with self.assertRaises(ValueError):+ toolkit.create_tool_group(+ group_name="group_1",+ description="xxx",+ )++ # A new group with tools+ toolkit.create_tool_group(+ group_name="group_2",+ description="Group 2",+ instructions="This is group 2.",+ tools=[Tool1(), Tool2()],+ )++ self.assertEqual(len(toolkit.groups), 2)+ schemas = toolkit.get_function_schemas()+ self.assertListEqual(+ schemas,+ [+ {+ "type": "function",+ "function": {+ "name": "reset_tools",+ "description": self.meta_tool_description,+ "parameters": {+ "properties": {+ "group_1": {+ "default": False,+ "description": "Group 1",+ "type": "boolean",+ },+ "group_2": {+ "default": False,+ "description": "Group 2",+ "type": "boolean",+ },+ },+ "type": "object",+ },+ },+ },+ ],+ )++ # Active one group+ state = AgentState()+ res = toolkit.call_tool(+ ToolCallBlock(+ id="xxx",+ name="reset_tools",+ input=json.dumps({"group_2": True}),+ ),+ state,+ )++ chunk = await anext(res)+ self.assertIsInstance(chunk, ToolChunk)++ chunk = await anext(res)+ self.assertIsInstance(chunk, ToolResponse)++ self.assertDictEqual(+ chunk.model_dump(),+ {+ "id": AnyString(),+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": """The currently activated tool group(s): group_2.+<tool-instructions>+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.+<group name="group_2">This is group 2.</group>+</tool-instructions>""", # noqa: E501+ },+ ],+ "metadata": {},+ "state": "finished",+ },+ )++ # Activate both groups+ res = toolkit.call_tool(+ ToolCallBlock(+ id="xxx",+ name="reset_tools",+ input=json.dumps({"group_2": True, "group_1": True}),+ ),+ state,+ )++ last_chunk = None+ async for chunk in res:+ last_chunk = chunk++ self.assertDictEqual(+ last_chunk.model_dump(),+ {+ "id": AnyString(),+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": """The currently activated tool group(s): group_2, group_1.+<tool-instructions>+The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.+<group name="group_2">This is group 2.</group>+</tool-instructions>""", # noqa: E501+ },+ ],+ "metadata": {},+ "state": "finished",+ },+ )++ # deactivate all groups+ res = toolkit.call_tool(+ ToolCallBlock(+ id="xxx",+ name="reset_tools",+ input=json.dumps({}),+ ),+ state,+ )++ last_chunk = None+ async for chunk in res:+ last_chunk = chunk++ self.assertDictEqual(+ last_chunk.model_dump(),+ {+ "id": AnyString(),+ "content": [+ {+ "type": "text",+ "id": AnyString(),+ "text": "All tool groups are currently deactivated.",+ },+ ],+ "metadata": {},+ "state": "finished",+ },+ )