Agent 工程笔记①：工具调用失败时，先查哪三层

Agent 靠工具调用（tool calling）读写文件、跑命令、查接口。失败时，控制台往往只丢一句「tool error」，排障却可能停在错误层。

本系列叫「Agent 工程笔记」。第一篇只建立排查顺序：先分清失败发生在哪一层，再决定改提示、改 schema，还是改环境。

你让 Agent「更新依赖并跑测试」。它调了终端工具，返回非零退出码。你以为是模型笨，把提示加长三倍，还是失败。

后来发现：命令在沙箱里根本没有 pnpm。问题在执行环境，不在「想不想得清楚」。

工具失败常见混在一起。分层以后，动作才对得上病。

模型有没有选对工具？参数意图对不对？该不该在缺信息时先搜索再写？

症状：调错工具、漏调、乱调、该停不停。

工具名、JSON 参数、必填字段、类型是否符合 schema？MCP / API 是否校验失败？

症状：参数缺失、类型错误、未知工具名、解析失败。

权限、网络、路径、依赖、超时、沙箱策略、密钥是否可用？

症状：命令找不到、权限拒绝、连不上、超时、磁盘只读。

（A）先看原始工具结果：退出码、stderr、HTTP 状态，不要只看模型转述

（B）确认工具名与参数是否合法（第二层）

（C）在同一环境手动复现命令（第三层）

（D）若环境与参数都对，再回头看提示与决策（第一层）

很多人颠倒：先改人格化提示，却不复现命令。

第一层：补约束与验收；减少工具数量；要求「先只读探测」。

第二层：收紧 JSON Schema；给枚举；对失败返回可机读错误码。

第三层：装依赖、开放路径、延长超时、提供只读凭据、修好沙箱。

下面是一个更利于第二层排查的工具错误返回示意。

json 复制代码

{
  "ok": false,
  "code": "ENOENT",
  "tool": "run_terminal",
  "message": "pnpm: command not found"
}

上面代码中，code 与 message 让宿主和模型都能定位到环境层，而不是笼统的「失败了」。

MCP 把工具接到宿主；接上不等于稳。Server 挂了、schema 漂移、权限过宽，都会在二三层爆雷。

「约束 + 验收」主要稳住第一层：少让模型在模糊目标下乱点工具。三层要一起看。

（1）只骂模型

多数是环境与契约。

（2）吞掉 stderr

等于丢掉第三层证据。

（3）工具说明过长却缺必填示例

第二层更容易出错。

（4）一次给二十个高危工具

第一层选错概率上升。

工具失败，先问：决策错了、参数错了，还是环境执行错了？按层动手，比反复加形容词有效。

下一篇预告：上下文太长时，砍什么、留什么。

（完）