14. 怎样记录一条可以重放的 Agent 轨迹

Codex 的标准输出区分命令开始、命令完成、Agent 消息和用量完成；Kimi 的消息链区分工具请求、工具结果和最终内容。这些信息如果被拼成一段终端文本，仍然很难回答某个结果来自哪次模型决策。

三层标识缺一不可

并行事件还需要单调递增的 sequence。时间戳不能单独承担排序：不同线程和主机的时钟可能存在偏差，多个事件也可能具有相同时间精度。

统一事件而不是统一成文本

轨迹至少包含：

• 上下文组装完成。
• 模型请求开始与完成。
• 工具调用提出、校验、授权、开始与完成。
• 用户批准或拒绝。
• 状态转移。
• 用量与终止原因。

事件正文可以因模型和工具不同而变化，外层信封保持相同字段。这样查询系统才能跨产品统计模型轮次、工具失败和权限拒绝。

OpenTelemetry 的生成式 AI 语义约定使用 gen_ai.operation.name 等属性描述模型和 Agent 操作；其 Agent 示例把 invoke_agent 作为父 Span，把模型调用和工具执行作为子 Span。Span 是一次有开始、结束和属性的可观测操作。OpenTelemetry GenAI Observability

可重放分为两个等级

执行重放具有风险。外部发送、写入和创建操作不能默认再次执行，应替换为模拟工具或要求新的授权。

轨迹还要记录版本

同一输入在模型版本、系统 Prompt、工具 Schema 或项目规则变化后可能产生不同结果。轨迹元数据至少保存：

• 模型与客户端版本。
• Prompt 模板版本。
• 工具 Schema 版本。
• 权限策略版本。
• 项目状态引用。

否则“重放结果不同”无法定位是模型变化还是运行时变化。

敏感内容与可调试性之间的边界

完整轨迹可能包含文件正文、命令输出和认证头。采集时就要分类：

先记录秘密再定期清理，会扩大泄漏窗口。脱敏应尽量发生在事件进入持久化系统之前。

一条轨迹能够重放，意味着我们可以从事件恢复因果关系，而不是仅仅保存了一份看起来完整的聊天记录。

事件信封需要稳定字段

每个事件至少包含版本、类型、轨迹标识、父事件标识、顺序号、发生时间、写入时间、主体和负载引用。发生时间描述动作何时出现，写入时间描述日志何时持久化，两者差异可以暴露队列延迟和乱序。

事件格式升级时，读取器应支持旧版本或执行明确迁移。直接修改历史事件会破坏审计；派生字段可以重新计算，但原始事件保持只追加。

重放还要控制非确定性

模型采样、当前时间、随机数、网络响应和文件状态都会改变结果。只读重放使用保存结果替代这些依赖；执行重放则记录新的环境快照，并与原轨迹形成分支关系。

重放结果不应覆盖原轨迹。它要生成新的 trace_id，引用来源轨迹和重放模式，使比较系统能够逐事件显示相同、缺失、新增和改变的内容。

决定重放与副作用重放不同

决定重放把保存的工具结果重新给模型，观察下一步；副作用重放重新执行工具。前者适合调试，后者需要隔离快照、模拟器或幂等。生产轨迹默认不能再次发送邮件、付款或删除。

Span 与领域事件互补

OpenTelemetry 的 Span 表示有开始和结束的操作，适合模型和工具耗时；领域事件表示授权拒绝、结果采纳等状态变化。两者用轨迹标识关联。OpenTelemetry 2026 年的 GenAI 示例记录模型、Token、工具和结果，也提醒完整内容是可选高敏感数据。OpenTelemetry：Inside the LLM Call

报告说明达到哪一级及缺失变量。任一失败轨迹都应回答模型看见什么、工具是什么、参数来自哪里、谁授权、动作是否发生、结果如何回填以及为何停止。