Skip to content

Build and run agents you can see, understand and trust.

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.py
index 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 tool
print("\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 tool
print("\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.py
index 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.py
index 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.py
index 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.toml
index 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.py
index 995954f74..118e23213 100644
--- a/src/agentscope/_utils/_common.py
+++ b/src/agentscope/_utils/_common.py
@@ -9,15 +9,12 @@ import os
import types
import uuid
from datetime import datetime
-from typing import Any, Callable, Type, Dict
+from typing import Any, Callable
import requests
-from docstring_parser import parse
from json_repair import repair_json
-from pydantic import BaseModel, Field, create_model, ConfigDict
from .._logging import logger
-from ..types import ToolFunction
def _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_schema
diff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.py
index 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 AgentState
from ._agent import Agent
-__all__ = ["Agent"]
+__all__ = ["Agent", "AgentState"]
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 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 dataclass
from typing import AsyncGenerator, Literal
from ..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, ChatModelBase
from ..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.py
new file mode 100644
index 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__.py
index 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.py
similarity index 71%
rename from src/agentscope/exception/_exception_base.py
rename to src/agentscope/exception/_base.py
index 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 = message
diff --git a/src/agentscope/exception/_tool.py b/src/agentscope/exception/_tool.py
index 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 AgentOrientedExceptionBase
class ToolNotFoundError(AgentOrientedExceptionBase):
diff --git a/src/agentscope/mcp/__init__.py b/src/agentscope/mcp/__init__.py
index 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 MCPToolFunction
from ._stateful_client_base import StatefulClientBase
from ._stdio_stateful_client import StdIOStatefulClient
from ._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.py
index 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 = Any
class 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.py
index 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_CHECKING
import mcp.types
from mcp import ClientSession
from mcp.client.sse import sse_client
from mcp.client.streamable_http import streamable_http_client
-from . import MCPToolFunction
from ._client_base import MCPClientBase
-from ..tool import ToolResponse
+
+if TYPE_CHECKING:
+ from ..tool import MCPTool
+else:
+ MCPTool = Any
class 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 = None
for tool in self._tools:
- if tool.name == func_name:
+ if tool.name == name:
target_tool = tool
break
if 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.py
deleted file mode 100644
index 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 res
diff --git a/src/agentscope/mcp/_stateful_client_base.py b/src/agentscope/mcp/_stateful_client_base.py
index 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 ABC
from contextlib import AsyncExitStack
-from typing import List
+from typing import List, TYPE_CHECKING, Any
import mcp
from mcp import ClientSession
from ._client_base import MCPClientBase
-from ._mcp_function import MCPToolFunction
from .._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.tools
return 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 = None
for tool in self._cached_tools:
- if tool.name == func_name:
+ if tool.name == name:
target_tool = tool
break
if 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.py
index 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 ChatResponse
from ._model_usage import ChatUsage
from ..formatter import FormatterBase, AnthropicChatFormatter
from ..message import TextBlock, ToolCallBlock, ThinkingBlock
+from ..tool import ToolChoice
from ..tracing import trace_llm
-from ..types import JSONSerializableObject, ToolChoice
+from ..types import JSONSerializableObject
if TYPE_CHECKING:
from anthropic.types.message import Message
diff --git a/src/agentscope/model/_dashscope_model.py b/src/agentscope/model/_dashscope_model.py
index 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 ChatResponse
from ._model_usage import ChatUsage
from ..formatter import FormatterBase, DashScopeChatFormatter
from ..message import TextBlock, ToolCallBlock, ThinkingBlock, Msg
+from ..tool import ToolChoice
from ..tracing import trace_llm
-from ..types import JSONSerializableObject, ToolChoice
+from ..types import JSONSerializableObject
from .._logging import logger
diff --git a/src/agentscope/model/_gemini_model.py b/src/agentscope/model/_gemini_model.py
index 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 ChatUsage
from ._model_base import ChatModelBase
from ._model_response import ChatResponse
from ..tracing import trace_llm
-from ..types import JSONSerializableObject, ToolChoice
+from ..types import JSONSerializableObject
+from ..tool import ToolChoice
if TYPE_CHECKING:
from google.genai.types import GenerateContentResponse
diff --git a/src/agentscope/model/_model_base.py b/src/agentscope/model/_model_base.py
index 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_CHECKING
from ._model_response import ChatResponse
from .._logging import logger
from ..formatter import FormatterBase
from ..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.py
index 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 ToolChoice
from ..tracing import trace_llm
-from ..types import JSONSerializableObject, ToolChoice
+from ..types import JSONSerializableObject
if TYPE_CHECKING:
from openai.types.chat import ChatCompletion
diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.py
index 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, ToolChunk
from ._toolkit import Toolkit
+from ._base import ToolBase
+from ._adapters import MCPTool
from ._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.py
new file mode 100644
index 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_content
diff --git a/src/agentscope/tool/_async_wrapper.py b/src/agentscope/tool/_async_wrapper.py
deleted file mode 100644
index 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.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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 to
parse 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 self
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
index 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 asyncio
import inspect
import os
+from collections import OrderedDict
from copy import deepcopy
-from functools import partial, wraps
+from functools import wraps
from typing import (
AsyncGenerator,
- Literal,
Any,
Type,
Generator,
Callable,
- Awaitable,
Coroutine,
+ TYPE_CHECKING,
)
import mcp
-import shortuuid
from 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 DeveloperOrientedException
from ..mcp import (
- MCPToolFunction,
MCPClientBase,
StatefulClientBase,
)
@@ -45,13 +38,13 @@ from ..message import (
ToolCallBlock,
TextBlock,
)
-from ..types import (
- JSONSerializableObject,
- ToolFunction,
-)
-from ..tracing._trace import trace_toolkit
from .._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 tool
functions, 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 not
provided, 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] = registered
def 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 JSON
schema, 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_schemas
def 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 function
try:
- 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_response
async 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`, no
tool 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 execution
self._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_tools
diff --git a/src/agentscope/tool/_types.py b/src/agentscope/tool/_types.py
index 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 deepcopy
from 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 tool
function, 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 schema
for 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
+ ] = value
if 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 models
if "$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 error
raise 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
@dataclass
class 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 group
identifier."""
- 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 tool
group 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"] | str
diff --git a/src/agentscope/tool/_utils.py b/src/agentscope/tool/_utils.py
new file mode 100644
index 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_schema
diff --git a/src/agentscope/types/__init__.py b/src/agentscope/types/__init__.py
index 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.py
deleted file mode 100644
index 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"] | str
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
new file mode 100644
index 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",
+ },
+ )