feat: 添加工具名称标准化功能，确保符合外部提供者限制并增加单元测试

Change-Id: Ic4a12c5033dd68a37a256a4ee0ad2dfafc804793
Signed-off-by: OhYee <oyohyee@oyohyee.com>

Author: OhYee

agentrun/integration/google_adk/tool_adapter.py

@@ -6,6 +6,7 @@
 
 from agentrun.integration.utils.adapter import ToolAdapter
 from agentrun.integration.utils.canonical import CanonicalTool
+from agentrun.integration.utils.tool import normalize_tool_name
 
 
 def _json_schema_to_google_schema(
@@ -179,7 +180,7 @@ class GoogleADKToolAdapter(ToolAdapter):
 
     def get_registered_tool(self, name: str) -> Optional[CanonicalTool]:
         """根据名称获取最近注册的工具定义 / Google ADK Tool Adapter"""
-        return self._registered_tools.get(name)
+        return self._registered_tools.get(normalize_tool_name(name))
 
     def from_canonical(self, tools: List[CanonicalTool]):
         """将标准格式转换为 Google ADK 工具 / Google ADK Tool Adapter
@@ -207,7 +208,7 @@ def from_canonical(self, tools: List[CanonicalTool]):
 
             # 创建 FunctionDeclaration
             declaration = types.FunctionDeclaration(
-                name=tool.name,
+                name=normalize_tool_name(tool.name),
                 description=tool.description or "",
                 parameters=google_schema,
             )

agentrun/integration/utils/adapter.py

@@ -16,6 +16,7 @@
 
 from agentrun.integration.utils.canonical import CanonicalMessage, CanonicalTool
 from agentrun.integration.utils.model import CommonModel
+from agentrun.integration.utils.tool import normalize_tool_name
 
 # 用于缓存动态创建的 Pydantic 模型，避免重复创建
 _dynamic_models_cache: Dict[str, type] = {}
@@ -510,8 +511,8 @@ def tool_func(**kwargs):
 
                     return canonical_tool.func(**kwargs)
 
-                # 设置函数元数据
-                tool_func.__name__ = canonical_tool.name
+                # 设置函数元数据（函数名也需要标准化以防第三方工具名限制）
+                tool_func.__name__ = normalize_tool_name(canonical_tool.name)
 
                 # 生成文档字符串
                 base_doc = canonical_tool.description or ""

agentrun/integration/utils/canonical.py

@@ -18,6 +18,8 @@
 
 from enum import Enum
 
+from agentrun.integration.utils.tool import normalize_tool_name
+
 
 class MessageRole(str, Enum):
     """统一的消息角色枚举"""
@@ -102,6 +104,11 @@ class CanonicalTool:
     parameters: Dict[str, Any]  # JSON Schema 格式
     func: Optional[Callable] = None
 
+    def __post_init__(self):
+        # Normalize canonical tool name to avoid exceeding provider limits
+        if self.name:
+            self.name = normalize_tool_name(self.name)
+
     def to_openai_function(self) -> Dict[str, Any]:
         """转换为 OpenAI Function Calling 格式"""
         return {

agentrun/integration/utils/tool.py

@@ -19,6 +19,7 @@
 
 from copy import deepcopy
 from functools import wraps
+import hashlib
 import inspect
 import json
 import re
@@ -47,6 +48,25 @@
 from agentrun.toolset import ToolSet
 from agentrun.utils.log import logger
 
+# Tool name constraints for external providers like OpenAI
+MAX_TOOL_NAME_LEN = 64
+TOOL_NAME_HEAD_LEN = 32
+
+
+def normalize_tool_name(name: str) -> str:
+    """Normalize a tool name to fit provider limits.
+
+    If `name` length is <= MAX_TOOL_NAME_LEN, return it unchanged.
+    Otherwise, return the first TOOL_NAME_HEAD_LEN characters + md5(full_name)
+    (32 hex chars), resulting in a 64-char string.
+    """
+    if not isinstance(name, str):
+        name = str(name)
+    if len(name) <= MAX_TOOL_NAME_LEN:
+        return name
+    digest = hashlib.md5(name.encode("utf-8")).hexdigest()
+    return name[:TOOL_NAME_HEAD_LEN] + digest
+
 
 class ToolParameter:
     """工具参数定义
@@ -253,7 +273,9 @@ def __init__(
         args_schema: Optional[Type[BaseModel]] = None,
         func: Optional[Callable] = None,
     ):
-        self.name = name
+        # Normalize tool name to avoid external provider limits (e.g. OpenAI 64 chars)
+        # If name length > 64, keep first 32 chars and append 32-char md5 sum of full name.
+        self.name = normalize_tool_name(name)
         self.description = description
         self.parameters = list(parameters or [])
         self.args_schema = args_schema or _build_args_model_from_parameters(
@@ -982,6 +1004,8 @@ def tool(
 
     def decorator(func: Callable) -> Tool:
         tool_name = name or func.__name__
+        # ensure tool name is normalized
+        tool_name = normalize_tool_name(tool_name)
         tool_description = description or (
             func.__doc__.strip() if func.__doc__ else ""
         )
@@ -1362,6 +1386,7 @@ def wrapper(**kwargs):
 
     # 设置函数属性（清理特殊字符，确保是有效的 Python 标识符）
     clean_name = re.sub(r"[^0-9a-zA-Z_]", "_", tool_name)
+    clean_name = normalize_tool_name(clean_name)
     wrapper.__name__ = clean_name
     wrapper.__qualname__ = clean_name
     if parameters:

agentrun/toolset/api/openapi.py

@@ -11,6 +11,7 @@
 import httpx
 from pydash import get as pg
 
+from agentrun.integration.utils.tool import normalize_tool_name
 from agentrun.utils.config import Config
 from agentrun.utils.log import logger
 from agentrun.utils.model import BaseModel
@@ -322,6 +323,8 @@ def wrapper(**kwargs):
 
         # 设置函数属性
         clean_name = re.sub(r"[^0-9a-zA-Z_]", "_", name)
+        # Normalize for provider limits / external frameworks
+        clean_name = normalize_tool_name(clean_name)
         wrapper.__name__ = clean_name
         wrapper.__qualname__ = clean_name
         wrapper.__doc__ = "\n".join(doc_parts)
@@ -609,7 +612,7 @@ def from_openapi_schema(
 
                         tools.append(
                             ToolInfo(
-                                name=operation_id,
+                                name=normalize_tool_name(operation_id),
                                 description=description,
                                 parameters=parameters,
                             )
@@ -682,7 +685,7 @@ def from_mcp_tools(
 
                 tool_infos.append(
                     ToolInfo(
-                        name=tool_name,
+                        name=normalize_tool_name(tool_name),
                         description=tool_description,
                         parameters=parameters
                         or ToolSchema(type="object", properties={}),

tests/unittests/integration/test_toolname_normalize.py

@@ -0,0 +1,77 @@
+import hashlib
+import json
+
+from agentrun.integration.utils.canonical import CanonicalTool
+from agentrun.integration.utils.tool import normalize_tool_name, Tool
+from agentrun.toolset.api.openapi import ApiSet
+
+
+def test_normalize_tool_name_short():
+    name = "short_name"
+    assert normalize_tool_name(name) == name
+
+
+def test_normalize_tool_name_long():
+    long_name = "a" * 80
+    normalized = normalize_tool_name(long_name)
+    assert len(normalized) == 64
+    assert normalized[:32] == long_name[:32]
+    expected_md5 = hashlib.md5(long_name.encode("utf-8")).hexdigest()
+    assert normalized[32:] == expected_md5
+
+
+def test_tool_normalizes_in_tool_class():
+    long_name = "tool_" + "x" * 80
+    t = Tool(name=long_name, func=lambda: None)
+    assert len(t.name) <= 64
+    assert t.name == normalize_tool_name(long_name)
+
+
+def test_canonical_tool_normalizes():
+    long_name = "canonical_" + "y" * 80
+    c = CanonicalTool(name=long_name, description="desc", parameters={})
+    assert c.name == normalize_tool_name(long_name)
+
+
+def test_openapi_from_schema_tool_name_truncation():
+    long_name = "op_" + "z" * 100
+    schema = {
+        "openapi": "3.0.0",
+        "paths": {
+            "/test": {
+                "get": {
+                    "operationId": long_name,
+                    "responses": {
+                        "200": {
+                            "content": {
+                                "application/json": {
+                                    "schema": {"type": "string"}
+                                }
+                            }
+                        }
+                    },
+                }
+            }
+        },
+    }
+
+    apiset = ApiSet.from_openapi_schema(schema=json.dumps(schema))
+    names = [t.name for t in apiset.tools()]
+    assert normalize_tool_name(long_name) in names
+
+
+def test_google_adk_declaration_name_normalized():
+    try:
+        from agentrun.integration.google_adk.tool_adapter import (
+            GoogleADKToolAdapter,
+        )
+    except Exception:
+        # google.genai not installed — skip
+        return
+
+    long_name = "gtool_" + "x" * 100
+    ct = CanonicalTool(name=long_name, description="d", parameters={})
+    adapter = GoogleADKToolAdapter()
+    tools = adapter.from_canonical([ct])
+    decl = tools[0]._get_declaration()
+    assert decl.name == normalize_tool_name(long_name)