导语

当 Agent 从 Demo 走向生产环境，团队最常遇到的困境不是“它能不能跑”，而是“它为什么这样跑”。一次失败的任务背后，可能藏着一次错误的工具选择、一段被截断的上下文、一次超时的外部 API 调用，或者一轮本可以避免的自我循环。传统监控能告诉你服务是否存活、接口是否返回 200，却很难回答一个更关键的问题：Agent 在出错之前，究竟“想”了什么、做了什么、依据是什么。

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

传统可观测性建立在三大支柱之上：日志（Logs）、指标（Metrics）、链路追踪（Traces）。这套体系针对的是确定性系统——同样的输入应当产生同样的输出，异常可以被归类为有限的错误码。

Agent 打破了这些前提：

• 执行路径不确定：同一个用户请求，Agent 可能走不同的推理路径、调用不同的工具组合。
• 中间状态语义化：一次 LLM 调用的输入输出是自然语言，不是结构化字段，出错时很难用阈值告警捕获。
• 失败是渐进的：Agent 往往不是“突然崩溃”，而是在多步推理中逐步偏离目标，最终给出一个看似合理但错误的答案。
• 成本与延迟耦合：token 消耗、工具调用次数、重试轮次本身就是需要观测的运行指标。

因此，Agent 可观测性的目标不只是“发现故障”，而是还原一次任务执行的完整决策轨迹，让工程师能够复盘 Agent 的每一步判断。

看清“脑子里”的每一步：需要采集什么

要复盘 Agent 的决策过程，观测数据需要覆盖以下几个层次。以下为通用设计要点，具体字段需结合所用框架与业务场景确定。

1. 会话与任务层

记录一次任务的起点：用户输入、会话 ID、触发的 Agent 配置（模型、系统提示词版本、可用工具集）。这一层是复盘的锚点，缺少它，后续所有步骤都失去上下文。

2. 推理步骤层

这是 Agent 可观测性的核心。每一步应尽量记录：

• 当前步骤的输入上下文（经过裁剪或摘要后的内容）；
• 模型的原始输出，包括推理内容与工具调用意图；
• 该步骤的耗时与 token 用量；
• 步骤序号与父子关系，用于还原执行树。

3. 工具调用层

工具是 Agent 与外部世界交互的边界，也是故障高发区。需要记录工具名称、入参、返回值、状态码、耗时与重试情况。工具调用的失败往往不会直接抛异常，而是以“返回了一段错误信息”的形式被模型继续消费，因此必须显式标记。

4. 状态与记忆层

如果 Agent 使用了记忆、向量检索或外部知识库，应记录检索命中的内容与相似度，帮助判断“它是不是基于错误的上下文做了正确推理”。

5. 结果与评估层

最终输出、是否达成目标、人工或自动评估结论。这一层把技术轨迹与业务效果连接起来。

落地时的几个关键设计

用 Trace 组织，而不是堆日志

Agent 的一次执行天然是一棵树：任务 → 多个推理步骤 → 每步下的工具调用。用分布式追踪的 Span 模型来组织这些数据，比平铺日志更利于定位“哪一步开始偏离”。每一步作为子 Span，工具调用作为更深一层的 Span，父子关系即执行顺序。

保留原始输入输出，但注意脱敏与成本

复盘价值最高的往往是模型的原始输出。但原始数据涉及用户隐私、密钥、内部信息，需要在采集侧做脱敏；同时全量保留会带来存储成本，可考虑采样策略与分级保留。

把“失败”定义清楚

Agent 的失败不只有异常。至少应区分：工具调用失败、超时、达到最大步数、输出未通过校验、人工判定不达标。不同失败类型对应不同的排查路径，混在一起会让告警失去意义。

让轨迹可回放

可观测性的终点是复现。理想状态下，给定一条 Trace，工程师能重放当时的上下文与工具返回，验证“如果换一个提示词或换一个工具，结果是否会不同”。这要求记录足够完整的输入快照，而不仅是摘要。

趋势判断

依据现有素材判断，Agent 可观测性正在从“附加能力”变成“基础设施”：

• 评测与观测融合：离线评测集与线上 Trace 将共享同一套数据结构，线上失败样本可以直接沉淀为评测用例。
• 以轨迹为中心的工具链：围绕 Span 的查看、对比、回放会成为 Agent 开发平台的标配能力，而非自建脚本。
• 成本与质量同屏：token、延迟、工具调用次数与任务成功率将放在同一视图下权衡，因为 Agent 的“好”本身就是多目标的。
• 标准化仍在早期：Agent 轨迹的字段规范尚未统一，团队在自建时应注意抽象出与具体框架解耦的数据模型，避免被单一 SDK 绑定。

结论

Agent 出错时，最有价值的不是一句“任务失败”，而是一条能看清每一步推理与工具调用的轨迹。构建 Agent 可观测性，本质上是在为不确定的执行过程建立可复盘的证据链：以 Trace 组织数据，覆盖会话、推理、工具、状态与结果五个层次，明确失败分类，并保证轨迹可回放。做到这些，团队才能在 Agent “想错”的那一刻及时看见，而不是在结果出错后被动猜测。

生成标记：本文由 ITPUB 文章生成平台基于已选素材整理生成。