AI Agent 实战教程 12：如何设计稳定的工具系统
工具系统是 AI Agent 工程中最容易被低估的部分。很多人讨论 Agent 时，会把注意力放在模型能力、提示词技巧和工作流框架上，但真正让 Agent 能够完成任务的，是一组设计良好、边界清晰、可被安全调用的工具。
如果工具系统设计得不好，Agent 会出现很多问题：该查询的时候执行了写入，该传 ID 的地方传了标题，接口失败后不知道如何恢复，工具返回一大段日志导致模型无法判断结果。模型越强，这类问题越隐蔽，因为它可能用看似合理的语言掩盖底层执行错误。
工具系统的定位
工具系统是模型与外部世界之间的执行层。模型不应该直接访问数据库、文件系统或业务接口，而是通过工具间接访问。工具系统负责把外部能力包装成模型可理解、系统可控制的接口。
一个稳定的工具系统至少要回答几个问题：
- 这个工具能做什么？
- 什么时候应该使用？
- 需要哪些参数？
- 参数如何校验？
- 返回什么结构？
- 风险等级是什么？
- 是否需要用户确认？
- 失败时如何表达错误？
这些问题如果没有在工具层解决，就会被迫交给模型临场判断，而模型并不适合承担所有工程约束。
工具注册表
工具注册表是工具系统的入口。它记录所有可用工具，并为 Agent 提供当前场景下允许调用的工具集合。
一个工具注册项通常包含：
- name：工具名称；
- description：工具用途；
- parameters：参数 schema；
- execute：执行函数；
- riskLevel：风险等级；
- scopes：所需权限；
- outputSchema：返回结构；
- examples：调用示例。
有了注册表，系统可以按场景加载工具。例如内容管理 Agent 只加载 tag、article、tutorial、material 相关工具；代码 Agent 只加载文件、测试、构建相关工具。这样模型看到的工具更少，选择错误的概率也更低。
工具 schema 设计
工具 schema 不是简单的 TypeScript 类型，它是模型理解工具的说明书。schema 应该尽量具体，避免模糊表达。
例如创建文章工具不应该只写“创建文章”，而应该说明：title 是文章标题，short 是 URL 友好的唯一标识，content 是 Markdown 正文，tagIds 最多建议 3 个，draftId 必须存在或由 CLI 自动创建。
好的 schema 会让模型知道：什么是必填字段，什么字段可以省略，哪些参数有格式要求，哪些错误是常见错误。
参数校验
模型生成的参数必须校验。常见校验包括：
- ID 是否为数字；
- short 是否符合 URL 规则；
- URL 是否以 http 开头；
- 文件路径是否在允许目录内；
- tagIds 是否存在；
- 日期是否能解析；
- 数组长度是否超过限制。
校验失败时，工具应该返回结构化错误，而不是直接抛出一段堆栈。比如返回 errorType、field、message、suggestion。这样 Agent 才能根据错误修正参数或询问用户。
风险等级与确认
工具必须区分读操作和写操作。查询标签、读取文章、获取列表通常风险较低；创建文章、上传图片、修改配置是写操作；删除、发布、批量修改、发送消息属于高风险操作。
风险等级应该由系统强制执行，而不是只在提示词里提醒模型。比如 delete 工具必须要求确认，即使模型认为用户已经表达了意图，也要经过系统审批。
返回值结构
工具返回值应该为后续步骤服务。创建资源后，应该返回 id、short、url、status 等字段；查询列表应该返回 total 和 list；失败时应该返回明确错误类型。
如果工具只返回一句“创建成功”，Agent 后续就无法引用资源 ID。如果工具返回完整结构，Agent 可以继续绑定、验证或展示结果。
幂等性设计
Agent 经常需要重试，因此工具要考虑幂等性。创建标签前先查重，上传图片前判断是否已经是自有素材，创建文章前检查 short 是否存在。这样即使任务中断后重跑，也不会制造重复数据。
幂等性是长任务 Agent 的关键能力。没有幂等性，断点续跑和错误恢复都很难实现。
小结
稳定的工具系统不是把函数暴露给模型这么简单。它需要注册表、schema、参数校验、风险等级、结构化返回、幂等性和日志。工具层越清晰，Agent 的行为越可控，也越容易进入生产环境。