Agent 靠工具调用tool calling读写文件、跑命令、查接口。失败时控制台往往只丢一句「tool error」排障却可能停在错误层。本系列叫「Agent 工程笔记」。第一篇只建立排查顺序先分清失败发生在哪一层再决定改提示、改 schema还是改环境。一、先说一个具体麻烦你让 Agent「更新依赖并跑测试」。它调了终端工具返回非零退出码。你以为是模型笨把提示加长三倍还是失败。后来发现命令在沙箱里根本没有pnpm。问题在执行环境不在「想不想得清楚」。工具失败常见混在一起。分层以后动作才对得上病。二、三层分别是什么第一层模型决策模型有没有选对工具参数意图对不对该不该在缺信息时先搜索再写症状调错工具、漏调、乱调、该停不停。第二层协议与参数工具名、JSON 参数、必填字段、类型是否符合 schemaMCP / API 是否校验失败症状参数缺失、类型错误、未知工具名、解析失败。第三层执行环境权限、网络、路径、依赖、超时、沙箱策略、密钥是否可用症状命令找不到、权限拒绝、连不上、超时、磁盘只读。三、推荐排查顺序A先看原始工具结果退出码、stderr、HTTP 状态不要只看模型转述B确认工具名与参数是否合法第二层C在同一环境手动复现命令第三层D若环境与参数都对再回头看提示与决策第一层很多人颠倒先改人格化提示却不复现命令。四、每层最小修复动作第一层补约束与验收减少工具数量要求「先只读探测」。第二层收紧 JSON Schema给枚举对失败返回可机读错误码。第三层装依赖、开放路径、延长超时、提供只读凭据、修好沙箱。下面是一个更利于第二层排查的工具错误返回示意。{ok:false,code:ENOENT,tool:run_terminal,message:pnpm: command not found}上面代码中code与message让宿主和模型都能定位到环境层而不是笼统的「失败了」。五、和 MCP / 约束验收的关系MCP 把工具接到宿主接上不等于稳。Server 挂了、schema 漂移、权限过宽都会在二三层爆雷。「约束 验收」主要稳住第一层少让模型在模糊目标下乱点工具。三层要一起看。六、常见误区1只骂模型多数是环境与契约。2吞掉 stderr等于丢掉第三层证据。3工具说明过长却缺必填示例第二层更容易出错。4一次给二十个高危工具第一层选错概率上升。七、小结与下一篇工具失败先问决策错了、参数错了还是环境执行错了按层动手比反复加形容词有效。下一篇预告上下文太长时砍什么、留什么。完