AI Agent Troubleshooting Playbook：构建可靠AI Agent的必备实践
Agent 出错时最怕漫无目的地试。这篇给出一套排障顺序：先定位在哪一层、固定复现、二分缩小范围、看完整 trace，附常见故障速查表和上线前的回归样例集。
💡 你将学到
Agent 出错时最怕漫无目的地试。这篇给出一套排障顺序：先定位在哪一层、固定复现、二分缩小范围、看完整 trace，附常见故障速查表和上线前的回归样例集。
AI Agent排障手册：定位、复现、二分与回归的完整流程
排障不是试错，是有顺序的缩小范围
Agent 的故障有个特点：同一个输入今天对、明天错。因为背后有模型采样、检索结果、外部接口这三重不确定性。很多人一上来就改提示词，改三个小时发现是上游接口返回了空数据。
这套手册给的是顺序：先确定故障在哪一层，再让它能稳定复现，再二分缩小范围，最后看完整链路。顺序对了，多数问题半小时内能定位。
第一步：判断故障在哪一层
| 症状 | 最可能的层 | 先查什么 |
|---|---|---|
| 答非所问、胡编工具名 | 提示/模型层 | 实际发送的完整提示词与模型版本 |
| 该调工具却没调 | 提示/工具声明层 | 工具描述、参数 schema、是否触发截断 |
| 工具调了但参数错 | 模型层 | 参数在 prompt 里的示例是否充分 |
| 工具报错 | 工具/依赖层 | 工具自身日志、鉴权、超时 |
| 检索到了却没用 | 上下文组装层 | 提示里检索内容是否被截断、排序是否合理 |
| 结果对但格式错 | 输出解析层 | 模型原始返回 vs 解析后的对象 |
| 随机失败、无规律 | 基础设施层 | 限流、超时、并发、重试 |
这张表的价值在于：先定层，再动手。定错层，改提示词改到天亮也没用。
第二步：让它能稳定复现
不能复现的 bug 只能靠猜。复现要固定三样东西：
- 输入：完整的用户输入，包括历史对话和检索到的文档
- 配置：模型版本、温度、系统提示词的哈希值、工具清单
- 外部状态：是否是同一份数据、同一时间的接口返回
做法是打开完整 trace：把每一轮的消息、工具调用参数、工具返回值、最终输出原样记录到日志或可观测平台（例如 Langfuse、OpenTelemetry）。有 trace 之后，"它为什么这么答"通常一眼就看得见。
第三步：二分缩小范围
五个开关，一次改一个：
| 动作 | 目的 |
|---|---|
| 关掉所有工具 | 判断是模型自身答错，还是工具带来的信息错 |
| 换一个更强的模型 | 判断是能力不足还是提示写法问题 |
| 温度设为 0 | 排除采样随机性 |
| 只用最小提示词 | 排除系统提示里的干扰 |
| 固定检索结果（写死上下文） | 判断是不是检索环节的锅 |
能复现之后，通常两轮二分就能定位到具体环节。
第四步：常见故障速查
| 现象 | 常见根因 | 处理 |
|---|---|---|
| 调用不存在的工具 | 工具描述太相似或名称被截断 | 精简工具数量、区分描述 |
| 反复调用同一个工具 | 缺循环上限 | 设最大步数并检测重复调用 |
| JSON 解析失败 | 输出混了解释文字 | 开 JSON 模式、剥代码块围栏 |
| 上下文溢出 | 历史对话无限增长 | 摘要压缩、截断早期轮次 |
| 401/403 | 密钥过期或权限变更 | 检查密钥有效期与作用域 |
| 429 | 未限流或并发过高 | 见限流策略 |
| 超时 | 未设超时或外部接口慢 | 设单步超时、降级返回部分结果 |
| 结果时好时坏 | 检索质量问题 | 固定数据集做评估，记录命中率 |
第五步：修完要防复发
每次修好一个问题，把当时的输入存成一个回归用例。积累到二三十条之后，每次改提示词、换模型、加工具都跑一遍。这套小样例集是 Agent 项目里性价比最高的投入——它能提前发现"修 A 坏 B"。
建议给用例打标签（工具调用、格式、安全、检索），失败时能直接看出是哪一类能力退化了。
排障时要避免的做法
- 一次改多处，改完变好也不知道是哪一处起作用
- 只看最终输出，不看中间的工具调用记录
- 用"再试一次就好了"结案，不记录根因
- 生产环境直接调提示词，没有版本管理
- 用大量线上请求做测试，影响真实用户和额度
常见问题
Q：线上出问题但本地复现不了，怎么办？ A：先对齐环境变量：模型版本、温度、系统提示词哈希、检索索引版本。多数"只在线上错"是这四项里有一项不同。再不行就把线上的原始 trace 拉下来重放。
Q：怎么判断是模型能力不够还是提示没写好？ A：用同一个输入换更强的模型跑一次。明显变好说明是能力边界，差不多说明是提示或数据问题。
Q：Agent 偶发不调用工具，怎么修？ A：先看工具数量和描述是否重叠，再确认系统提示里是否明确写了"什么情况下必须调用工具"。经验上，工具超过十几个之后漏调概率会上升，考虑按场景分组。
Q：什么时候该放弃提示工程，改成代码约束？ A：同一类错误修三次还在复发，就该用代码兜底——格式用 schema 校验，关键动作加前置条件检查，而不是继续在提示词里加感叹号。
相关文章
本站文章由编辑人工撰写，收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库，仅作信息参考，不构成付费推广。
