registry.py 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. # app/services/agent/tools/registry.py
  2. import inspect
  3. import functools
  4. from typing import Callable, Dict, Any, List, Optional, get_type_hints, get_origin, get_args
  5. from app.core.logger import logger
  6. # 上下文保留关键字,这些参数不向 LLM 暴露,而在执行时由框架自动注入
  7. CONTEXT_PARAM_NAMES = {"db", "current_user", "redis_client", "context"}
  8. def python_type_to_json_type(py_type: Any) -> str:
  9. """将 Python 类型转换为 JSON Schema 类型"""
  10. origin = get_origin(py_type)
  11. if origin is not None:
  12. if origin in (list, List):
  13. return "array"
  14. if origin in (dict, Dict):
  15. return "object"
  16. # 处理 Optional[T] / Union[T, None]
  17. args = get_args(py_type)
  18. non_none_args = [a for a in args if a is not type(None)]
  19. if non_none_args:
  20. return python_type_to_json_type(non_none_args[0])
  21. if py_type in (int,):
  22. return "integer"
  23. if py_type in (float,):
  24. return "number"
  25. if py_type in (bool,):
  26. return "boolean"
  27. if py_type in (dict, Dict):
  28. return "object"
  29. if py_type in (list, List):
  30. return "array"
  31. return "string"
  32. class AgentTool:
  33. """Agent 工具包装类"""
  34. def __init__(
  35. self,
  36. name: str,
  37. description: str,
  38. func: Callable,
  39. is_dangerous: bool = False,
  40. ):
  41. self.name = name
  42. self.description = description.strip()
  43. self.func = func
  44. self.is_dangerous = is_dangerous
  45. self.is_async = inspect.iscoroutinefunction(func)
  46. self.signature = inspect.signature(func)
  47. self.type_hints = get_type_hints(func) if hasattr(func, "__annotations__") else {}
  48. self.openai_schema = self._build_openai_schema()
  49. def _build_openai_schema(self) -> Dict[str, Any]:
  50. """根据函数签名自动推导 OpenAI Tool Function Schema"""
  51. properties = {}
  52. required = []
  53. for param_name, param in self.signature.parameters.items():
  54. if param_name in CONTEXT_PARAM_NAMES:
  55. continue
  56. param_type = self.type_hints.get(param_name, str)
  57. json_type = python_type_to_json_type(param_type)
  58. param_desc = f"Parameter {param_name}"
  59. # 尝试从 docstring 中提取简单描述(如果存在)
  60. properties[param_name] = {
  61. "type": json_type,
  62. "description": param_desc,
  63. }
  64. # 判断是否必选
  65. if param.default is inspect.Parameter.empty:
  66. # 没有默认值,且不是 Optional
  67. origin = get_origin(param_type)
  68. args = get_args(param_type)
  69. is_optional = origin is not None and type(None) in args
  70. if not is_optional:
  71. required.append(param_name)
  72. return {
  73. "type": "function",
  74. "function": {
  75. "name": self.name,
  76. "description": self.description,
  77. "parameters": {
  78. "type": "object",
  79. "properties": properties,
  80. "required": required,
  81. },
  82. },
  83. }
  84. async def execute(self, arguments: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> Any:
  85. """执行该工具,并根据需要注入上下文(如 db, current_user)"""
  86. context = context or {}
  87. call_kwargs = {}
  88. for param_name, param in self.signature.parameters.items():
  89. if param_name in CONTEXT_PARAM_NAMES:
  90. if param_name in context:
  91. call_kwargs[param_name] = context[param_name]
  92. elif "context" in context and param_name in context["context"]:
  93. call_kwargs[param_name] = context["context"][param_name]
  94. elif param_name in arguments:
  95. call_kwargs[param_name] = arguments[param_name]
  96. elif param.default is not inspect.Parameter.empty:
  97. call_kwargs[param_name] = param.default
  98. try:
  99. if self.is_async:
  100. result = await self.func(**call_kwargs)
  101. else:
  102. result = self.func(**call_kwargs)
  103. return result
  104. except Exception as e:
  105. logger.error(f"[AgentTool:{self.name}] execution error: {e}", exc_info=True)
  106. return {"error": str(e)}
  107. class ToolRegistry:
  108. """全局工具注册中心"""
  109. def __init__(self):
  110. self._tools: Dict[str, AgentTool] = {}
  111. def register(
  112. self,
  113. name: Optional[str] = None,
  114. description: Optional[str] = None,
  115. is_dangerous: bool = False,
  116. ):
  117. """装饰器:注册函数为 Agent 工具"""
  118. def decorator(func: Callable):
  119. tool_name = name or func.__name__
  120. tool_desc = description or (func.__doc__ or f"Tool {tool_name}").strip()
  121. tool = AgentTool(
  122. name=tool_name,
  123. description=tool_desc,
  124. func=func,
  125. is_dangerous=is_dangerous,
  126. )
  127. self._tools[tool_name] = tool
  128. return func
  129. return decorator
  130. def get_tool(self, name: str) -> Optional[AgentTool]:
  131. return self._tools.get(name)
  132. def get_all_tools(self) -> List[AgentTool]:
  133. return list(self._tools.values())
  134. def get_openai_tools_schema(self) -> List[Dict[str, Any]]:
  135. """获取所有已注册工具的 OpenAI Function Calling 定义列表"""
  136. return [tool.openai_schema for tool in self._tools.values()]
  137. async def execute(
  138. self,
  139. name: str,
  140. arguments: Dict[str, Any],
  141. context: Optional[Dict[str, Any]] = None,
  142. ) -> Any:
  143. tool = self.get_tool(name)
  144. if not tool:
  145. return {"error": f"Tool '{name}' not found in registry"}
  146. return await tool.execute(arguments, context=context)
  147. # 全局默认单例注册中心
  148. tool_registry = ToolRegistry()
  149. agent_tool = tool_registry.register