题目 1:工具选错与参数错误有什么区别?为什么两类问题的修复方向不同?
如果任务需要读取文件,模型却选择 write_file,这是 Tool Selection Error,说明能力选择阶段出了问题,应检查 Tool 描述、命名、Skill 或决策 Prompt;如果模型选择了正确的 read_file,但 path 写错,则属于 Argument Error,应检查 Schema、参数约束、路径发现和 Error Observation。两者表面都可能导致 Tool 失败,但根因层不同。
题目 2:如何区分 Context Failure 和 Agent 幻觉?
如果项目规则明明存在,但最终送给模型的 Context 中根本没有它,模型随后违反规则,这是 Context Failure;如果 Trace 中从未出现成功 Tool Result,模型却声称“测试已通过”“文件已修改”,则属于没有证据支撑的 Unsupported Claim。前者应修 ContextBuilder,后者应增加 Evidence Check 和 Completion Gate。
题目 3:如何判断 Retry 是有效 Recovery,还是已经进入循环?
有效 Recovery 会根据 Error Observation 改变下一步,例如 FileNotFoundError 后先 list_files 再读取正确路径;无效 Retry 则会重复相同 Tool、相同 Arguments 和相同 Error Signature,状态没有推进。Trace 中如果连续出现这些模式,应触发 RepetitionDetector、Reminder、Replan 或 RunGuard。
题目 4:编程实现——定义一个最小 FailureReport,至少包含 run_id、first_bad_step、failure_type、root_cause 与 fixes。
from dataclasses import ( dataclass, field, ) @dataclass class FailureReport: run_id: str first_bad_step: int failure_type: str root_cause: str fixes: list[str] = field( default_factory=list ) if __name__ == "__main__": report = FailureReport( run_id="run_demo", first_bad_step=1, failure_type="context_failure", root_cause=( "AGENTS.md 未进入 Context" ), fixes=[ "自动加载 AGENTS.md", "项目规则接入 Middleware", ], ) print(report)
题目 5:为什么 Failure Postmortem 要找 First Bad Step,而不是只看最后一个 FAILED Step?
最后一个 FAILED Step 通常只是故障结果。例如 Run 在 Step 30 因 MaxStepsExceeded 停止,但真实根因可能从 Step 8 开始重复相同错误动作。如果只看最后一步,很容易错误地把 MAX_STEPS 调大。First Bad Step 能帮助我们找到执行链最早偏离正确路径的位置,从而修到根因而不是症状。
题目 6:为什么“证据已经够了但继续调用 Tool”属于 Agent 质量问题?
继续无边界调用 Tool 不仅增加 Token、Latency 和 Cost,还会把更多次要信息加入 Context,增加模型被噪声带偏的概率。一个成熟 Agent 应该有 Evidence-based Stop Condition,当主要异常指标和维度已经有足够 Tool Result 支撑时及时结束。效率和结论清晰度都是 Agent 质量的一部分。
题目 7:失败复盘完成后,为什么必须把样本加入 Benchmark?
一次修复只证明当前版本解决了问题。未来更换模型、调整 Prompt、修改 Skill 或重构 Tool 时,同类问题可能重新出现。将失败样本转成 Regression Benchmark 后,每次版本迭代都可以自动验证问题没有回归。这样失败会沉淀成长期测试资产,而不是一次性经验。
进一步阅读
- Root Cause Analysis:区分现象、直接原因、辅助因素和真实根因。
- Failure Taxonomy:建立团队统一的 Agent 故障分类。
- Regression Testing:把真实失败样本沉淀成长期回归任务。
- No Progress Detection:识别 Agent 动作很多但状态没有推进。
- Evidence-based Completion:最终结论必须有 Tool Evidence 支撑。
- Stop Condition Design:避免提前结束和无边界探索。
- Trace Analysis:从 Step 时间线反向定位 First Bad Step。
- Agent Evaluation:将失败类型与 Benchmark 指标结合起来持续迭代。
术语表
- Failure Postmortem:对失败 Run 进行结构化复盘,定位最早异常 Step、根因、辅助因素、修复方案和回归任务。
- First Bad Step:执行链中第一个明显偏离正确路径的 Step,通常比最终 FAILED Step 更接近根因。
- Tool Selection Error:模型选择了错误 Tool,例如本应 read_file 却选择 write_file。
- Argument Error:Tool 选择正确,但具体参数错误,例如路径、SQL 字段、日期范围或命令参数不正确。
- Context Failure:Agent 需要的重要规则、Memory、Tool Result、Plan 或 Completion Criteria 没有进入当前 Context。
- Recovery Failure:Tool 失败以后 Agent 没有根据 Error Observation 调整策略,反而重复同类失败动作。
- Premature Termination:Success Criteria 尚未满足,Agent 就提前进入 COMPLETED 或输出最终答案。
- Over-tooling:任务已经拥有足够证据,Agent 仍继续无边界调用 Tool,造成额外成本、噪声和结论漂移。
- Symptom:能直接观察到的异常表现,例如超过最大步数;它是调查入口,不自动等于根因。
- Root Cause Confidence:对根因判断可信度的显式标记,例如 hypothesis、probable 和 confirmed。已确认根因应能关联到具体证据。
- Corrective Action:为预防、检测或缓解同类故障而实施的可追踪措施,需要有负责人、状态与验证方式。
- Near Miss:高风险行为已被触发,但在造成真实损害前被 Policy、Approval 或人工阻止的事件。
本章总结
这一节,我们把 AgentOps 的最后一个关键闭环补上了,失败以后,如何真正找到根因。
前面有:
Tracing
Metrics
Evaluation
但如果失败以后仍然只说:
“模型不够聪明。”
那这些基础设施都没有真正发挥价值。
这章最重要的第一条原则是,Agent 失败是一条执行链,而不是一个点。
完整链路可以看成:
Context
↓
LLM Decision
↓
Tool
↓
Arguments
↓
Tool Result
↓
Observation
↓
Recovery
↓
Next Action
↓
Stop Condition
任何一层都可能出错。
第二条原则是,先找 First Bad Step。
最终的:
FAILED
往往只是结果。
比如:
Step 30:
MaxStepsExceeded
真正问题可能从:
Step 8:
重复相同 Tool + Arguments + Error
就已经开始。
第三条原则是,不要把所有失败都归到“模型”。
我们建立了:
Context Failure
Decision Failure
Argument Failure
Tool Failure
Observation Failure
Recovery Failure
Loop Failure
Termination Failure
Policy Failure
Orchestration Failure
不同 Failure Type 对应不同修复层。
例如:
Context Failure
→ ContextBuilder / Memory / Compaction
Argument Failure
→ Tool Schema / Validation
Loop Failure
→ RepetitionDetector / RunGuard
Termination Failure
→ Completion Criteria / Stop Condition
Policy Failure
→ Middleware / ProjectPolicy
这样就不会遇到任何问题都只会:
继续加 Prompt。
第四条原则是,Retry 不等于 Recovery。
真正 Recovery 必须:
读懂 Error
改变策略
产生新状态
如果只是:
同一个 Tool
同一个参数
同一个错误
不断重复,那是循环。
第五条原则是,提前结束和过度调用 Tool,本质上都需要更好的 Stop Condition。
Agent 必须知道:
什么还没做完
什么时候证据足够
什么时候可以真正结束
第六条原则是,没有 Tool Evidence,不得声称现实动作已经完成。
这对 Coding Agent 特别重要。
如果 Trace 中没有:
pytest returncode = 0
就不能说:
测试已通过。
如果没有真正的 write_file Result,就不能说:
文件已修改。
最后,我们把失败复盘固定成:
Task
↓
Observed Failure
↓
First Bad Step
↓
Trace Evidence
↓
Failure Type
↓
Root Cause
↓
Contributing Factors
↓
Fix
↓
Regression Benchmark
这里最后一步非常关键,把失败变成测试资产。
每一次真实失败,如果能加入 Regression Benchmark,就会让 Agent Harness 在后续模型、Prompt、Skill、Tool 变化时持续检查:
这个老问题有没有回来?
这才是真正成熟的工程迭代。
到这里,第7部分,Observability 与 AgentOps
已经完整闭环:
Tracing
→ 看清发生了什么
Metrics
→ 看清花了多少资源
Evaluation
→ 看清整体表现
Failure Postmortem
→ 看清为什么失败
下一部分,我们会把前面所有能力收束进两个完整端到端项目。
第一个就是,从 0 打造 Coding Agent。
它会真正串起:
AGENTS.md
Skills
Planner
Tool Registry
Error Recovery
Middleware
Sandbox
Human Approval
Tracing
Evaluation
让 Agent 面对一个陌生 Python 项目,自己完成:
扫描
定位
修改
测试
失败恢复
再次验证
最终汇报
这也是整门课程从“组件设计”走向“完整系统”的关键转折点。

















请登录后查看评论内容