Agent执行路径动态生成，传统日志无法追踪。可观测性设计需覆盖Trace链路、决策日志与Token消耗三层次，配合分级采样策略，让PM在Agent出错时快速定位并系统性修复，避免黑盒成为技术债。

你的Agent上线了。

用户反馈说“结果不对”，你打开后台，看到一条冷冰冰的错误日志：tool_call_failed。

然后呢？

不知道它在第几步出的问题。不知道它调用了哪个工具、传了什么参数。不知道它“以为自己在做什么”。你只能靠猜。

这就是没有可观测性的Agent——它在运行，但对你来说是个黑盒。

可观测性不是”加日志”这么简单

传统软件的可观测性三件套：日志（Logs）、指标（Metrics）、追踪（Traces）。

Agent系统同样需要这三件套，但难度更高：

传统软件的执行路径是固定的。你写了什么代码，它就跑什么路径，日志只需要记录关键节点。

Agent的执行路径是动态生成的。同一个用户请求，昨天Agent选择了工具A，今天它可能选择工具B再调用工具C，中间还自己生成了一段推理。你根本不知道它”会走哪条路”。

这带来一个根本性挑战：你无法提前埋点，只能全程追踪。

PM需要理解：Agent可观测性的核心目标不是”记录发生了什么”，而是“理解Agent为什么做了这个决定”。

第一维度：Trace链路——把每次执行都”录像”

Trace（链路追踪）是Agent可观测性最基础的一层。

一次完整的Agent执行，通常包含：

• 用户输入（原始prompt）
• Agent的思考过程（内部推理，如果有CoT的话）
• 工具调用序列（调用了哪些工具，顺序是什么）
• 每次工具调用的入参和出参
• 最终的输出结果

这些信息串联起来，就是一条执行链路（Trace）。

好的Trace设计应该满足：

1. 每个步骤有唯一ID，可以独立查询

不能只记录“这次运行失败了”。要能定位到“第3步工具调用，参数里的日期格式错了”。

2. 时间戳精确到毫秒

哪个步骤耗时最长？是模型推理慢，还是外部API超时？时间分布是排查性能问题的关键。

3. 跨会话可关联

同一个用户的多轮对话，Agent有没有正确使用上下文？跨会话的Trace关联能帮你发现记忆系统的问题（这一点在上周写记忆系统那篇里提过）。

PM在设计需求时，Trace存储方案要提前确认：存哪里，保留多久，谁有权限查。这不是技术细节，是数据治理问题。

第二维度：决策日志——理解Agent的”内心戏”

Trace记录了“做了什么”，决策日志记录的是“为什么这么做”。

这是Agent可观测性和传统软件最不一样的地方。

一个设计良好的Agent，每次做关键决策时应该能输出：

• 选择了哪个工具，为什么不选其他工具
• 对当前任务的理解是什么（避免Agent”理解偏了”但你不知道）
• 遇到不确定时，如何处理（是猜测、是请求澄清、还是直接放弃）

实操层面，有两种常见方案：

方案一：在System Prompt里要求Agent输出结构化推理

让Agent在每次工具调用前，先输出一段JSON：{“reasoning”: “用户要查最近7天数据，我选择date_range_query工具”， “confidence”: 0.85}

好处是成本低、易实现；缺点是依赖模型“听话”，复杂场景下可能不稳定。

方案二：使用支持原生Chain-of-Thought的框架

LangSmith、Langfuse、Arize Phoenix等工具可以在不修改业务逻辑的情况下，自动捕获Agent的推理过程。

PM需要推动研发选型时把可观测性纳入考量标准，而不是上线后再“接入监控”。事后接往往比事前设计贵3倍。

第三维度：Token消耗可视化——ROI的起点

很多PM不关心Token，觉得那是算钱的事，让财务管就行。

这个思路会让你在后期很被动。

Token消耗是Agent系统最直接的成本指标，也是发现问题的早期信号：

Token异常飙升 = 某个地方出问题了

常见场景：

• Agent陷入循环（同一个工具调用了20次）
• Prompt注入了太多无用的历史记录（上下文管理失控）
• 用户输入了异常长的文本，触发了某个兜底逻辑

如果你没有Token监控，这些问题会悄悄消耗你的预算，直到月底账单出来才发现。

Token分布告诉你哪里最”贵”

一次完整的Agent执行里，哪个步骤消耗Token最多？

• 如果是初始推理：可能System Prompt写得太长
• 如果是工具调用结果处理：返回数据可能需要压缩
• 如果是多轮对话积累：上下文截断策略需要优化

这些优化每一个都能降低10%-40%的成本。对于规模化部署的企业Agent，这是非常实在的数字。

PM应该要求研发提供按功能/用户/时段分层的Token消耗报表，而不只是一个总量数字。

一个容易被忽视的设计点：可观测性的”粒度控制”

有人会说：那就全部都记录呗，什么都存下来。

不行，原因有三：

1. 成本：每次Agent执行都完整存储推理过程，存储费用可能超过计算费用
2. 隐私：用户的输入和Agent的中间推理里可能含有敏感信息，全量存储带来合规风险
3. 噪音：日志太多，真正出问题时反而找不到关键信息

好的可观测性设计需要分级采样策略：

• 正常执行：只记录摘要级别的Trace（开始、结束、关键节点）
• 异常执行：触发全量记录（失败、超时、用户投诉）
• 特定用户/场景：按需全量记录（用于调试或A/B测试分析）

这个策略应该由PM在PRD里定义清楚，而不是让研发“随便存一下”。

PM的行动清单

如果你现在正在主导一个Agent产品，以下是你应该推动的事：

立项阶段

• 可观测性方案和业务功能同步设计，不是事后补
• 明确Trace保留策略（时长、粒度、权限）
• 选型时把”监控接入难度”列为评估维度

开发阶段

• 要求每个工具调用有唯一TraceID
• 要求Agent关键决策点有结构化输出
• Token消耗按功能模块分别统计

上线后

• 建立基线：正常情况下每次执行的Token消耗范围、耗时范围
• 设置异常告警：Token突增50%或执行时间超过阈值
• 定期review失败Trace：每周看一次，主动发现问题

最后一句话

Agent可观测性解决的不是”Agent出错了怎么办”，而是“Agent出错了你能不能发现、能不能快速定位、能不能系统性修复”。

黑盒Agent是技术债，迟早要还。现在设计进去，比出了问题再补，便宜得多。