# app/services/agent/tools/registry.py import inspect import functools from typing import Callable, Dict, Any, List, Optional, get_type_hints, get_origin, get_args from app.core.logger import logger # 上下文保留关键字,这些参数不向 LLM 暴露,而在执行时由框架自动注入 CONTEXT_PARAM_NAMES = {"db", "current_user", "redis_client", "context"} def python_type_to_json_type(py_type: Any) -> str: """将 Python 类型转换为 JSON Schema 类型""" origin = get_origin(py_type) if origin is not None: if origin in (list, List): return "array" if origin in (dict, Dict): return "object" # 处理 Optional[T] / Union[T, None] args = get_args(py_type) non_none_args = [a for a in args if a is not type(None)] if non_none_args: return python_type_to_json_type(non_none_args[0]) if py_type in (int,): return "integer" if py_type in (float,): return "number" if py_type in (bool,): return "boolean" if py_type in (dict, Dict): return "object" if py_type in (list, List): return "array" return "string" class AgentTool: """Agent 工具包装类""" def __init__( self, name: str, description: str, func: Callable, is_dangerous: bool = False, ): self.name = name self.description = description.strip() self.func = func self.is_dangerous = is_dangerous self.is_async = inspect.iscoroutinefunction(func) self.signature = inspect.signature(func) self.type_hints = get_type_hints(func) if hasattr(func, "__annotations__") else {} self.openai_schema = self._build_openai_schema() def _build_openai_schema(self) -> Dict[str, Any]: """根据函数签名自动推导 OpenAI Tool Function Schema""" properties = {} required = [] for param_name, param in self.signature.parameters.items(): if param_name in CONTEXT_PARAM_NAMES: continue param_type = self.type_hints.get(param_name, str) json_type = python_type_to_json_type(param_type) param_desc = f"Parameter {param_name}" # 尝试从 docstring 中提取简单描述(如果存在) properties[param_name] = { "type": json_type, "description": param_desc, } # 判断是否必选 if param.default is inspect.Parameter.empty: # 没有默认值,且不是 Optional origin = get_origin(param_type) args = get_args(param_type) is_optional = origin is not None and type(None) in args if not is_optional: required.append(param_name) return { "type": "function", "function": { "name": self.name, "description": self.description, "parameters": { "type": "object", "properties": properties, "required": required, }, }, } async def execute(self, arguments: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> Any: """执行该工具,并根据需要注入上下文(如 db, current_user)""" context = context or {} call_kwargs = {} for param_name, param in self.signature.parameters.items(): if param_name in CONTEXT_PARAM_NAMES: if param_name in context: call_kwargs[param_name] = context[param_name] elif "context" in context and param_name in context["context"]: call_kwargs[param_name] = context["context"][param_name] elif param_name in arguments: call_kwargs[param_name] = arguments[param_name] elif param.default is not inspect.Parameter.empty: call_kwargs[param_name] = param.default try: if self.is_async: result = await self.func(**call_kwargs) else: result = self.func(**call_kwargs) return result except Exception as e: logger.error(f"[AgentTool:{self.name}] execution error: {e}", exc_info=True) return {"error": str(e)} class ToolRegistry: """全局工具注册中心""" def __init__(self): self._tools: Dict[str, AgentTool] = {} def register( self, name: Optional[str] = None, description: Optional[str] = None, is_dangerous: bool = False, ): """装饰器:注册函数为 Agent 工具""" def decorator(func: Callable): tool_name = name or func.__name__ tool_desc = description or (func.__doc__ or f"Tool {tool_name}").strip() tool = AgentTool( name=tool_name, description=tool_desc, func=func, is_dangerous=is_dangerous, ) self._tools[tool_name] = tool return func return decorator def get_tool(self, name: str) -> Optional[AgentTool]: return self._tools.get(name) def get_all_tools(self) -> List[AgentTool]: return list(self._tools.values()) def get_openai_tools_schema(self) -> List[Dict[str, Any]]: """获取所有已注册工具的 OpenAI Function Calling 定义列表""" return [tool.openai_schema for tool in self._tools.values()] async def execute( self, name: str, arguments: Dict[str, Any], context: Optional[Dict[str, Any]] = None, ) -> Any: tool = self.get_tool(name) if not tool: return {"error": f"Tool '{name}' not found in registry"} return await tool.execute(arguments, context=context) # 全局默认单例注册中心 tool_registry = ToolRegistry() agent_tool = tool_registry.register