章末自测

题目 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 项目,自己完成:

扫描
定位
修改
测试
失败恢复
再次验证
最终汇报

这也是整门课程从“组件设计”走向“完整系统”的关键转折点。

© 版权声明
THE END
喜欢就支持一下吧
点赞9 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容