[!info] related notes

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

Tool Registry

一句话定义

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

核心原理

Python 实现

局部注册表示例（Python 3.10+），使用 function 风格 schema envelope；具体模型接口需另做适配。元数据由受信代码注册，不能让模型自报只读能力。

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", False)
        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):
        if tool.name in self._tools:
            raise ValueError(f"Duplicate tool: {tool.name}")
        self._tools[tool.name] = tool

    def get(self, name: str) -> Tool | None:
        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())

使用

search_handler 是应用提供的实现；此处只演示注册。导出 schema 或按用户过滤列表不替代执行时鉴权，handler 签名也需与统一适配器一致。

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. 把发现当授权：没展示给模型的工具也可能被直接请求，执行入口必须重新检查
4. 只读默认放行：未声明能力不能推定安全；示例默认非只读，实际能力仍要审核
5. 运行中任意修改定义：生产注册表应在启动时校验并冻结，或明确工具版本与更新策略

参考资料

• Tool Calling 工程化
• Function Schema