Agent 工具怎么设计和注册？Tool Schema、Registry 与执行器如何解耦

面试官可能会问：“给 Agent 新增一个搜索工具，你会改哪些地方？工具越来越多以后，怎么注册、禁用、鉴权和排查？”

如果回答是“写一个函数，再把它放进 tools 数组”，只能说明会做最小 Demo。真实工具系统至少面对两类消费者：模型需要一份容易理解的工具说明，后端需要一个可执行、可鉴权、可观测的服务入口。这两者有关联，却不能混为一体。

Tool Schema 解决“模型怎样知道工具能做什么、参数怎么填”；Tool Registry 解决“程序怎样找到真实执行器，并读取权限、超时、副作用和版本等元数据”；工具网关解决“真正调用时怎样统一校验、限流、日志和容错”。把三层拆开，新增工具才不需要修改 Agent 主循环，敏感工具也不会因为出现在 Prompt 里就被任何用户调用。

先给出 30 秒回答

我会把 Agent 工具拆成三部分：给模型看的 Tool Schema、给程序用的 Tool Registry、真正执行的后端适配器。Schema 包含稳定名称、明确描述、参数约束和返回语义，帮助模型选工具和填参数；Registry 把工具名映射到执行器，并保存版本、权限等级、是否有副作用、超时、重试、租户范围和可用状态；运行时网关根据当前用户和任务只暴露允许的 Schema，收到 tool call 后再做名称、参数、权限和业务校验，最后执行并返回统一 Observation。这样工具可以独立上线、灰度、禁用和审计，Agent loop 只依赖抽象工具协议。

装饰器只是注册入口。真正需要讲清的是模型说明、运行元数据和真实执行如何相互解耦。

放大查看图解 ↗

模型只需要看说明书，后端必须掌握执行权和安全元数据。

一个工具到底由哪些部分组成

最小教程通常说，一个工具由名字、描述和参数组成。这是从模型视角看。进入工程实现后，还要增加返回契约、执行器和运行策略。

稳定名称

名称用于模型选择，也用于后端分发。它应该短、可理解、可版本管理，例如 search_web、visit_page、query_order。不要让同一工具在不同地方出现多个别名，也不要频繁重命名。名称变化会影响 Prompt、评估集、日志查询和历史 Trace。