22. 排错实战：一次任务为什么失败

不要先改 prompt

Agent 出问题时，很多人第一反应是改 prompt。

但失败原因往往不在 prompt。

先分层排查。

第一层：配置

确认：

config.yaml 是否被读取
provider 是否正确
api key 是否生效
base url 是否正确

模型没通时，后面所有排查都没有意义。

第二层：模型

看模型调用是否成功，返回是否被截断，是否超时。

如果模型不稳定，先换一个小任务验证，不要直接跑长报告。

第三层：工具

工具失败要看输入和输出。

常见问题：

参数格式错
工具返回太长
工具没有拿到正文
错误信息被吞掉

第四层：资料

研究型 Agent 最常见的问题是资料不够。

如果只拿到搜索摘要，没有原文，就不要让它写确定结论。

第五层：产物

如果任务要求生成文件，最后一定要验证：

文件是否存在
路径是否正确
内容是否完整
是否能被下载或展示

这一篇你要记住

排错顺序是：

配置 → 模型 → 工具 → 资料 → 子 Agent → 文件产物

按层排，比反复改 prompt 有用。

一个具体排查例子

假设研究报告质量很差。

不要先改 prompt，先问：

搜索有没有拿到相关来源？
抓取有没有拿到正文？
工具返回是否太长？
Skill 是否要求引用证据？
最终报告是否包含来源？

如果第一步资料就不可靠，后面再怎么改 prompt 都有限。

什么时候该停止

如果缺少原文、缺少工具日志、缺少 run 事件，就不要继续脑补原因。

先补观测，再修问题。

输出排查结论

排查结果最好写成：

现象
定位层级
证据
修复动作
验证结果

这样下次类似问题可以复用。