跳到主要内容

回放与调试

核对日期：2026-05-09。

1. 定义与边界​

回放与调试是用线上或测试 trace 的输入、状态、Prompt、模型版本、工具结果和事件序列复现 Agent 行为的能力。它不是简单查看日志；日志回答“发生了什么”，回放要回答“为什么发生、换版本会怎样、能否安全重现”。

2. 为什么重要​

Agent 失败通常不是单点错误，而是上下文选择、模型推理、工具结果、Prompt 和状态机共同作用。没有回放能力，团队只能靠截图和用户描述排查，无法做回归验证和事故复盘。

3. 核心机制​

trace 事件结构：

{
  "trace_id": "trace_01",
  "run_id": "run_01",
  "span_id": "span_model_2",
  "span_type": "model_call",
  "parent_span_id": "span_step_4",
  "attributes": {
    "agent.version": "1.8.0",
    "prompt.version": "2026-05-09.3",
    "gen_ai.request.model": "gpt-x",
    "tool.names": ["crm.lookup"]
  },
  "input_ref": "object://secure/inputs/span_model_2.json",
  "output_ref": "object://secure/outputs/span_model_2.json",
  "started_at": "2026-05-09T10:00:00Z",
  "ended_at": "2026-05-09T10:00:05Z"
}

回放模式：

模式用途副作用
完全 mock 回放复现原始轨迹不调用真实模型和工具。
模型重跑 + 工具 mock比较模型或 Prompt 变化禁止真实副作用。
工具重查 + 模型固定验证数据源变化只允许读工具。
沙箱端到端staging 复现使用隔离资源。

4. 架构模式​

5. 工程实现​

回放 runner：

def replay(fixture, mode):
    ctx = ReplayContext(
        run_id=fixture.run_id,
        prompt_version=fixture.prompt_version,
        tool_mode=mode.tool_mode,
        model_mode=mode.model_mode,
        side_effects=False,
    )
    result = agent.run(ctx, fixture.initial_input)
    return diff_trace(fixture.expected_trace, result.trace)

差异比较不应只比较最终文本，还要比较：

  • 工具调用顺序和参数。
  • 输出 schema。
  • 安全拒答。
  • 成本和延迟。
  • 状态机跃迁。

6. 生产实践​

  • 每个 run 记录 trace_id，并在用户问题、错误告警、成本账单中可关联。
  • 高风险工具默认不允许在回放中真实执行。
  • trace 原文按敏感级别分层存储，普通日志只放摘要和引用。
  • 线上事故 trace 脱敏后沉淀为回归用例。
  • 模型非确定性导致输出文本不同是正常的，评测应关注业务断言。

7. 常见反模式​

  • 只有 printf 日志，没有结构化 trace 和 span。
  • 回放时调用真实发信、付款、删除工具。
  • 不记录 Prompt 版本和工具 schema，导致无法复现。
  • 只保存最终答案，忽略中间工具返回。
  • 把敏感 trace 直接提交到 Git 仓库。

8. 评测方法​

  • Golden trace 回归：关键线上 case 在新版本中通过断言。
  • 差异报告：Prompt 或模型升级前后工具调用和成本差异。
  • 脱敏验证：fixture 中没有明文 PII、密钥和访问 token。
  • 可恢复性：从任一 checkpoint 继续执行能得到合法状态。

9. 安全与治理​

  • trace 访问需要按租户、环境、数据级别授权。
  • 回放环境默认禁用副作用工具，必须显式白名单。
  • 对用户数据回放要满足数据保留和删除要求。
  • 安全事件 trace 单独标记，避免被普通训练或评测流程误用。

10. 权威资料​

11. 二次精修：可回放证据包​

可回放不是保存日志，而是保存足够重建一次决策的输入、版本和环境。

{
  "replay_case_id": "replay_20260509_001",
  "source_trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "run_id": "run_123",
  "agent_version": "refund_agent@1.8.2",
  "prompt_versions": ["refund.system@2026-05-09.3"],
  "model": "gpt-5",
  "tool_versions": {"search_policy": "2.1.0", "create_refund_ticket": "1.4.0"},
  "input_fixture_ref": "blob://fixtures/replay_001/input.json",
  "tool_fixtures_ref": "blob://fixtures/replay_001/tools.json",
  "expected_outcome": "ask_human_approval",
  "redaction": "pii_v3"
}
证据必要性缺失后果
用户输入快照复现上下文无法判断模型是否误解
Prompt/model/tool 版本复现决策环境新版本覆盖旧行为
工具请求与响应定位外部依赖错把工具问题当模型问题
状态快照恢复中间步骤只能整单重跑
成本与延迟事件解释性能事故无法定位成本飙升
安全策略版本判断是否应拦截规则变化导致误判

12. 回放模式​

调试时先回答四个问题：输入是否正确、状态是否正确、工具是否正确、模型是否按约束执行。不要一上来改 prompt，否则可能掩盖真实的状态或工具缺陷。

13. 评测与安全边界​

  • 回放集要覆盖成功、失败、超时、人工审批、工具异常、注入攻击和高成本样本。
  • 回放结果应比较 final answer、tool sequence、关键状态迁移和安全决策，而不只比较文本相似度。
  • 线上 trace 进入回放库前必须脱敏，且要记录脱敏版本；无法脱敏的样本只能在受控环境调试。
  • 副作用工具回放默认禁用真实执行，必须使用 fixture、sandbox 或只读 shadow。
  • 指标：Replay Reproducibility、Trajectory Delta、Tool Fixture Coverage、PII Redaction Failure、Debug Time to Root Cause。

14. 补充权威资料​

15. 主控验收清单​

  • 回放证据包是否包含输入、状态、prompt、模型、工具和策略版本。
  • 是否默认禁用真实副作用工具。
  • 是否对回放样本脱敏并记录脱敏版本。
  • 是否比较最终结果、工具序列和关键状态迁移。
  • 是否把无法复现的样本标记原因并补观测字段。
  • 是否把事故回放样本纳入回归集。