[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Runtime, Tool Executor, Function Schema

Tool Registry

一句话定义

Tool Registry 是 AI Service 中管理工具定义的中心化注册模块。所有工具在这里注册，Agent 运行时从这里获取工具列表和 Schema。

核心原理

Python 实现

class Tool:
    def __init__(self, name, description, parameters, handler, **kwargs):
        self.name = name
        self.description = description
        self.parameters = parameters  # JSON Schema
        self.handler = handler
        self.risk_level = kwargs.get("risk_level", "low")
        self.requires_approval = kwargs.get("requires_approval", False)
        self.read_only = kwargs.get("read_only", True)
        self.timeout = kwargs.get("timeout", 30)

    def to_schema(self) -> dict:
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": self.parameters,
            }
        }

class ToolRegistry:
    def __init__(self):
        self._tools: dict[str, Tool] = {}

    def register(self, tool: Tool):
        self._tools[tool.name] = tool

    def get(self, name: str) -> Tool:
        return self._tools.get(name)

    def get_schemas(self, filter_func=None) -> list[dict]:
        tools = self._tools.values()
        if filter_func:
            tools = [t for t in tools if filter_func(t)]
        return [t.to_schema() for t in tools]

    def list_tools(self) -> list[str]:
        return list(self._tools.keys())

使用

registry = ToolRegistry()

# 注册工具
registry.register(Tool(
    name="search_knowledge",
    description="搜索知识库",
    parameters={
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
    handler=search_handler,
    risk_level="low",
    read_only=True,
))

# 获取 Schema 给 LLM
schemas = registry.get_schemas()

常见坑

1. 工具名冲突: 两个模块注册了同名工具
2. Schema 和 handler 不一致: Schema 定义了参数但 handler 不接受
3. 不做动态加载: 所有工具都注册，但不是所有场景都需要

参考资料

• Tool Calling 工程化
• Function Schema