跳到主要内容

失败案例分析

1. 定义与边界​

失败案例分析是从一次 Agent 失败的 trace、日志、指标和用户反馈中提取根因、修复动作和回归样本的流程。它不是简单写“模型理解错了”，而是要定位到可改变的工程组件。

2. 为什么重要​

Agent 失败通常是系统性问题。没有结构化分析，团队会反复调提示词，却忽略工具 schema、权限、检索数据、策略、超时、用户交互设计等真正原因。

3. 核心机制​

失败归因树：

4. 工程实现​

分析模板：

## 失败摘要
- trace_id:
- 用户目标:
- 实际结果:
- 期望结果:

## 证据
- 关键 span:
- 工具调用:
- 错误码:
- 用户反馈:

## 根因
- primary_reason:
- contributing_factors:

## 修复
- prompt:
- tool_schema:
- policy:
- retrieval:
- test:

## 回归样本
- case_id:
- expected_behavior:

常用失败标签：

标签说明
intent_misread用户目标理解错误
missing_clarification应澄清但未澄清
bad_plan计划缺步骤或顺序错误
wrong_tool工具选择错误
bad_args工具参数错误
tool_failure_unhandled工具失败处理错误
policy_bypass权限或确认绕过
hallucinated_state编造外部状态

5. 生产实践​

  • P0/P1 事故必须产出失败分析和回归样本。
  • 高频失败按聚类处理，避免逐条人工分析。
  • 分析结论要能落到某个组件 owner。
  • 修复后必须用同一 trace 派生的样本验证。

6. 常见反模式​

  • 根因写成“模型不够聪明”。
  • 没有证据链，只看最后回答。
  • 修复动作只有“优化提示词”。
  • 没有把案例加入回归集。

7. 评测方法​

指标用途
Root Cause Coverage失败是否完成归因
Time to Triage从发现到分类的时间
Fix Verification Rate修复是否有评测验证
Regression Added Rate是否沉淀回归样本
Repeat Failure Rate同类失败是否再次出现

8. 安全与治理​

安全失败案例需要单独流程：限制访问、保留证据、通知安全负责人、评估影响范围、确认是否需要用户或监管通知。分析材料中不得扩散敏感数据。

9. 权威资料​

16. 主控验收清单​

  • 是否每个失败案例都有 owner 和截止日期。
  • 是否至少产生一个回归样本、告警或 runbook 更新。

10. 二次精修：失败复盘模板​

失败案例分析要产出可执行修复，而不是只写事故故事。

incident:
  id: "inc_20260509_refund_loop"
  severity: "sev2"
  detected_by: "CostPerSuccessSpike"
  started_at: "2026-05-09T09:20:00Z"
  mitigated_at: "2026-05-09T09:45:00Z"
  affected_runs: 128
  customer_impact: "退款查询延迟，未发生资金副作用"
  versions:
    agent: "1.8.2"
    prompt: "refund.system@2026-05-09.3"
    tool: "search_order@2.1.0"
章节必须回答
影响影响了谁、多久、损失多大
时间线何时开始、发现、止血、恢复
根因直接原因和系统性原因
证据trace、日志、指标、反馈
修复代码、prompt、策略、工具
预防回归样本、告警、runbook

11. 根因分析流程​

12. 失败分类​

分类典型根因修复方向
Prompt指令歧义、变量缺失prompt 版本和 eval
Toolschema 错、下游异常契约测试和重试
State状态丢失、并发覆盖checkpoint 和乐观锁
Safety策略缺失、审批绕过guardrail 和安全评测
Cost循环、上下文膨胀预算和熔断
Observabilitytrace 缺失SDK 和字段治理

13. 复盘验收​

  • 每个事故至少新增一个回归样本或告警规则。
  • 复盘要明确“不再发生”的工程机制，而不是只说加强关注。
  • 高风险事故要验证是否需要通知用户、客户、监管或安全团队。
  • 证据包要脱敏并限制访问。
  • 修复完成后要做回放，确认 trace 轨迹和指标恢复。

14. 指标​

指标目标
Time to Root Cause越短越好
Regression Coverage事故样本进入回归集
Repeat Incident Rate复发率下降
Evidence Completenesstrace/log/metric/feedback 是否齐全
Action Item Closure修复项按期关闭

15. 补充权威资料​