Agent 兜圈、幻觉或越权时，应该如何系统排障
内容摘要：Agent 故障往往跨模型、工具、编排三层。本章用统一的九段式结构（现象→影响→证据→原因→验证→缓解→根因→回归→预防）分析高频故障，并强调"没有 Trace 就无法定位"。 难度：高级 |前置知识：17 可观测性、16 测试
常见误区
Agent 出问题通常是模型不够强，先换模型、调 Prompt 或提高最大步数，就能快速修好。
先给结论
Agent 故障要依据 Trace 在模型、上下文、编排、工具和外部系统之间定位。正确流程是收集证据、建立假设、最小复现、修复根因并补回归测试，而不是凭最终答案猜原因。
带着这三个问题阅读：
- 兜圈、幻觉、参数错误、越权和重复副作用分别需要什么证据？
- 如何区分模型决策问题、工具实现问题与状态编排问题？
- 临时缓解、根因修复和预防措施为什么要分开记录？
排障总原则
前提：缺少 Trace、日志、工具结果或指标时，无法判断根因——请先补齐可观测性（17），不要靠猜。
故障一：Agent 兜圈 / 打满步数
- 现象：任务经常以
max_steps结束，反复调用同类工具。 - 影响范围：延迟高、成本高、完成率低。
- 已知证据：Trace 显示同一工具被多次调用、参数相似、无进展。
- 可能原因：工具结果没提供有效新信息；停止条件缺失；Prompt 未告知何时收尾；上下文被截断丢了进度。
- 验证步骤：用
ScriptedModel复现；检查工具返回是否可用；检查上下文是否超窗（05）。 - 临时缓解：降低
max_steps、加"无进展即停"判据。 - 根因修复：改进工具返回信息量、明确停止条件、上下文瘦身、必要时改规划模式（08）。
- 回归验证：把该 case 加入评测集，断言步数下降、完成率上升。
- 预防：监控"步数打满率"告警（17）。
故障二：幻觉 / 编造事实
- 现象：回答自信但错误，或引用不存在的来源。
- 影响范围：正确性、用户信任。
- 已知证据：回答无出处，或出处与内容不符。
- 可能原因：让模型凭记忆答需外部事实的问题；RAG 未命中或未强制引用；上下文噪声大。
- 验证步骤：检查是否走了 RAG；核对引用；关掉猜测让其"不知道就说不知道"。
- 临时缓解：强制引用、低置信转人工（13）。
- 根因修复：需事实就接工具/RAG（06/11）；提升召回与重排；忠实度评测（16）。
- 回归验证：忠实度指标 + 引用正确性回归。
- 预防：上线忠实度监控与抽检。
故障三：工具调用失败 / 参数错误
- 现象：工具报参数错误、超时或异常。
- 影响范围：任务中断、重试放大。
- 已知证据：Trace 中
validation_error/exec_error/timeout。 - 可能原因：Schema 不清晰、模型给了非法参数、下游不稳定。
- 验证步骤：查参数是否过校验；下游是否可用；错误是否可重试。
- 临时缓解：完善错误信息回传让模型纠正（06）；对可恢复错误退避重试（15）。
- 根因修复：收紧/澄清 Schema、加默认值、区分可/不可重试错误。
- 回归验证：对各失败路径写单测。
- 预防：监控工具成功率。
故障四：提示注入 / 越权
- 现象：Agent 执行了不该做的操作，或泄露系统提示/数据。
- 影响范围：安全事故，可能不可逆。
- 已知证据：Trace 显示高危工具被非预期触发；输入/检索内容含可疑指令。
- 可能原因：直接/间接注入；过度授权；无审批。
- 验证步骤：重放输入与检索内容，定位注入源；检查权限与审批是否生效。
- 临时缓解：收紧权限、关停相关工具、加审批。
- 根因修复：纵深防御——隔离 + 最小权限 + 校验 + 审批 + 输出过滤（14）。
- 回归验证：把攻击语料加入对抗测试集（16）。
- 预防：注入拦截监控告警；定期红队。
故障五：成本 / 延迟失控
- 现象：账单激增或 P95 延迟飙升。
- 影响范围：预算、SLA。
- 已知证据：Token 统计显示上下文过长或步数过多（17）。
- 可能原因：上下文未瘦身、全用大模型、无预算上限、反思/多 Agent 过度。
- 验证步骤：按 Trace 拆解成本大头。
- 临时缓解：加预算护栏、限
max_tokens。 - 根因修复：上下文工程、模型路由/降级、缓存（18）。
- 回归验证：成本/延迟指标回到阈值内且完成率不降。
- 预防：成本突增告警、单任务硬上限。
故障六：恢复后重复执行（重复副作用）
- 现象：崩溃/重试后出现重复工单、重复扣款。
- 影响范围：数据一致性、资金。
- 已知证据：同一逻辑操作产生多条记录。
- 可能原因：写操作无幂等键；恢复未跳过已完成步骤。
- 验证步骤：复查是否有幂等键、checkpoint 是否记录完成状态。
- 临时缓解：人工去重、暂停自动重试。
- 根因修复：幂等键 + 恢复跳过已完成步骤（15、09）。
- 回归验证：
test_run_once_dedup类测试 + 崩溃恢复演练。 - 预防：写操作强制幂等评审项（19 检查清单）。
快速定位对照表
| 现象 | 先看 | 大概率层 | 去哪章 |
|---|---|---|---|
| 兜圈 | 步数/工具轨迹 | 编排 | 08 |
| 幻觉 | 引用/是否走 RAG | 模型/数据 | 11 |
| 工具报错 | validation/exec 事件 | 工具/校验 | 06 |
| 越权/泄露 | 高危调用/注入源 | 安全 | 14 |
| 贵/慢 | Token/步数 | 成本 | 18 |
| 重复执行 | 幂等键/checkpoint | 可靠性 | 15 |
关联章节
面试复述
排障先看完整轨迹，再按层定位。每个故障都应记录现象、影响、证据、假设、验证、缓解、根因、回归和预防；缺少 Trace 时，首要修复是补可观测性。
复述时先给结论，再补机制、适用边界和一个可验证指标；不要只罗列框架名称或产品功能。
迁移练习
从历史事故中选一条，用本章九段式模板重新整理，并补一条能稳定复现该问题的自动化回归测试。
检索关键词
Agent 故障排查 兜圈 打满步数 幻觉定位 工具失败 注入越权排查 成本失控 重复执行
官方来源
- 本章为工程经验综合，结合各章方法；
verified_at: 2026-09-07。