20 · 可观测性

看清 Agent 的每一步在想什么

📚 系列导航：这是《Agent 开发进阶》的第 20 篇（共 24 篇）。上一篇你给 agent 立了评测考卷，这一篇装上行车记录仪——tracing，翻车能定位到具体那一轮。下一篇：21 · 安全护栏。

第一次线上事故大概率是这样：用户甩来一句"你们这 agent 答得离谱"，后台只有一条最终回复——它查了什么、调了哪个工具、每轮在想什么，一概没有。只能重跑祈祷复现。我干过，猜了一下午。从那以后规矩定死：没有 trace 的 agent 不许上线。这一篇只干一件事：接上全链路 tracing，把"靠猜复现"变成"按图索骥"。

看完这一篇，你会拿到：

• 一份可直接落库的最小 trace schema
• 一套观测工具四维选型打分法
• 一条从投诉到定位出错轮的归因流程
• 一个"token 花在哪"的成本看板切面清单

---

01 最小 trace schema：没有观测就没有调试

agent 和普通服务的区别：执行路径是模型现场决定的。打个比方，普通服务的日志像固定线路的公交记录，agent 的 trace 是行车记录仪——路线是司机临场选的，不录下来就说不清它为什么拐错弯。做法：每轮循环记一行结构化日志，五要素——输入、模型输出、工具调用与结果、token 与延迟、错误。

{"trace_id": "t-0417", "turn": 3, "input": "退款政策咨询",
 "model_output": "调用 search_kb", "tool_result": "命中 0 条",
 "tokens": {"in": 2100, "out": 85}, "latency_ms": 1240, "error": null}

预期：每轮一行 JSON，按 trace_id 聚合即完整轨迹。

💡 一句话总结：trace 是上线前置条件不是锦上添花——五要素一行 JSON 先记下来。

02 工具选型：别为观测搭观测

LangSmith、Langfuse 这类平台要不要上？按四维比：数据归属（trace 含业务数据，能否私有化部署）、查询能力（能否按会话、工具、错误切片）、评测联动（badcase 能否直接进第 19 篇的评测集）、接入成本（2026 上半年格局，以官方为准）。我的判断：日请求量没过千，01 节的日志加个检索脚本就够——先养成记录习惯。

💡 一句话总结：四维选型：数据归属、查询、评测联动、接入成本——起步自建日志够用。

03 归因流程：从投诉到那一轮

固定成流水线：投诉 → 调出会话 trace → 逐轮回放定位出错轮 → 判定哪一环（检索、工具还是生成）→ badcase 入池喂回评测集。关键在逐轮回放：错误往往前几轮就埋下——第 3 轮检索命中 0 条、第 4 轮开始瞎编，只看第 4 轮会误判成"幻觉"。有 trace，五步十分钟；没有，复现就是抽奖。

💡 一句话总结：归因是流水线不是破案——调 trace、定位轮、判环节、入池，固定动作。

04 成本看板：token 花在哪了

token 字段聚合起来就是成本看板，三个切面：按轮次（哪几轮最贵——通常是历史滚存）、按工具（谁的返回最啰嗦）、按版本（这次改动让成本变了多少）。看板不只抓浪费，还抓退化：我经历过一次模型升级，成功率纹丝不动、成本翻了 3 倍——轨迹变啰嗦了，是成本曲线先报的警。

💡 一句话总结：按轮次、工具、版本三切面聚合——看板抓浪费，也抓成功率看不见的退化。

05 日志脱敏：trace 里的合规炸弹

trace 原样记下用户输入，手机号、邮箱全在里面。规矩一条：脱敏在写入前，不在查询前——落盘即脱敏。做法：写入管道加正则打码，字段白名单化，digest 只存摘要。我在自己的 trace 里见过成排手机号，后背是凉的——这种事故代价比任何 bug 都大。

💡 一句话总结：脱敏规则和 trace 同一天上线——写入前打码，合规炸弹别自己埋。

06 动手：完成一次真实 badcase 归因

任务：① 给你的 agent 每轮写一行 01 节格式的 trace；② 挑一个真实答错的 case（没有就批量跑任务抓一个）；③ 按 03 节流程逐轮回放，写归因报告。

验收标准：归因报告写明"第几轮、哪个环节、什么决策错了"，附 trace 片段和进评测集的样本。

两种结果都正常：定位到具体轮——修复后跑评测回归，闭环完成；定位不了——多半是 schema 缺字段（如工具入参），补上重跑，观测体系就是这样迭代出来的。

07 小结

你现在应该能：接上五要素 trace、按四维做观测选型、把一次投诉归因到具体轮、搭出带脱敏的成本看板。

看得见之后还要锁得住——21 · 安全护栏：坏指令正藏在 agent 读取的内容里。

---

📎 实战案例

某团队线上出问题只有最终答案，复现猜了约 4 小时。接入 tracing 后，下一个 badcase 十分钟定位到出错轮——第 3 轮检索命中 0 条，修的是检索词而不是模型。

踩坑

• 第一次线上事故没有过程日志，我复现猜了 4 个小时——trace 从此是上线门槛。
• 日志里躺着成排用户手机号——脱敏必须和 trace 同一天上线，写入前打码。
• 一次模型升级成功率没变、成本翻了 3 倍——是成本看板先报警，轨迹指标必须进看板。