Agent 可观测性实战：观测的不是机器，是决策

Agent 越自主，越需要被"看见"。这句话在 2026 年下半年已经快成行业口号了——OpenAI 给 Codex 云环境配审计，Cursor 给 Rollouts 接部署监控，GitHub 给 Copilot 加 OpenTelemetry。但口号归口号，真正动手给 Agent 加可观测性的人会发现：传统的"日志+指标+链路追踪"三件套，到了 Agent 这里几乎不够用。因为你要回答的问题变了：不再是"系统慢在哪"，而是"它为什么这么干"。

这篇是实战指南：Agent 可观测性到底要观测什么、怎么搭、以及三个最常见的坑。核心观点先摆出来：Agent 的可观测性不是日志，是可审计的决策链——你要能回答的不是"发生了什么"，而是"它基于什么信息、做了什么判断、这个判断对不对"。

为什么传统可观测性不够用？

微服务的可观测性回答三个问题：多快（metrics）、哪错了（logs）、请求走哪了（traces）。这套东西假设"代码的行为是确定的"——同样的输入，同样的输出，查的就是性能和异常。

Agent 把这个假设打破了。同样的 prompt 跑两次，工具调用序列可能完全不同；一次"成功"的任务里，可能藏着三次失败的尝试和一次危险的操作（比如它差点删了数据库，只是最后没删）。传统监控看到的是"任务成功，耗时 3 分钟"，而你真正想知道的是：它中间试了什么？为什么选了这条路？有没有做过危险的事？

所以 Agent 可观测性的第一性原理是：记录的不是"系统状态"，而是"决策过程"。每一次工具调用，都要能回答五个问题：想干什么（意图）、看到了什么（输入上下文摘要）、选了哪个工具和参数（决策）、结果是什么（输出摘要）、花了多少（tokens/时间/钱）。这五个问题，就是 Agent 可观测性的最小数据模型。

实战架构：四层，缺一不可

第一层：决策日志（Decision Log）。这是地基。每次 Agent 做"选择"——选工具、定参数、决定重试还是放弃——都记一条结构化日志。关键字段：timestamp、session_id、step_id、intent（自然语言一句话）、tool、args_hash（参数的哈希，全量参数太大）、input_summary、output_summary、tokens、duration_ms。注意不要记全量 prompt 和全量输出，那是成本黑洞；记摘要+哈希，需要深挖时再按哈希去对象存储里取全量。

第二层：轨迹回放（Trajectory Replay）。把一次任务的所有决策按时间轴展开，能像看录像一样回放。这是 debug Agent 的神器——"它为什么在这个节点调了删除？"回放一看：哦，它把"清理临时文件"理解成了"清理数据目录"。没有回放，你只能靠猜。实现要点：每个 step 存"渲染后的 prompt 片段"而不是"prompt 模板"，因为模板里的变量展开后才是 Agent 真正看到的东西。

第三层：护栏事件（Guardrail Events）。单独记录所有"被拦下"的事：权限拒绝、沙盒拦截、人工确认、自动熔断。这一层的数据是安全审计的金矿，也是调优护栏的依据。如果某条护栏一周触发 500 次但全是误报，说明阈值错了；如果某类危险操作从没被拦过，说明有盲区。护栏事件要单独存、单独告警，别和普通日志混在一起。

第四层：成本归因（Cost Attribution）。每个任务、每个用户、每个 Agent，花了多少 tokens、多少钱。2026 年 token 价格战打完，账单依然是 Agent 应用的第一大运营成本。没有成本归因，你就不知道哪个功能在烧钱、哪个用户在薅羊毛。实现很简单：在决策日志里加 tokens 和 model 字段，离线按价格表一算就有。

三个最常见的坑

坑一：记了全量 prompt，三个月后存不起了。一个中型 Agent 应用，一天产生几十 GB 的日志很常见。正确姿势是"分级存储"：结构化决策日志存 90 天（热），全量 prompt/output 存对象存储 30 天（温），超过 30 天的只留哈希和摘要（冷）。需要回放三个月前的任务？大概率你并不需要——真需要的，提前归档。

坑二：只记"做了什么"，不记"为什么"。很多团队的 Agent 日志就是工具调用的流水账：调了 read_file，调了 edit_file，调了 bash。出了问题回头看，完全不知道它为什么选这个文件、为什么用这个参数。强制要求：每个工具调用必须带 intent 字段，让 Agent 自己用一句话说"我想干什么"。多花几个 tokens，debug 时省几小时。

坑三：可观测性和护栏是两套系统。见过最多的架构：日志走 ELK，护栏是硬编码在代码里的 if。结果是护栏拦了什么，日志里看不到；日志里看到危险操作，回头发现护栏根本没覆盖。正确做法是护栏即事件源：每次护栏决策（放行/拦截/转人工）都写一条 guardrail event，和决策日志用同一个 session_id 关联。这样"它想干坏事→被拦下→转人工→人工放行"的完整链条才是可审计的。

最小可行方案：今天就能动手

如果你从零开始，别想着一次建成四层。按这个顺序来：

• 第 1 周：给每次工具调用加结构化日志（intent + tool + args_hash + 摘要 + tokens）。存到你现有的日志系统里就行，别新搭。
• 第 2 周：做一个最简陋的轨迹回放页面：按 session_id 查出所有 steps，按时间列出来，能展开看摘要。丑没关系，能用就行。
• 第 3 周：把护栏决策独立成事件，接一条告警通道（拦截率突增就报警）。
• 第 4 周：加上成本归因，做一张"每个功能烧多少钱"的周报，发给全组看——你会惊讶于大家省钱的积极性。

工具选型：自建还是买？

四层架构听起来很重，自己从零搭要 1-2 个工程师干一个月。2026 年下半年的现实是：大部分层都有现成的工具了，别重复造轮子。

• 决策日志层：LangSmith、Langfuse、Braintrust 都是成熟选择，开源可自托管。选型标准就一个：支不支持"自定义字段"（intent、args_hash 这些）——不支持的，再便宜也别用，因为 Agent 的决策日志和 LLM 调用日志是两回事。
• 轨迹回放层：上面三家都带回放 UI，够用。但注意"渲染后的 prompt"这个需求——很多工具默认只存模板，你要确认它存的是"展开后的完整输入"。这是选型时最容易被销售话术糊弄的点，POC 时亲手验证。
• 护栏事件层：这是最值得自建的一层。因为护栏和你的业务逻辑强相关（什么算"危险操作"，每个业务不一样），买通用工具反而削足适履。自建一个"护栏事件表"（guardrail_events），字段：session_id、rule_id、decision（allow/block/escalate）、reason，一天就能搭起来。
• 成本归因层：别买工具，用 SQL。决策日志里有 tokens 和 model，一张表关联价格表，BI 工具直接出报表。2026 年 token 价格变得快（$2/$10 都快成标准了），价格表做成配置，别硬编码。

真实案例：一次回放救了一周的 debug

讲一个真实的案例（细节脱敏）：某团队的 Agent 负责"每天凌晨同步第三方数据并生成报表"。某天报表数据全错，但任务状态显示"成功"，日志里全是绿的。按传统思路，得把整个 pipeline 重跑一遍猜问题——至少两天。

他们打开轨迹回放，按时间轴看：Agent 在第 7 步调了数据 API，返回是"429 限流"；第 8 步，Agent 的 intent 写的是"API 限流，改用缓存数据继续"；第 9 步，它从一个三天前的缓存文件里读了数据，生成了"成功"的报表。问题一目了然：Agent 在"限流"时选择了"降级"，但降级策略是错的——用了过期缓存，而不是重试或告警。

修复只用了 10 分钟：在 AGENTS.md 里加一条铁律——"第三方 API 限流时，必须指数退避重试 3 次，失败则告警并标记任务失败，不许用缓存数据冒充"。没有回放，这个 bug 要藏几个月；有了回放，10 分钟定位。这个案例说明了决策日志里"intent 字段"的价值——如果没有那句"改用缓存数据继续"，他们到现在还在猜。

成熟度模型：你在第几级？

最后给一个自检框架，对照看看你的 Agent 应用在第几级：

• L1 裸奔：只有模型厂商的账单，任务成功失败靠用户反馈发现。特征：出问题先被用户骂，再去翻聊天记录。
• L2 日志：有工具调用的流水账，但没有 intent、没有回放。特征：能查到"调了什么"，查不到"为什么"。
• L3 可回放：有决策日志+轨迹回放，能复盘单次任务。特征：出问题 1 小时内能定位到"哪一步的哪个决策错了"。
• L4 可审计：护栏事件独立，危险操作全链路可追溯。特征：安全团队问"它上周三干了什么"，你 5 分钟能拿出完整证据链。
• L5 可运营：成本归因到功能/用户，有"烧钱排行榜"，有自动熔断。特征：每周一看报表就知道"哪个功能在亏钱"，自动止损。

大多数团队在 L2，目标是年底到 L4。别想着一步到 L5——可观测性是爬楼梯，不是坐电梯。每一级的投入产出比都是正的，爬一级赚一级。

延伸：OpenTelemetry 语义约定怎么用

GitHub 给 Copilot 接 OpenTelemetry 不是偶然——2026 年下半年，OTel 正在成为 Agent 可观测性的"普通话"。但直接用 OTel 的默认语义（http.server 那些）是不够的，因为 Agent 的"span"不是 HTTP 请求，是"决策"。

实操建议：用 OTel 的"自定义 span"给四层架构建模——每个工具调用是一个 span，属性带 intent、tool、args_hash、tokens；整条任务链是一个 trace，属性带 user_id、task_type、total_cost。护栏事件用 OTel 的"event"机制挂在对应的 span 上。这样做的好处：你的 Agent 可观测性直接接入现有的 OTel 生态（Grafana、Datadog 全都认），不用重复造轮子。记住：别自己发明可观测性协议，除非你比 OTel 更懂。

一句话总结：Agent 的可观测性，观测的不是机器，是"决策"。传统监控问"系统怎么了"，Agent 监控问"它为什么这么想"。把决策链记下来、能回放、能审计、能算账，你就有了在 2026 年下半场运营 Agent 应用的入场券。记住，可信度的竞争已经开场，而可信度的地基，就是"每一件事都说得清"。