Agent 的 trace 怎么做？出了问题怎么定位是哪一步错的？

结构：一次完整运行是一条 trace，里面按步骤嵌套 span——外层是这次 Agent 运行，里面每一步是一次模型调用 span，模型调用下面挂它触发的工具执行 span。截至 2026-08，OpenTelemetry 的 GenAI 语义约定（v1.41）已经定义了 agent / workflow / tool / model 这几类 span 以及耗时和 token 指标，嵌套结构就是 invoke_agent → chat → execute_tool，对齐它可以少走弯路（注意多数属性仍是实验性的，且内容捕获默认关闭）。

每步至少记：步号、模型与版本、提示词/harness 版本号、工具名、参数摘要、结果长度、耗时、输入输出 token（含缓存命中）、终止原因、护栏是否触发、本步成本。

定位顺序：先看终止原因（正常结束 / 步数上限 / 预算熔断 / 工具熔断），再看轨迹形态（选错工具、参数填错、工具返回空、重复调用、上下文超限），最后才去看具体某一步的请求体。

补四层。

1. 终止原因是性价比最高的一个字段。 它的分布就是系统健康度看板：正常终止占比下滑、步数上限触发率上升，通常意味着任务变难或某次提示词改动引入了退化——这个信号比用户投诉早得多。加上按意图分组，还能立刻看出是哪类请求出了问题。所以我会把它做成默认告警项，而不是排障时才去查。

2. 定位分四层，从便宜到贵。 ① 终止原因分布（秒级，覆盖大部分归因）；② 轨迹形态分类（看动作序列的模式，不看文本）；③ 单步请求体（这一层要能一键拿到最终发出去的 payload，包括系统提示、工具定义、完整历史——很多框架在这里不透明，是选型时就该验的，见 Q3-17）；④ 离线重放。绝大多数问题在前两层就能定位，直接从第三层开始读全文是最费时的做法。

3. 重放是 Agent 排障的核心能力。 保存完整的 messages 序列和每次工具的原始返回，就能做两种重放：纯回放（把已发生的轨迹重新渲染出来给人看，用于复盘）和带录制的重跑（用录下来的工具返回重新跑模型，这样能验证"改了提示词之后同样的输入会不会走对"）。有了后者，一个偶发问题就能变成回归集里的一条固定用例——这是把不可复现问题转化成可管理资产的唯一办法。

4. 内容捕获要分级，别一刀切。 全量存提示词和工具结果，成本和隐私风险都很高（客服场景里工具返回可能全是个人信息）。我的做法：正常轨迹只存结构化元数据 + 内容摘要/哈希；异常轨迹（失败、触发护栏、超预算）全量捕获；敏感字段脱敏；设保留期；大体量的工具结果存指针而不是正文。这样既能查问题，又不至于把 trace 存储做成第二个数据仓库。

5. 顺带解决成本归因。 只要 token 按步骤、工具、意图、用户打了标签，"钱花在哪"就是一次查询的事——这正是 Q3-02 那类成本突涨问题能在一天内定位的前提。没有这层标签，成本分析只能靠猜。