Skip to content

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

feat(toolkit): support different strategies when registering duplicated tools in toolkit (#939)

DavdGaod662bec3aa81
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index 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: 21
days-before-close: 3
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 8c648bb32..aa19a2548 100644
--- a/src/agentscope/_utils/_common.py
+++ b/src/agentscope/_utils/_common.py
@@ -14,10 +14,12 @@ from datetime import datetime
from typing import Union, Any, Callable, Type, Dict
import requests
+from docstring_parser import parse
from json_repair import repair_json
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, create_model, ConfigDict
from .._logging import logger
+from ..types import ToolFunction
if 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_schema
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
index d7eb7beb0..a2c2b5f26 100644
--- a/src/agentscope/tool/_toolkit.py
+++ b/src/agentscope/tool/_toolkit.py
@@ -9,7 +9,6 @@ from functools import partial
from typing import (
AsyncGenerator,
Literal,
- Dict,
Any,
Type,
Generator,
@@ -17,13 +16,12 @@ from typing import (
Awaitable,
)
+import shortuuid
from pydantic import (
BaseModel,
Field,
create_model,
- ConfigDict,
)
-from docstring_parser import parse
from ._async_wrapper import (
_async_generator_wrapper,
@@ -32,7 +30,7 @@ from ._async_wrapper import (
)
from ._registered_tool_function import RegisteredToolFunction
from ._response import ToolResponse
-from .._utils._common import _remove_title_field
+from .._utils._common import _parse_tool_function
from ..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 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.
"""
# Arguments checking
if 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.name
original_func = tool_func.__call__
- self._validate_tool_function(func_name)
json_schema = json_schema or tool_func.json_schema
mcp_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 function
func_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_obj
def 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 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)
@@ -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_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,
)
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_schema
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
index 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 asyncio
import 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 function
self.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 model
self.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