Agent 可观测性入门：没有 trace 的 Agent 等于不可运维

传统服务出问题，看日志和指标基本能定位。Agent 出问题，你打开监控面板只看到「成功率 87%」和「平均延迟 4.2 秒」，看不出为什么。

原因很简单：Agent 的执行路径是一棵动态生成的树，而多数团队的埋点还停留在「请求 - 响应」的线性模型。

一、一次 trace 至少要记什么

trace_id
├─ session_id        多轮会话归组
├─ step_index        第几步
├─ llm_call：model / 完整 messages（含 system、tools）
│            输出（含 tool_calls 原样）/ token 数 / 延迟
├─ tool_call：工具名 + 原始参数 / 返回（截断 4KB）
│             错误类型 / 耗时
└─ final_output

重点两个：完整 messages 和 tool_call 的原始参数。90% 的 Agent 问题在这两个字段里有直接答案。

截断策略要注意：工具返回可以截断，模型输入不能。上下文压缩、历史注入这些操作必须留痕，否则永远对不上「模型到底看到了什么」。

二、三个排查场景

答非所问。 看回放里模型的输入。常见根因：检索为空但没报错、工具返回「未找到」被当成肯定回答、上下文压缩把关键信息删了。

工具选错。 看调用分布。高频误选通常不是模型问题，是工具描述有歧义。统计「工具名 → 后续是否报错或被纠正」，能直接定位要改的描述。

越跑越慢、越跑越贵。 按 step_index 聚合 token 和延迟。典型模式是「循环里每步都重读全量历史」，token 随步数平方增长——只看总指标发现不了。

三、会话回放怎么做

理想形态是时间线视图：左边步骤，中间模型输入输出，右边工具详情。不上商业平台的话，最简单三步：

1. 每个 trace 落一份 JSON 到对象存储；
2. 写个内部小页面，输入 trace_id 渲染成时间线；
3. 关键字段支持搜索。

第 3 点最有价值。「失败但没被发现」的会话是质量事故的主要来源，而它们从来不会进入错误日志。

四、两个被低估的指标

• 工具调用冗余率：同参数重复调用同一工具的比例。高说明模型没读懂返回值，或返回格式不友好。
• 人工介入率：用户手动纠正的比例。这是最接近真实满意度的代理指标，比点赞有用得多。

五、从最小开始

不用一上来就上全链路平台。先做三件事就能覆盖大部分收益：所有调用打结构化日志并带 trace_id；一个按 trace_id 回放的时间线页面；每天扫描一遍「失败但声称成功」的会话。

Agent 的可靠性不是靠换更强模型堆出来的，是靠能被看见堆出来的。