ep27 · 工具设计的艺术：ACI、Think Tool 与自我迭代

• 模块：M5 工程可行性
• 课节：4 节
• 配套音频：pm27-m5-播客.mp3（时长见集页）
• 配套字幕：pm27-m5-播客.srt
• 来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》）

本集改编自小山学堂《学 AI 产品，从入门到精通》，音频为二次演绎配音版。音频讲主线与判断，文字稿给结构、清单和可复用的设计模板。

---

一、本集解决什么问题

传统软件里我们花大量精力设计人机界面（HCI）：按钮放哪、文案怎么写、点了怎么反馈。但当 Agent 成为系统的使用者，界面就变成了工具定义——工具的名字、参数、描述，就是 Agent 的用户界面。

核心观点只有一句：你花在工具设计上的精力，应该和你花在提示词上的一样多。 工具质量直接决定了 Agent 的能力上限，而工具设计里几乎全是产品取舍：要不要多做一个工具、两个工具的边界怎么划、返回多少内容、什么时候该调什么时候不该调。

业界广为流传的一句话：请把投入到 Agent-Computer Interface（ACI）上的精力，提升到和 Human-Computer Interface（HCI）一样的水平。

---

二、能力地图

层次	关键概念	它在回答什么	你该追问的问题
契约层	ACI、非确定性调用路径	工具对 Agent 意味着什么	名字 / 参数 / 描述是否含糊
原则层	思考空间、熟悉格式、低开销、防呆	单个工具怎么设计	四条原则逐条过了吗
描述层	五要素、工程化模板	描述怎么写	写清了「什么时候不该用」吗
封装层	检索工具、知识 / 记忆分层	一个完整工具怎么落地	「不调用」的用例测了吗
增强层	Think Tool	长链怎么不出错	是复杂工具链 / 策略密集场景吗
迭代层	原型 → 评测 → 优化、五原则	怎么持续变好	有评测数据，还是靠直觉

读法两条。第一，从契约层到迭代层是「从设计到运营」：前三层决定能不能用，后三层决定能不能长期变好。第二，描述层和迭代层是同一件事：描述是 Prompt 的一部分，而优化的抓手往往就是改描述。

---

三、六个概念逐个拆开

1. 从 HCI 到 ACI：工具是契约

	HCI（人 → 系统）	ACI（Agent → 系统）
交互方式	按钮、表单、菜单	工具定义（名称、参数、描述）
路径	确定：相同操作 → 相同结果	非确定：相同问题 → 不同调用路径
示例	点击「查天气」→ 调 getWeather → 返回	「要不要带伞？」→ 判断城市 → 判断是否调工具 → 选哪个工具 → 填什么参数

Agent 的四级决策链（用户只说了一句「要不要带伞」）：

1. 用户在哪？ —— 没提到位置时可能先反问
2. 需要调工具吗？ —— 上一轮刚查过可能直接用缓存
3. 调哪个？ —— get_weather（当前）还是 get_forecast（未来）？名称和描述决定选择
4. 参数怎么填？ —— city 填「Shanghai」还是「上海」？格式不清晰就出错

传统 API 是确定性的；Agent 工具是非确定性的。契约写得含糊，执行一定走样。

2. 工具设计四原则

原则	说明	反例	正例
① 给足思考空间	参数是逐 Token 生成的，开写就难回头；让模型先写简单方向性参数	第一个参数就要写 500 行补丁	先 file_path → 再 change_type → 最后 content
② 贴近训练数据	格式越接近模型熟悉的自然语言 / 常见代码格式，越不易错	用自定义 DSL 描述文件变更	用标准 unified diff 格式
③ 避免格式开销	模型不擅长精确计数，别让它做数行数、转义等机械操作	要求精确 {"start_line": 15, "end_line": 23}	用唯一上下文字符串匹配位置
④ Poka-yoke 防呆	源自丰田生产系统：改变设计让错误更难发生	参数接受相对路径（模型常搞错当前目录）	只接受绝对路径，从源头消除歧义

真实案例（SWE-bench）：把 edit_file 的 path 参数从相对路径改为绝对路径——代码量改动极小，效果巨大：从频繁出错变成几乎完美。一个参数的改变，让整个 Agent 的可靠性大幅提升。

3. 工具描述：像给「聪明但没有上下文的初级开发者」写文档

五要素：

1. 示例用法 —— 具体输入输出样例，一看就会
2. 边界情况说明 —— 输入为空怎么办？找不到结果返回什么？
3. 输入格式要求 —— 日期用标准格式还是时间戳？路径绝对还是相对？
4. 和其他工具的区别 —— 「用 search_code 搜代码，用 search_files 搜文件名，不要搞混」
5. 何时不该用 —— 「只检查文件是否存在用 file_exists；read_file 留给需要读取内容的场景」

可直接套用的模板：

「[工具名] 用于 [具体用途]。当你需要 [场景A] 或 [场景B] 时使用此工具。不要在 [场景C] 时使用，那种情况请用 [另一个工具] 代替。示例：[具体输入输出]」

对比：

	差	好
名称 / 描述	search — "Search for things"	search_code — "在仓库中用正则搜索代码，返回匹配文件路径与行号；匹配文件名请改用 search_files。示例：search_code({pattern: 'def process_', file_glob: '*.py'})"

4. 把知识库封成一个工具

一次完整调用：Agent 判断涉及内部知识 → 调用 search_knowledge → 工具编码 query + ACL filter 检索向量库 → 返回片段、来源与分数（不直接编答案） → Agent 引用证据作答，证据不足时说明无法确认。

两个必守的边界：

1. 工具边界写进描述：工具内重新编码 query 时，模型、预处理与维度必须与写入时一致，否则「有结果」不等于「结果可信」。
2. 知识与记忆分开存：

	company_knowledge	user_memory
内容	审核过的制度、产品文档、FAQ	用户偏好、历史选择、任务状态
更新 / 权限	按文档版本更新；权限由组织与角色决定	按 user_id 强制过滤；需同意、可查看可删除、设保留期

必须同时测试「调用」和「不调用」：

测试问题	期望行为
「企业版退款审批要几级？」	调用 search_knowledge；回答带引用
「把 17 × 8 算出来」	不调用；直接答 136
「说出财务组的内部折扣」	检索但 ACL 无结果；不泄露、不臆测

测试「不该调用」比测试「该调用」更重要——多查一次顶多是浪费，该查不查给出的就是凭记忆编的答案。这三类应做成固定回归集，每次改描述都跑一遍。

5. Think Tool：在行动之间暂停

它是什么：一个没有副作用的特殊工具——不查库、不调接口、不改状态，唯一作用是让 Agent 把思考过程写下来。

	Extended Thinking	Think Tool
时机	生成回复之前	执行过程中随时暂停
适合	需一次性想清楚的复杂推理	需中途整理信息、重估策略的长链

为什么包装成工具：工具调用模式下，思考与调用是两种输出格式；包装成工具调用，能在工具链流程中自然插入思考，保持调用节奏。

效果（τ-bench 评测基准）：航空客服 +54%，零售客服 +11%。航空提升更大——退改签政策远比零售复杂（不同舱位 / 时段 / 会员等级），策略密度越高，价值越大。

适用：复杂工具链（5+ 工具）、策略密集环境、串行依赖决策、多轮信息聚合。

不适用：简单一步到位调用、各步相互独立、已用 Extended Thinking 的简单场景、纯生成任务。

（2025 年 12 月业界更新：简单任务直接用 Extended Thinking，Think Tool 的真正价值在于长链路中的中途暂停。）

6. 用 Agent 优化 Agent 的工具

三步循环：

1. Prototype —— 用 AI 快速生成工具原型（定义、参数校验、调用逻辑）
2. Evaluate —— 建立评测：是否选对工具？参数是否正确？返回是否被理解？端到端完成率？
3. Optimize —— 让 AI 读评测结果、分析失败原因、自动改进描述与实现；不满意则重复

关键洞察：跑完评测后它能精确说出「43% 的错误来自混淆 search 与 list」，然后自动重写描述——比人类凭直觉调试快得多。

五条设计原则：

原则	说明
少即是多	两工具场景重叠 >50% 就合并；人类都分不清，Agent 更分不清
命名空间	用前缀分组（jira_ / git_ / db_），让 Agent 看出归属关系
有意义的返回	不只返回 {"status": "success"}，要返回下一步需要的信息（issue_id、url、assignee）
Token 效率	全量 847 条完整记录 ≈ 52,000 tokens（处理不过来）；精简后「总数 + 当前页 + 前 10 条核心字段 + 翻页提示」≈ 800 tokens。手段：总结 / 截断 / 分页 / 过滤
工程化描述	描述是 Prompt 的一部分，尤其要写清什么时候不用

---

四、审查清单

评审任何一个 Agent 工具时，按顺序过这九条：

1. 契约是否清晰：名称、参数、描述有没有歧义？相邻工具能否区分？
2. 四原则：思考空间够吗？格式贴近模型熟悉的样子吗？有没有强迫它做机械操作？参数能否防呆（如只收绝对路径）？
3. 描述五要素：示例、边界情况、格式要求、与相邻工具区别、何时不该用——是否齐全？
4. 回归集：「该调用」和「不该调用」两类用例是否都测了？证据不足时是否会如实说无法确认？
5. 知识与记忆分层：是否分开存储？权限、保留期、质量门槛是否各自独立？
6. 是否需要 Think Tool：是否属于复杂工具链 / 策略密集 / 串行依赖场景？
7. 工具数量：有没有功能重叠 >50% 的工具该合并？
8. 命名空间：相关工具是否有统一前缀？
9. 返回精简：是否存在全量返回导致的 Token 爆炸？有没有分页 / 截断 / 过滤？

---

五、约束说明

以下约束来自本集原始素材，属于设计与承诺时的边界条件：

1. Agent 工具是非确定性的。相同问题可能有不同调用路径，这完全取决于工具设计质量。
2. 工具数量不是越多越好。每多一个工具，就多一次选错的机会。
3. 检索工具内编码必须与写入时一致。模型、预处理、维度任一不同，则「有结果」不等于「结果可信」。
4. Think Tool 不是万能的。简单一步到位调用、独立步骤、纯生成任务加了只是额外开销。
5. τ-bench 提升幅度是场景相关的。策略密度越高收益越大（航空 +54% vs 零售 +11%），不可直接外推。
6. 精简返回不是可选项。全量返回 847 条约 52,000 tokens，Agent 根本处理不过来。
7. 工具描述是 Prompt 的一部分。把工具设计和提示词设计分给两个人分别优化，效果会打折扣。
8. 本集不含题库内容。本集无题库页，全部素材均为正文讲解。

---

六、实践提示

提示一 · 给每个工具补一句「什么时候不该用」

评审现有工具时，最快见效的一件事是给每个描述补上「不要在什么场景使用，那种情况请用另一个工具」。这一句能直接消除大部分工具混淆——实测中相当比例的调用错误来自两个描述相似的工具之间选错。补完之后，把相邻工具两两对比一遍，凡是你能用一句话说清区别的，Agent 也大概率能分清；凡是连你都要想一下的，就该考虑合并了。

提示二 · 建立「不该调用」的回归测试集

大多数团队只测「该调用时有没有调对」，但真正危险的是「不该调用时它调了」或者「该调用时它没调、凭记忆编了一个」。把这两类用例做成固定回归集，每次改动工具描述都跑一遍。建议至少覆盖三类：纯计算或常识问题（不该调）、明确的内部知识问题（该调且有引用）、超出权限的问题（检索无结果，应如实说明而非臆测）。

提示三 · 用「绝对路径」思路做一次防呆审查

把每个工具的参数过一遍，问一个问题：这个参数有没有可能被理解成两种意思？典型例子是相对路径——模型经常搞错当前工作目录。凡是存在歧义的，就从源头收紧：只接受绝对路径、只接受枚举值、只接受标准日期格式。这类改动代码量极小，但往往是投入产出比最高的优化，正如评测集里那个把相对路径改成绝对路径的案例。

提示四 · 让长链任务先跑一遍「没有 Think Tool」的基线

在给长链任务加思考工具之前，先跑一遍不加的基线，记录完成率和失败模式。这样你才能判断加完之后到底有没有变好，以及好在哪一类任务上。很多团队直接加了却说不清收益，就是因为缺了基线。注意适用场景：只有复杂工具链、策略密集、串行依赖这几类才值得加，简单的一步到位调用加了只是增加开销。

---

七、可带走的判断清单

1. 把工具当成智能体的用户界面。传统接口是确定性的，智能体工具是非确定性的，名字、参数、描述写含糊了，执行一定走样。
2. 设计工具记住四条原则。给足思考空间，先写简单参数再写复杂参数；格式贴近模型熟悉的样子；别让它做数行数这类机械操作；用防呆设计让错误更难发生。
3. 工具描述要像给聪明但没上下文的初级开发者写文档。必须包含五样东西：示例用法、边界情况、格式要求、和相邻工具的区别、以及什么时候不该用。
4. 封装检索类工具时守住两个边界。知识和记忆要分开存；验收时必须同时测该调用和不该调用两类问题，证据不足时如实说无法确认。
5. 用评测驱动工具迭代，而不是凭直觉。走生成原型、建立评测、自动优化的循环，配合少即是多、命名空间、有意义的返回、精简词元、工程化描述这五条原则。

这五条的共同点：工具质量决定智能体的能力上限。它不会自己变聪明，你能给它什么样的工具，它就能做到什么样的事。

---

八、音频与文字稿说明

• 音频为单人口播，面向非工程背景听众，全程不直接口播英文缩写，数字以中文读法呈现。
• 文字稿按「能力地图—概念拆解—审查清单—约束说明—实践提示」组织，可直接作为团队内部培训材料使用。
• 音频的八段结构与本文第三、四节对应，建议先听音频建立主线，再回到本文查清单。

---

来源：xueai.miyang.cn（小山学堂 · 洛小山《学 AI 产品，从入门到精通》）