工具使用：让 Agent 安全地接触世界

工具把文本系统变成行动系统

没有工具时，模型只能基于输入生成内容。有了工具，Agent 可以检索动态信息、执行代码、调用业务系统或改变外部世界。能力变大，责任也随之变大。

官方课程把工具模式的构件归纳为：

• 工具 schema 或契约；
• 决定何时调用的执行逻辑；
• 管理用户、模型、工具消息的系统；
• 连接真实能力的集成层；
• 错误处理与输入验证；
• 维护多轮一致性的状态。

本课不调用任何外部 API，而是用本地课程索引模拟整个生命周期。

一个好工具先是好接口

search_lessons 的契约可以写成：

名称：search_lessons
用途：在允许的课程索引中按关键词查找条目
输入：query，非空字符串
输出：lessonId、title、path 的列表
失败：INVALID_QUERY 或空列表
权限：只读课程索引

工具不负责“回答用户”。它只完成一个窄任务。这样做有四个好处：

1. 输入可以在执行前验证；
2. 输出可以独立测试；
3. 权限容易理解；
4. 失败不会和自然语言答案混在一起。

如果工具同时搜索、总结、发送邮件并修改记录，它很难被安全授权，也很难定位哪一步出错。

五阶段 Trace

1. 目标

“找出工具使用课，并给一个十分钟练习。”完成需要课程证据和练习。

2. 决策

当前状态里没有相关课程路径。Agent 查看允许工具，发现课程索引搜索是最小且足够的动作。

3. 调用

执行层验证 query，调用工具并记录结构化输入。模型提出调用不等于工具一定会执行；权限与校验位于两者之间。

4. 观察

工具返回 04 的标题与路径。观察被写回状态，同时保留空结果、错误与耗时。

5. 停止

课程已定位，练习可以根据工具契约生成。继续调用不会增加必要证据，因此停止。

这五步必须可回放。Trace 展示系统事件和决策依据，不依赖“模型说自己做过什么”。

错误是正常分支

至少处理三类结果：

• 输入无效：执行前拒绝，告诉决策层怎样修正；
• 合法但无命中：返回空结果，允许改写查询；
• 工具失败：保留错误类型，按策略重试、降级或请求人工输入。

绝不能把失败字符串当作成功内容，也不能因为无结果就编造一个课程路径。

工具治理取决于外部效果

课程搜索是只读、可重复、低影响动作，可以自动执行。发送邮件会对外沟通，转账会改变资产，删除会破坏数据。影响越高，越需要：

• 更窄的权限；
• 更严格的输入与目标校验；
• 明确预览；
• 人工确认；
• 幂等或撤回设计；
• 可审计记录。

工具数量不是 Agent 能力的分数。只授予完成当前目标所需的最小集合。

本课完成定义

你应能从零写出一个工具契约；阅读五阶段 Trace；解释为什么某个调用合法或越权；并让 Course Helper 使用两个本地只读工具完成任务。

本课依据锁定版本的工具使用设计模式重构。