跳到主要内容

Agent Observability and Debugging

当你开始做 AI Agent，很快就会发现一个现实问题：

Agent 出问题时，往往不是“最后答案错了”这么简单。

它更常见的失败方式是：

  • 第一步就选错工具
  • 拿到了正确资料却没用上
  • 中间状态丢了
  • 不断重复某个循环
  • 本来应该停止，却继续多跑了好几步

所以对 Agent 来说，调试对象不只是输出结果，而是整条执行轨迹。

也正因为如此，Observability 和 Debugging 会成为 Agent 工程化里非常关键的一环。

1. 为什么 Agent 比普通问答更难调试​

普通问答系统很多时候只需要看：

  • 输入是什么
  • 输出是什么

最多再看一下 prompt 和检索资料。

但 Agent 多了一整层运行过程：

  • 每一步决策
  • 工具调用
  • 工具结果
  • 状态变化
  • 停止条件

也就是说，Agent 的错误可能发生在：

  • 目标理解
  • 任务拆解
  • 工具选择
  • 参数生成
  • 结果整合
  • 状态管理
  • 结束判断

这就是为什么：

没有可观测性，Agent 就很难被稳定调试。

2. 什么是 Agent Observability​

在这里，Observability 可以理解为：

让 Agent 的运行过程变得可看见、可追踪、可复盘。

它通常不只是日志，而是围绕下面这些问题来设计：

  • 它现在在做什么
  • 它为什么这么做
  • 它调了什么工具
  • 工具返回了什么
  • 当前状态怎么变了
  • 它为什么继续，为什么停止

3. 调试 Agent 时最应该看什么​

3.1 Goal​

先看系统理解到的目标是什么。

因为很多问题的根源不是后面流程差，而是第一步目标就理解偏了。

3.2 Step Trace​

也就是每一步发生了什么。

例如：

  1. 当前判断
  2. 执行动作
  3. 得到观察结果
  4. 更新后的状态

3.3 Tool Call Trace​

也就是工具调用轨迹。

包括：

  • 选了哪个工具
  • 参数是什么
  • 执行是否成功
  • 返回结果是什么

3.4 State Transition​

也就是状态怎么变化。

比如：

  • 已完成步骤列表
  • 当前待办
  • 当前证据集合
  • 失败重试计数

3.5 Stop Reason​

也就是 Agent 为什么结束。

这是非常容易被忽视的一项，但对调试特别重要。

因为系统可能是：

  • 真完成了
  • 误以为完成
  • 到了最大步数
  • 卡住后被强制停止

4. 一条典型的调试链路​

很多 Agent 的调试都可以抽象成下面这条链路：

User Goal -> Plan/Decision -> Tool Call -> Observation -> State Update -> Final Output

当结果不理想时，你最好不要只问：

  • “为什么答案错了”

而应该依次问：

  • 目标有没有理解错
  • 决策有没有偏
  • 工具有没有选错
  • 参数有没有错
  • 返回结果有没有被正确使用
  • 状态有没有丢
  • 停止条件是不是判断错了

5. 最常见的 Agent 故障类型​

5.1 Tool Selection Error​

该调用工具时没调，不该调时乱调。

5.2 Tool Argument Error​

工具选对了，但参数不对。

5.3 Evidence Integration Error​

拿到了正确结果，却没有正确整合进后续推理。

5.4 State Loss​

前面已经确认的信息，后面又忘了。

5.5 Looping​

不断重复类似动作，没有实质推进。

5.6 Premature Stop​

任务还没完成，系统却以为完成了。

5.7 Overrun​

其实已经够了，但系统还在继续跑，导致成本和延迟变高。

6. Agent 里应该记录哪些日志​

如果你只做最小可用的观测，我建议优先记录这几类。

6.1 Run Metadata​

包括：

  • 任务 ID
  • 用户输入
  • 模型版本
  • prompt 版本
  • 工具版本

6.2 Step Log​

包括：

  • 第几步
  • 当前意图
  • 决策摘要
  • 执行动作

6.3 Tool Log​

包括：

  • 工具名
  • 参数
  • 返回结果
  • 错误信息
  • 耗时

6.4 State Snapshot​

包括：

  • 当前目标
  • 已完成事项
  • 当前证据
  • 剩余待办

6.5 Final Outcome​

包括：

  • 最终结果
  • 停止原因
  • 总步数
  • 总成本
  • 是否成功

7. Debugging 时一个很实用的思路​

不要把所有问题都归因成“prompt 不行”。

Agent 的问题通常可以分成 4 层：

7.1 Prompt / Instruction 问题​

比如：

  • 没有明确要求使用工具
  • 没有明确结束条件
  • 没有约束输出行为

7.2 Tooling 问题​

比如：

  • 工具 schema 太模糊
  • 工具参数不清晰
  • 工具返回结构不好用

7.3 Orchestration 问题​

比如：

  • 循环控制不好
  • 状态更新缺失
  • 重试策略有问题

7.4 Evaluation 问题​

比如：

  • 其实系统已经退化，但团队没及时发现
  • 问题出现在线上，却没有沉淀回归样本

这个分层很重要，因为不同层的修法完全不同。

8. Observability 和 Harness 的关系​

这两个概念很接近，但最好区分开。

8.1 Observability 更偏“看见运行过程”​

它关注：

  • trace
  • log
  • metric
  • runtime diagnosis

8.2 Harness 更偏“组织运行与评估闭环”​

它关注：

  • 任务集
  • 版本对比
  • 回归验证
  • 评分分析

可以把它们理解成：

  • Observability 帮你看清单次运行
  • Harness 帮你系统化比较多次运行

两者最好配合使用。

9. 一个很实用的排查顺序​

如果一个 Agent 结果明显不对，我建议按这个顺序排：

  1. 看最终输出
  2. 看停止原因
  3. 看最后几步轨迹
  4. 看工具调用记录
  5. 看状态变化
  6. 再回头看 prompt 和 orchestration 逻辑

这样做的好处是：

  • 更快定位最可能的断点
  • 避免一上来就全面重写 prompt

10. 怎么把线上问题变成可复现问题​

这是 Agent 调试里最关键的工程能力之一。

一个好的团队不会只在线上看告警，而是会把失败沉淀下来。

建议至少保留：

  • 原始任务输入
  • 当时的配置版本
  • 关键轨迹
  • 失败结果

然后把它们转成：

  • 回归测试样本
  • Harness 任务集
  • 问题分类标签

这样你修完之后，才能真正验证“这个问题以后不会再悄悄回来”。

11. 常见误区​

11.1 只记录最终答案​

这对 Agent 往往远远不够。

11.2 日志很多，但没有结构​

如果什么都打，但没有统一字段，最后一样很难排查。

11.3 一看到问题就改 prompt​

很多问题其实根本不是 prompt 问题，而是工具、状态或编排问题。

11.4 调试只看单次案例​

单个失败案例很重要，但如果没有进入任务集和回归体系，就很难形成长期改进。

12. 一句话总结​

如果说普通问答系统主要调的是“答案质量”，那么 Agent 系统真正要调的是：

目标理解、过程决策、工具调用、状态变化和停止条件这一整条运行链路。

所以对 Agent 来说，Observability 的核心价值就是：

把原本黑盒的多步执行过程，变成一个可追踪、可解释、可复盘的系统。