Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(toolkit): support different strategies when registering duplicated tools in toolkit (#939)
DavdGaod662bec3aa81
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.ymlindex 26bed3d3b..a68e83eb5 100644--- a/.github/workflows/stale.yml+++ b/.github/workflows/stale.yml@@ -24,6 +24,7 @@ jobs:stale-issue-message: 'This issue is marked as stale because there has been no activity for 21 days. Remove stale label or add new comments or this issue will be closed in 3 day.'close-issue-message: 'Close this stale issue.'stale-issue-label: 'stale-issue'+ exempt-issue-labels: 'RoadMap,Roadmap'days-before-stale: 21days-before-close: 3diff --git a/pyproject.toml b/pyproject.tomlindex dfcbd1eb6..671ff8b32 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -57,7 +57,9 @@ full = ["pypdf","python-docx","nltk",- "qdrant-client",+ # The qdrant-client >= 1.16.0 has conflicts with pymilvus, so we fix+ # the version to 1.15.1 here.+ "qdrant-client==1.15.1",]dev = [# Include full dependencies from local package@@ -65,12 +67,12 @@ dev = [# Development tools"pre-commit","pytest",+ "pytest-forked","sphinx-gallery","furo","myst_parser","matplotlib","pymilvus[milvus_lite]",- # Long-term memory][project.urls]diff --git a/src/agentscope/_utils/_common.py b/src/agentscope/_utils/_common.pyindex 8c648bb32..aa19a2548 100644--- a/src/agentscope/_utils/_common.py+++ b/src/agentscope/_utils/_common.py@@ -14,10 +14,12 @@ from datetime import datetimefrom typing import Union, Any, Callable, Type, Dictimport requests+from docstring_parser import parsefrom json_repair import repair_json-from pydantic import BaseModel+from pydantic import BaseModel, Field, create_model, ConfigDictfrom .._logging import logger+from ..types import ToolFunctionif typing.TYPE_CHECKING:from mcp.types import Tool@@ -283,3 +285,122 @@ 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\n".join(descriptions)++ # Create a dynamic model with the function signature+ fields = {}+ for name, param in inspect.signature(tool_func).parameters.items():+ # Skip the `self` and `cls` parameters+ if name in ["self", "cls"]:+ continue++ # Handle `**kwargs`+ if param.kind == inspect.Parameter.VAR_KEYWORD:+ if not include_var_keyword:+ continue++ fields[name] = (+ Dict[str, Any]+ if param.annotation == inspect.Parameter.empty+ else Dict[str, param.annotation], # type: ignore+ Field(+ description=params_docstring.get(+ f"**{name}",+ params_docstring.get(name, None),+ ),+ default={}+ if param.default is param.empty+ else param.default,+ ),+ )++ elif param.kind == inspect.Parameter.VAR_POSITIONAL:+ if not include_var_positional:+ continue++ fields[name] = (+ list[Any]+ if param.annotation == inspect.Parameter.empty+ else list[param.annotation], # type: ignore+ Field(+ description=params_docstring.get(+ f"*{name}",+ params_docstring.get(name, None),+ ),+ default=[]+ if param.default is param.empty+ else param.default,+ ),+ )++ else:+ fields[name] = (+ Any+ if param.annotation == inspect.Parameter.empty+ else param.annotation,+ Field(+ description=params_docstring.get(name, None),+ default=...+ if param.default is param.empty+ else param.default,+ ),+ )++ base_model = create_model(+ "_StructuredOutputDynamicClass",+ __config__=ConfigDict(arbitrary_types_allowed=True),+ **fields,+ )+ params_json_schema = base_model.model_json_schema()++ # Remove the title from the json schema+ _remove_title_field(params_json_schema)++ func_json_schema: dict = {+ "type": "function",+ "function": {+ "name": tool_func.__name__,+ "parameters": params_json_schema,+ },+ }++ if func_description not in [None, ""]:+ func_json_schema["function"]["description"] = func_description++ return func_json_schemadiff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.pyindex d7eb7beb0..a2c2b5f26 100644--- a/src/agentscope/tool/_toolkit.py+++ b/src/agentscope/tool/_toolkit.py@@ -9,7 +9,6 @@ from functools import partialfrom typing import (AsyncGenerator,Literal,- Dict,Any,Type,Generator,@@ -17,13 +16,12 @@ from typing import (Awaitable,)+import shortuuidfrom pydantic import (BaseModel,Field,create_model,- ConfigDict,)-from docstring_parser import parsefrom ._async_wrapper import (_async_generator_wrapper,@@ -32,7 +30,7 @@ from ._async_wrapper import ()from ._registered_tool_function import RegisteredToolFunctionfrom ._response import ToolResponse-from .._utils._common import _remove_title_field+from .._utils._common import _parse_tool_functionfrom ..mcp import (MCPToolFunction,MCPClientBase,@@ -187,7 +185,8 @@ class Toolkit(StateModule):if self.tools[tool_name].group in group_names:self.tools.pop(tool_name)- def register_tool_function( # pylint: disable=too-many-branches+ # pylint: disable=too-many-branches, too-many-statements+ def register_tool_function(self,tool_func: ToolFunction,group_name: str | Literal["basic"] = "basic",@@ -208,6 +207,12 @@ class Toolkit(StateModule):])| None = None,+ namesake_strategy: Literal[+ "override",+ "skip",+ "raise",+ "rename",+ ] = "raise",) -> None:"""Register a tool function to the toolkit.@@ -250,6 +255,15 @@ class Toolkit(StateModule):async. If it returns `None`, the tool result will bereturned 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."""# Arguments checkingif group_name not in self.groups and group_name != "basic":@@ -272,7 +286,6 @@ class Toolkit(StateModule):if isinstance(tool_func, MCPToolFunction):func_name = tool_func.nameoriginal_func = tool_func.__call__- self._validate_tool_function(func_name)json_schema = json_schema or tool_func.json_schemamcp_name = tool_func.mcp_name@@ -295,8 +308,7 @@ class Toolkit(StateModule):func_name = tool_func.func.__name__original_func = tool_func.func- self._validate_tool_function(func_name)- json_schema = json_schema or self._parse_tool_function(+ json_schema = json_schema or _parse_tool_function(tool_func.func,include_long_description=include_long_description,include_var_positional=include_var_positional,@@ -307,8 +319,7 @@ class Toolkit(StateModule):# normal functionfunc_name = tool_func.__name__original_func = tool_func- self._validate_tool_function(func_name)- json_schema = json_schema or self._parse_tool_function(+ json_schema = json_schema or _parse_tool_function(tool_func,include_long_description=include_long_description,include_var_positional=include_var_positional,@@ -352,7 +363,65 @@ class Toolkit(StateModule):postprocess_func=postprocess_func,)- self.tools[func_name] = func_obj+ 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.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_objdef remove_tool_function(self,@@ -632,6 +701,12 @@ class Toolkit(StateModule):])| None = None,+ namesake_strategy: Literal[+ "override",+ "skip",+ "raise",+ "rename",+ ] = "raise",) -> None:"""Register tool functions from an MCP client.@@ -659,6 +734,15 @@ class Toolkit(StateModule):async. If it returns `None`, the tool result will bereturned 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)@@ -725,12 +809,12 @@ class Toolkit(StateModule):if preset_kwargs_mapping is not None:preset_kwargs = preset_kwargs_mapping.get(mcp_tool.name, {})- # TODO: handle mcp_server_nameself.register_tool_function(tool_func=func_obj,group_name=group_name,preset_kwargs=preset_kwargs,postprocess_func=postprocess_func,+ namesake_strategy=namesake_strategy,)logger.info(@@ -863,111 +947,6 @@ class Toolkit(StateModule):so, raise a ValueError."""if func_name in self.tools:raise ValueError(- f"A function with name '{func_name} is already registered "+ f"A function with name '{func_name}' is already registered ""in the toolkit.",)-- @staticmethod- 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"""- 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\n".join(descriptions)-- # Create a dynamic model with the function signature- fields = {}- for name, param in inspect.signature(tool_func).parameters.items():- # Skip the `self` and `cls` parameters- if name in ["self", "cls"]:- continue-- # Handle `**kwargs`- if param.kind == inspect.Parameter.VAR_KEYWORD:- if not include_var_keyword:- continue-- fields[name] = (- Dict[str, Any]- if param.annotation == inspect.Parameter.empty- else Dict[str, param.annotation], # type: ignore- Field(- description=params_docstring.get(- f"**{name}",- params_docstring.get(name, None),- ),- default={}- if param.default is param.empty- else param.default,- ),- )-- elif param.kind == inspect.Parameter.VAR_POSITIONAL:- if not include_var_positional:- continue-- fields[name] = (- list[Any]- if param.annotation == inspect.Parameter.empty- else list[param.annotation], # type: ignore- Field(- description=params_docstring.get(- f"*{name}",- params_docstring.get(name, None),- ),- default=[]- if param.default is param.empty- else param.default,- ),- )-- else:- fields[name] = (- Any- if param.annotation == inspect.Parameter.empty- else param.annotation,- Field(- description=params_docstring.get(name, None),- default=...- if param.default is param.empty- else param.default,- ),- )-- base_model = create_model(- "_StructuredOutputDynamicClass",- __config__=ConfigDict(arbitrary_types_allowed=True),- **fields,- )- params_json_schema = base_model.model_json_schema()-- # Remove the title from the json schema- _remove_title_field(params_json_schema)-- func_json_schema: dict = {- "type": "function",- "function": {- "name": tool_func.__name__,- "parameters": params_json_schema,- },- }-- if func_description not in [None, ""]:- func_json_schema["function"]["description"] = func_description-- return func_json_schemadiff --git a/tests/toolkit_test.py b/tests/toolkit_test.pyindex 23edcabd8..605a02691 100644--- a/tests/toolkit_test.py+++ b/tests/toolkit_test.py@@ -1,4 +1,5 @@# -*- coding: utf-8 -*-+# mypy: disable-error-code="index""""Test toolkit module in agentscope."""import asyncioimport time@@ -70,6 +71,21 @@ def sync_func()+class TestCls:+ """A test class for testing."""++ def sync_func(self) -> ToolResponse:+ """A duplicate sync function for testing."""+ return ToolResponse(+ content=[+ TextBlock(+ type="text",+ text="test",+ ),+ ],+ )++async def async_generator_func(raise_cancel: bool,) -> AsyncGenerator[ToolResponse, None]:@@ -118,16 +134,146 @@ class ToolkitTest(IsolatedAsyncioTestCase):"""Set up the test environment before each test."""self.toolkit = Toolkit()- async def test_basic_functionalities(self) -> None:- """Test sync function:- 1. register tool function- 2. set/cancel extended model- 3. get JSON schemas- 4. call tool function- """+ self.sync_func_schema = {+ "type": "function",+ "function": {+ "name": "sync_func",+ "parameters": {+ "properties": {+ "arg1": {+ "description": "Test argument 1.",+ "type": "integer",+ },+ "arg2": {+ "anyOf": [+ {+ "items": {+ "anyOf": [+ {"type": "string"},+ {"type": "integer"},+ ],+ },+ "type": "array",+ },+ {"type": "null"},+ ],+ "default": None,+ "description": "Test argument 2.",+ },+ },+ "required": ["arg1"],+ "type": "object",+ },+ "description": "A sync function for testing.\n\n"+ "Long description.",+ },+ }++ async def test_duplicate_tool_registration(self) -> None:+ """Test duplicate tool function registration."""+ tool_call = ToolUseBlock(+ type="tool_use",+ id="123",+ name="sync_func",+ input={+ "arg1": 55,+ },+ )++ # Add a functionself.toolkit.register_tool_function(- tool_func=sync_func,- preset_kwargs={"arg1": 55},+ sync_func,+ )+ self.assertListEqual(+ [self.sync_func_schema],+ self.toolkit.get_json_schemas(),+ )+ async for chunk in await self.toolkit.call_tool_function(tool_call):+ self.assertListEqual(+ chunk.content,+ [+ TextBlock(+ type="text",+ text="arg1: 55, arg2: None",+ ),+ ],+ )++ test = TestCls()++ # Try to add the same function with raise strategy+ with self.assertRaises(ValueError):+ self.toolkit.register_tool_function(test.sync_func)++ # Try to add the same function with skip strategy+ self.toolkit.register_tool_function(+ test.sync_func,+ namesake_strategy="skip",+ )+ self.assertListEqual(+ [self.sync_func_schema],+ self.toolkit.get_json_schemas(),+ )++ # Try to add the same function with rename strategy+ self.toolkit.register_tool_function(+ test.sync_func,+ namesake_strategy="rename",+ )+ new_func_name = list(self.toolkit.tools.keys())[1]+ new_func_schema = {+ "type": "function",+ "function": {+ "name": new_func_name,+ "parameters": {+ "properties": {},+ "type": "object",+ },+ "description": "A duplicate sync function for testing.",+ },+ }+ self.assertListEqual(+ [+ self.sync_func_schema,+ new_func_schema,+ ],+ self.toolkit.get_json_schemas(),+ )+ self.assertTrue(new_func_name.startswith("sync_func_"))+ res = await self.toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="123",+ name=new_func_name,+ input={},+ ),+ )+ async for chunk in res:+ self.assertListEqual(+ chunk.content,+ [+ TextBlock(+ type="text",+ text="test",+ ),+ ],+ )+ res = await self.toolkit.call_tool_function(tool_call)+ async for chunk in res:+ self.assertListEqual(+ chunk.content,+ [+ TextBlock(+ type="text",+ text="arg1: 55, arg2: None",+ ),+ ],+ )++ # Try to add the same function with override strategy+ self.toolkit.register_tool_function(+ test.sync_func,+ namesake_strategy="override",)self.assertListEqual([@@ -136,39 +282,54 @@ class ToolkitTest(IsolatedAsyncioTestCase):"function": {"name": "sync_func","parameters": {- "properties": {- "arg2": {- "anyOf": [- {- "items": {- "anyOf": [- {- "type": "string",- },- {- "type": "integer",- },- ],- },- "type": "array",- },- {- "type": "null",- },- ],- "default": None,- "description": "Test argument 2.",- },- },+ "properties": {},"type": "object",},- "description": "A sync function for testing.\n\n"- "Long description.",+ "description": "A duplicate sync function "+ "for testing.",},},+ new_func_schema,],self.toolkit.get_json_schemas(),)+ res = await self.toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="123",+ name="sync_func",+ input={},+ ),+ )+ async for chunk in res:+ self.assertListEqual(+ chunk.content,+ [+ TextBlock(+ type="text",+ text="test",+ ),+ ],+ )++ async def test_basic_functionalities(self) -> None:+ """Test sync function:+ 1. register tool function+ 2. set/cancel extended model+ 3. get JSON schemas+ 4. call tool function+ """+ self.toolkit.register_tool_function(+ tool_func=sync_func,+ preset_kwargs={"arg1": 55},+ )+ sync_func_schema = deepcopy(self.sync_func_schema)+ sync_func_schema["function"]["parameters"]["properties"].pop("arg1")+ sync_func_schema["function"]["parameters"].pop("required")+ self.assertListEqual(+ [sync_func_schema],+ self.toolkit.get_json_schemas(),+ )# Test extended modelself.toolkit.set_extended_model(@@ -225,43 +386,7 @@ class ToolkitTest(IsolatedAsyncioTestCase):self.toolkit.set_extended_model("sync_func", None)self.assertListEqual(- [- {- "type": "function",- "function": {- "name": "sync_func",- "parameters": {- "properties": {- "arg2": {- "anyOf": [- {- "items": {- "anyOf": [- {- "type": "string",- },- {- "type": "integer",- },- ],- },- "type": "array",- },- {- "type": "null",- },- ],- "default": None,- "description": "Test argument 2.",- },- },- "type": "object",- },- "description": "A sync function for testing.\n\n"- "Long description.",- },- },- ],+ [sync_func_schema],self.toolkit.get_json_schemas(),)@@ -581,42 +706,7 @@ class ToolkitTest(IsolatedAsyncioTestCase):self.toolkit.update_tool_groups(["my_group"], True)self.assertListEqual(self.toolkit.get_json_schemas(),- [- {- "type": "function",- "function": {- "name": "sync_func",- "parameters": {- "properties": {- "arg1": {- "description": "Test argument 1.",- "type": "integer",- },- "arg2": {- "anyOf": [- {- "items": {- "anyOf": [- {"type": "string"},- {"type": "integer"},- ],- },- "type": "array",- },- {"type": "null"},- ],- "default": None,- "description": "Test argument 2.",- },- },- "required": ["arg1"],- "type": "object",- },- "description": "A sync function for testing.\n\n"- "Long description.",- },- },- ],+ [self.sync_func_schema],)# Deactivate the tool group