发布时间：2026-09-2
标签：AI Agent｜工程实践｜Failure Analysis｜错误分类

---

上一篇我留了个悬念：最小版 Agent 跑出来的结论里，藏着一个致命问题。

就是这句："核心函数是 payment_process()"。

我去仓库里搜了一遍，发现根本没有这个函数。它是我那个 Agent 编出来的。

那一刻我意识到一件事：在 Agent 开发里，你最需要研究的第一门学问，不是怎么让它跑起来，而是它跑起来之后，会以哪几种方式做错。

---

系列导航

• 上一篇：AI Agent 工程实践（39）：第一次实现——先做一个最小 Agent
• 下一篇：AI Agent 工程实践（41）：怎么调 Agent——不要再靠改 Prompt

---

问题背景

这是第五阶段的第五篇。前面四篇，我们选对了问题、拆清了需求、画好了架构、做出了最小版。现在，到了这个系列最有辨识度的一篇：正面研究"失败"本身。

传统软件工程里，bug 是意外；但在 Agent 工程里，出错是常态。因为你的核心执行单元是一个概率性的大模型，它每一步都可能偏。所以，如果你不理解"它会怎么错"，你就永远只能靠"再改改 Prompt 试试"这种瞎猫碰死耗子的方式去修。

这一篇要做的，是把 Agent 的失败做成一棵分类树。有了这棵树，你才能从"感觉它错了"升级到"知道它错在哪一类、该去哪一层修"。

---

错误尝试：五个真实案例，五个失败

我把最小版 Agent 拿去跑真实问句，挑了五个有代表性的失败，逐个记录：

案例 1：问"支付逻辑在哪"，它调了 git_log 而不是 grep。
→ 应该搜代码，它却去查提交历史，方向就错了。

案例 2：问"入口文件是什么"，它读了 3 个无关文件才蒙对。
→ 检索方向没错，但读错了文件，浪费了大量 Token。

案例 3：让它查"登录功能"，它传了 grep(keyword="login") 但仓库里实际是 signin。
→ 工具选对了，参数写错了，什么都搜不到。

案例 4：问"这个 bug 为什么发生"，它读完两个文件就下了结论，跳过了关键的反例。
→ 证据不足，却自信地编了一个完整的因果链。

案例 5：就是上一篇那个 payment_process()——根本不存在的函数。
→ 纯粹的幻觉，无中生有。

我一开始面对这五个失败，反应和大多数人一样：统一归因为"模型不行，改 Prompt"。 结果越改越乱。

---

关键观察：失败是一棵分类树

转折点在于，我把这五个失败放一起看，发现它们根本不是同一种错：

案例	表面现象	真正的错误类型
1	查错方向	Tool Selection Error（选错工具）
2	读错文件	Retrieval Error（检索错对象）
3	搜不到	Argument Error（参数错误）
4	证据不足就下结论	Reasoning Error（推理跳跃）
5	无中生有	Reasoning Error（幻觉，最严重）

它们落在不同的层：有的错在"选工具"那一层，有的错在"传参数"那一层，有的错在"下结论"那一层。

核心洞察：

Agent 的失败不是一个 bug，是一棵分类树——不分类，你就只能永远"再改改 Prompt 试试"。

---

最终方案：Agent Failure Taxonomy（七类错误）

我把 Agent 的失败系统性地分成了七类，这成了我后来调试所有 Agent 的第一张查表：

#	错误类型	含义	典型症状	根因通常在哪一层
1	Planning Error	计划错了	步骤顺序乱、漏掉关键步骤	Planner / Prompt
2	Tool Selection Error	选错工具	该 grep 却用 git_log	Tool 描述 / Prompt
3	Argument Error	参数错了	搜 login 实际是 signin	Tool 描述 / 模型
4	Retrieval Error	读错对象	读了无关文件	Context / State
5	State Error	状态丢了/串了	忘了已经查过、重复查	State 管理
6	Reasoning Error	推理跳跃或幻觉	证据不足下结论、编造	Context / Reviewer 缺失
7	Output Error	输出格式/内容错	结论没证据、格式乱	Output 约束

这张表的关键，不只是"七类"这个分类，而是每一类都指向了不同的修复层：

这一步是整个系列最重要的分水岭：从"感觉错了"到"定位到类"，是你能不能系统化调 Agent 的关键。下一篇，我会基于这棵树，建立一套不再靠"改 Prompt"的调试循环。

---

代码或配置示例

七类失败不该只停留在脑子，应该落成一份可复用的分类清单，每次 Agent 出错就对照着打标签：

# repo_doctor/failure_taxonomy.yaml —— 失败分类的事实源
failure_taxonomy:
  - id: planning_error
    symptom: 步骤顺序乱、漏步骤
    fix_layer: planner
  - id: tool_selection_error
    symptom: 选错工具
    fix_layer: tool_description
  - id: argument_error
    symptom: 参数填错
    fix_layer: tool_schema
  - id: retrieval_error
    symptom: 读了无关内容
    fix_layer: context_builder
  - id: state_error
    symptom: 重复查、忘记已查
    fix_layer: state_manager
  - id: reasoning_error
    symptom: 证据不足下结论、幻觉
    fix_layer: reviewer
  - id: output_error
    symptom: 结论无证据、格式乱
    fix_layer: output_constraint

有了这份 YAML，后续每次调试，第一步不再是"改 Prompt"，而是先给这次失败打一个标签，然后顺着标签去对应的层修。这就是下一篇要展开的 Debugging Loop 的起点。

---

设计权衡

候选方案	优点	缺点	为什么不选
全部归因"模型不行"	省事	无法定位，只能盲目改 Prompt	掩盖了错误的结构性差异
每个错误单独分析	精确	无法复用，每次从零开始	不积累，无法形成方法论
七类分类树	可复用、可定位到层	分类边界偶有模糊	在"够用"和"系统化"之间平衡

一个诚实的边界：七类之间有时会重叠（比如 Reasoning Error 常常由 Retrieval Error 诱发）。分类的价值不在"分得绝对干净"，而在"逼你先想清楚它大概是哪一类"，从而找对修复的方向，而不是无脑改 Prompt。

---

总结

✅ 出错是 Agent 的常态，不是意外。
✅ 失败必须分类，七类：Planning / Tool Selection / Argument / Retrieval / State / Reasoning / Output。
✅ 每一类都指向一个不同的修复层，这是从"感觉"到"定位"的分水岭。
✅ 铁律：Agent 的失败是一棵分类树，不分类就只能永远改 Prompt。
✅ 分类清单落成 YAML，作为后续调试的第一张查表。

---

参考资料

• LangSmith 的 Trace 分析文档 → 为什么引用：它把 Agent 失败按 span 类型拆解，是七类分类的实践来源之一。
• 《Designing Agentic Systems》中关于 error mode 的讨论 → 为什么引用：系统性枚举失败模式，正是本篇的方法论。

---

系列导航

• 上一篇：AI Agent 工程实践（39）：第一次实现——先做一个最小 Agent
• 下一篇：AI Agent 工程实践（41）：怎么调 Agent——不要再靠改 Prompt

本文是 [AI Agent 工程实践] 系列的第 40 篇。