Agent 事故复盘模板：把一次线上失败变成可复用资产
这篇文章解决什么问题
Agent 系统一旦上线，就一定会遇到失败：答错、检索漏召回、工具超时、越权拦截、成本飙升、Prompt Injection、用户投诉。真正拉开差距的不是“永不失败”，而是每次失败后能不能复盘、修复、回归和沉淀。
Agent 事故复盘模板的目标是把一次线上事故转化为工程资产：失败样本、错误分类、评测用例、Runbook、发布门禁和产品改进。
Agent 事故和普通后端事故的区别
普通后端事故通常可以从日志、指标和异常堆栈定位。Agent 事故更复杂，因为失败可能来自模型、Prompt、RAG、工具、状态机、权限、上下文、用户意图和产品交互。
| 事故来源 | 示例 |
|---|---|
| Prompt | 新版本 Prompt 导致回答格式不稳定 |
| Model | 模型切换后工具调用参数变差 |
| RAG | 检索没有召回关键文档，或引用不支持答案 |
| Tool | 外部 API 超时、schema 变更、权限不足 |
| State | 长任务状态丢失、重复执行副作用 |
| Safety | Prompt Injection 诱导模型调用危险工具 |
| Product | 用户不知道需要审批，误以为任务卡死 |
| Ops | 队列积压、成本异常、限流配置不合理 |
因此 Agent 复盘必须覆盖文本质量和工程链路两部分。
复盘文档结构
建议每次事故都按固定模板记录：
- 事故摘要
- 影响范围
- 时间线
- 用户视角表现
- Trace 与证据
- 根因分析
- 错误分类
- 处置动作
- 修复方案
- 回归样本
- 发布门禁更新
- 后续负责人和截止时间
不要只写“已修复”。复盘的价值在于让同类问题以后更早被发现。
事故摘要模板
| 字段 | 示例 |
|---|---|
| incident_id | AGENT-INC-2026-001 |
| 发现时间 | 2026-06-06 20:15 |
| 发现来源 | 用户反馈、报警、人工巡检、评测回归 |
| 影响功能 | RAG 问答、数据分析 Agent、MCP 工具调用 |
| 严重等级 | P0 / P1 / P2 / P3 |
| 当前状态 | mitigated、fixed、monitoring |
| 负责人 | owner |
严重等级建议和用户影响绑定：
| 等级 | 判断标准 |
|---|---|
| P0 | 数据泄漏、越权执行、危险副作用、核心服务不可用 |
| P1 | 大范围错误回答、任务大量失败、成本异常飙升 |
| P2 | 局部功能异常、部分用户受影响、有替代路径 |
| P3 | 文案、体验、低风险质量问题 |
时间线怎么写
时间线要记录“用户发生了什么”和“系统做了什么”。
| 时间 | 事件 | 证据 |
|---|---|---|
| 20:15 | 用户反馈答案引用错误 | feedback_id |
| 20:18 | 值班人查看 run trace | run_id |
| 20:25 | 发现检索 top_k 中没有关键文档 | retrieval_trace |
| 20:40 | 临时回滚 Prompt 版本 | deploy_id |
| 21:10 | 新增回归样本并验证通过 | eval_run_id |
| 21:30 | 恢复灰度流量 | release_id |
时间线不要只写结论，要能让后来者复盘定位路径。
Trace 与证据清单
Agent 事故复盘一定要收集证据。没有证据的复盘很容易变成猜测。
| 证据 | 用途 |
|---|---|
| user_input | 判断用户意图和输入边界 |
| final_answer | 判断输出问题 |
| prompt_version | 判断是否由 Prompt 变更引入 |
| model_config | 判断模型版本、温度、工具模式 |
| retrieved_chunks | 判断检索召回和证据质量 |
| tool_calls | 判断工具选择、参数、错误 |
| state_transitions | 判断任务状态是否正确推进 |
| approvals | 判断高风险动作是否经过审批 |
| cost_latency | 判断成本和性能异常 |
| logs_alerts | 判断基础设施问题 |
注意：复盘材料要遵守数据治理要求，敏感信息需要脱敏，跨租户数据不能复制到公共文档。
根因分析框架
推荐用“现象 → 直接原因 → 系统原因 → 预防机制缺失”四层分析。
示例：
| 层级 | 内容 |
|---|---|
| 现象 | 用户问合同条款，Agent 给出错误引用 |
| 直接原因 | RAG 召回的 chunk 不包含关键条款 |
| 系统原因 | 文档入库时表格解析失败，关键条款没有被正确 chunk |
| 机制缺失 | 入库质量检查没有覆盖表格解析，评测集没有合同表格样本 |
不要把根因停留在“模型幻觉”。如果回答错了，要继续追问证据链、检索链、Prompt、上下文和评测覆盖。
错误分类表
| 分类 | 典型表现 | 后续动作 |
|---|---|---|
| input_error | 用户输入不完整、歧义大 | 增加澄清问题 |
| context_error | 上下文缺失、过长、排序差 | 优化 context packing |
| retrieval_error | 漏召回、错召回、权限过滤错误 | 修复入库、召回、rerank |
| model_error | 推理错误、格式不稳 | Prompt、模型路由、评测 |
| tool_error | 工具超时、参数错、schema 变更 | 工具契约测试 |
| state_error | 状态跳转错误、重复执行 | 状态机和幂等修复 |
| policy_error | 越权、审批缺失、策略误拦截 | 权限和策略修复 |
| ux_error | 用户误解状态或结果 | 前端提示和交互改进 |
| ops_error | 队列、部署、配置、监控问题 | Runbook 和报警修复 |
分类的目的不是贴标签，而是决定修复路径。
修复动作怎么沉淀
一次合格复盘至少产出四类资产：
| 资产 | 示例 |
|---|---|
| 代码修复 | 修复 chunk 解析、工具 schema、状态转移 |
| 评测样本 | 把失败输入加入 regression set |
| 监控报警 | 新增引用准确率、工具错误率、队列积压报警 |
| 文档 Runbook | 更新排查步骤、回滚策略、审批规则 |
如果事故只改了 Prompt，没有新增评测和门禁，下次很可能复发。
回归样本模板
| 字段 | 内容 |
|---|---|
| case_id | regression_contract_table_001 |
| source_incident | AGENT-INC-2026-001 |
| input | 脱敏后的用户问题 |
| expected_behavior | 应引用合同表格第 N 条，证据不足时拒答 |
| required_evidence | document_id、chunk_id |
| scoring | citation、factuality、no-answer behavior |
| risk_level | P1 |
| owner | 评测负责人 |
失败样本进入评测集后，要标注来源和风险等级，避免未来被误删。
复盘会议问题清单
可以按下面问题开复盘会：
- 用户最先感知到的问题是什么？
- 系统有没有报警？如果没有，为什么？
- Trace 是否足够还原执行过程？
- 问题来自输入、检索、模型、工具、状态、权限还是体验？
- 是否有临时止血动作？止血是否安全？
- 是否需要回滚 Prompt、模型、RAG 索引或工具版本？
- 哪个评测集应该覆盖这个问题？
- 哪个发布门禁应该阻止类似问题上线？
- 是否需要更新用户提示、审批规则或运营台？
- 谁负责修复，什么时候完成，如何验证？
面试表达模板
可以这样讲：
我会把 Agent 事故复盘做成工程闭环。事故发生后先收集 run trace、prompt_version、model_config、retrieved_chunks、tool_calls 和状态转移，再按 input、context、retrieval、model、tool、state、policy、ux、ops 分类定位根因。修复不只改代码，还要把失败样本加入 regression set，更新 release gate 和 runbook，确保同类问题下次能被自动评测或报警发现。
常见误区
误区一：把所有问题都归因给模型
模型可能是表现层，根因可能是检索、上下文、工具、权限或产品设计。
误区二：复盘只写给管理者看
复盘文档应该能指导工程修复、评测补样本、运维加报警和产品改交互。
误区三：没有脱敏就复制线上数据
Agent Trace 往往包含用户输入、文档片段、工具参数和内部策略，复盘时必须遵守数据治理要求。