Agent 卡在第三步，怎么查，一次请求的可观测性

Agent 卡在第三步，怎么查，一次请求的可观测性

用户报障，说机器人答得很奇怪。你去翻日志，只看到一行请求进来、一行响应出去，中间调了哪些工具、喂给模型什么上下文、token 花在哪里，一概不知。于是开始复现，复现不出来，再猜，猜错两轮，一天过去了。

这类场景在有 Agent 的系统里特别常见，因为一次请求内部发生了太多事，模型调了两轮，工具调了五次，还夹着一次检索。传统的接口日志按请求记一条，粒度完全不够。

给一次请求建一棵树

做法是给每次请求分配一个 traceId，请求内部每一次模型调用、每一次工具调用，都作为子节点记录，带自己的 spanId 和父节点。这样一次请求就是一棵树，能看清耗时和成本落在哪个分支。

三个字段必须有。输入，包括完整的提示词和参数，脱敏后落盘。输出，模型的原始返回或者工具的结果，长内容可截断但要留摘要和引用。耗时和 token，模型调用记输入输出 token，工具调用记执行时长和是否重试。

成本要能归因

总账单涨了，得知道钱花在哪个功能、哪个用户、哪类问题上。traceId 之外，再带上用户 ID、会话 ID、功能标签，账单就能按维度切开。没有这层归因，成本优化只能靠猜，而猜错的成本是整月的账单。

有个细节值得单独记，缓存命中和未命中的记录。提示词缓存能省一大笔，但前提是知道哪些请求命中了，哪些每次都全量计费。不记录就永远不知道缓存在不在生效。

回放比日志更有用

日志是给人看的，回放是给系统重跑的。把一次请求的输入、上下文、工具返回按顺序存下来，改完提示词之后可以把这批输入重跑一遍，对比输出差异。评测集的样本从哪来，答案就在这里，从回放库里抽。

回放还有个诊断价值，工具结果没变、提示词没变、模型版本没变，输出却变了的那些请求，往往暴露了温度或者采样参数的隐性问题。

别把敏感数据直接写日志

可观测性的第一版最容易犯的错是全量落盘。用户的手机号、地址、身份证号，工具返回的完整订单信息，全进了日志系统。日志的访问权限通常比业务库松，一旦泄漏就是事故。

脱敏放在写入侧，别放在查询侧。写入时就把手机号打码、身份证打码、姓名保留姓，原始值加密存到单独的受限表，日志里只留引用。查问题真要原文，凭审批去取。

留存期也要定。诊断用的明细留两周到一个月，聚合指标留更久。明细长期保留既是成本也是风险。

采样怎么定

全量记录很贵，模型调用的完整输入输出动辄几千 token。常见的做法是错误全记，成功的按比例采样，比如百分之十。慢请求和贵请求无论成败都记全，这两类最有诊断价值。

采样要用 traceId 做一致性哈希，别随机丢子节点。一次请求的模型调用被记下，工具调用被丢了，那棵树就残了。

结合系列

评测篇的样本来源，在这里有了具体落点，回放库直接喂评测集。参数校验篇的三层校验，每一层的拒绝都该在 trace 里留标记，否则你只知道失败率高，不知道是哪一层拦的。执行循环篇的重试上限，在 trace 上表现为同一工具的多个 span，一眼能看出是不是在原地打转。会话隔离篇的身份，也要进 trace，否则查问题时连是哪个用户在报障都定位不了。