Observability：Agent 出问题时要看见哪一步

今天先记住

Observability（可观测性）不是把日志打多一点，而是让你在 Agent 失败时能回答三个问题：它看见了什么、决定了什么、实际做了什么。没有这三层证据，系统一出错就只能靠猜。

它在大地图里的位置

今日坐标

评估 / 修正 → Observability

txt

用户目标
  -> 上下文 / 记忆
  -> 规划 / 决策
  -> 工具调用 / 外部系统
  -> 执行 / 观察结果
  -> ▶ 评估 / 修正
  -> 最终输出

昨天讲成本和延迟，是看一次任务花了多少、等了多久。今天的可观测性更靠近“为什么会这样”：当 Agent 走错路时，你要能沿着上下文、计划、工具调用、观察结果一路回放，而不是只看到一句失败文案。

它到底是什么

在 Agent 里，可观测性通常由 trace（执行轨迹）、span（某一步的记录）、事件日志、工具输入输出、模型请求摘要、状态快照组成。

它记录的重点不是“模型想了什么玄学理由”，而是工程上可检查的链路：用户输入是什么，系统注入了哪些上下文，Agent 选择了哪个工具，参数是什么，工具返回了什么，下一步状态有没有改变，最后输出是什么。

普通服务看 HTTP 状态码和耗时就能定位很多问题；Agent 不行。它可能返回 200，但读错记忆、选错工具、重复执行，或者在缺少信息时自作主张。

为什么 Agent 里会用到它

Agent 的错误经常藏在中间步骤。比如用户要求“只发布今天这一篇文档”，最终页面确实上线了，但提交里混进了无关文件。只看最终输出会觉得成功；看 trace 才会发现 git add 的文件集合越界。

可观测性把这类问题从“感觉不对”变成可定位状态：哪一步读到了多余文件，哪一步没有检查暂存区，哪一步把失败当成成功继续走。这样修复时不是改一句 prompt 祈祷，而是补一个检查点、改一条权限规则，或加一个评估用例。

怎么判断它有没有用

如果一次任务会跨多个工具，至少要记录每个工具的输入、输出和耗时。
如果 Agent 会改变外部状态，要记录动作发生前后的状态差异，比如 staged files、目标分支、发送对象。
如果日志只能看到最终回答，看不到中间决策，那它不够支撑排障。
如果 trace 里有大量原始隐私内容，要先做脱敏和权限分层，否则可观测性本身会变成风险。

一个小例子

txt

Input:
用户说：“生成并发布 2026-07-30 的 AI Agent Daily，只提交相关文件。”

Process:
1. 读取课程框架和上一篇文章。
2. 写入 docs/ai-agent/2026-07-30.md。
3. 检查敏感内容。
4. 查看 git status。
5. 只暂存当天 Markdown。
6. commit 并 push。

Output:
trace 里至少能看到：
read_framework -> ok
write_file -> docs/ai-agent/2026-07-30.md
secret_scan -> passed
git_status -> unrelated=.workbuddy/
git_add -> only docs/ai-agent/2026-07-30.md
push -> main updated

这个例子可以拿去判断真实系统：如果它出问题后只能告诉你“发布失败”，那还不够；至少要能指出失败发生在写文件、检查、暂存、提交还是推送。

常见误区

以为日志越多越好。没有结构的长日志只会让排障更慢。
只记录模型输入输出。Agent 的工具参数、状态变化和外部结果同样关键。
把可观测性等同于监控面板。漂亮图表不能替代可回放的执行轨迹。
忽略脱敏。trace 可能包含用户文本、文件路径、工具返回和权限信息，不能无脑外发。

今天自测

Agent 失败时，你最想先看到哪三类中间信息？
为什么“最终回答正确”仍然可能掩盖过程错误？
一个会提交代码的 Agent，trace 里至少应该记录哪些状态变化？

Observability：Agent 出问题时要看见哪一步 ​

今天先记住 ​

它在大地图里的位置 ​

它到底是什么 ​

为什么 Agent 里会用到它 ​

怎么判断它有没有用 ​

最近冒出来的词 ​

一个小例子 ​

常见误区 ​

今天自测 ​