《AI Agent 技术原理与架构·模型、推理与能力边界》11.2 Record/Replay:记录什么、重放什么

Agent 出错时,团队最想知道的是“它当时看到了什么、做了什么”。记录与回放把一次运行拆成请求、模型、检索、工具、输出五类事件,用摘要逐步骤比对。本节用最小事件集实验演示完整性检查、首个差异定位和回放状态,并讨论隐私、副作用隔离与回归测试的边界。

以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。

Agent 出错时,日志里通常只有一句“任务失败”。团队想知道:模型看到了哪段上下文、检索返回了什么、工具调用参数是什么、执行结果是什么。没有这些,排查只能靠猜;有了这些,才能把一次失败变成可重演的案例。

记录与回放(record/replay)就是为这件事设计的:运行时记录关键事件,事后按相同顺序重放,逐步比对差异。它不是“把日志存下来”那么简单,关键在于记录什么、记录多细、回放时哪些东西可以重算、哪些必须固定。

最小事件集

一个 Agent 请求至少包含五类事件:

事件内容作用
request用户输入、系统提示、参数确定起点
model模型版本、采样参数、输出复现生成
retrieval查询、索引版本、返回片段复现证据
tool工具名、参数、返回、状态复现动作
output最终答案、引用、状态复现结果

这五类构成“最小可解释集”。少任何一类,回放都会缺一块:没有 retrieval,不知道模型基于什么回答;没有 tool,不知道动作是否执行;没有 model,无法判断是提示问题还是模型变化。

事件之间要能对齐。最简单的方式是给每个事件一个步骤号,按顺序排列;复杂系统可以用 trace ID + span ID,把并行的检索和工具调用组织成树。

摘要还是全文

记录全文最忠实,但成本高、隐私风险大。记录摘要(哈希)便宜,但只能判断“是否相同”,无法还原内容。

实际系统通常分层:

层内容保留期
摘要哈希、长度、版本长期
结构化参数、状态、引用 ID中期
全文提示、检索片段、工具返回短期/脱敏

摘要用于回归比对,结构化用于排障,全文用于深度复现。三层按需保留,而不是全部长期保存。涉及个人信息的内容应该在写入前脱敏,而不是事后删除。

最小实验:完整性、首个差异与状态

下面的实验定义五类必需事件,检查记录是否完整,逐步骤比对录制与实时事件,并报告首个差异位置。

# file: agp_lab/record_replay.py | write
# tier: 3
# verify: python3 -m unittest tests.test_record_replay
"""Record/Replay:记录最小事件集,按步骤比对重放。"""
from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class Event:
    step: int
    kind: str
    digest: str


REQUIRED = ("request", "model", "retrieval", "tool", "output")


def completeness(events: list[Event]) -> dict[str, bool]:
    present = {event.kind for event in events}
    return {kind: kind in present for kind in REQUIRED}


def first_mismatch(recorded: list[Event], live: list[Event]) -> int | None:
    for index, (expected, actual) in enumerate(zip(recorded, live)):
        if expected != actual:
            return index
    if len(recorded) != len(live):
        return min(len(recorded), len(live))
    return None


def replay_status(recorded: list[Event], live: list[Event]) -> str:
    missing = [kind for kind, ok in completeness(recorded).items() if not ok]
    if missing:
        return f"incomplete:{','.join(missing)}"
    mismatch = first_mismatch(recorded, live)
    return "ok" if mismatch is None else f"mismatch@{mismatch}"


if __name__ == "__main__":
    recorded = [
        Event(0, "request", "a1"),
        Event(1, "model", "b2"),
        Event(2, "retrieval", "c3"),
        Event(3, "tool", "d4"),
        Event(4, "output", "e5"),
    ]
    live_ok = list(recorded)
    live_bad = list(recorded)
    live_bad[2] = Event(2, "retrieval", "c9")
    print("completeness:", completeness(recorded))
    print("ok:", replay_status(recorded, live_ok))
    print("bad:", replay_status(recorded, live_bad))
    print("missing:", replay_status(recorded[:3], recorded[:3]))

运行:

cd private/labs/agp-lab
python3 -m agp_lab.record_replay

输出:

completeness: {'request': True, 'model': True, 'retrieval': True, 'tool': True, 'output': True}
ok: ok
bad: mismatch@2
missing: incomplete:tool,output

第一条记录包含五类事件,完整性全部为 True,回放状态是 ok。第二条把第 2 步的检索摘要从 c3 改成 c9,回放报告 mismatch@2,直接指出差异发生在检索步骤,而不是让团队从头猜。

第三条只记录了前三步,缺少 tool 和 output,状态是 incomplete:tool,output。完整性检查先于比对:记录本身不完整时,比对结果没有意义,系统应该明确报告“缺什么”,而不是给出一个看似通过的 ok。

这个实验用的是摘要比对,所以它能回答“是否相同”,不能回答“为什么不同”。真正的排障还需要结构化字段和全文;摘要的作用是快速定位到哪一步,再展开那一层的细节。

回放的三种模式

模式做法适用
全录制回放模型、检索、工具全部用录制结果精确复现、审计
部分回放固定检索和工具,重跑模型调试提示与模型
重算回放只固定输入,全部重算评测与回归

全录制回放最稳定,但只能复现“当时发生了什么”,不能回答“如果换个提示会怎样”。部分回放固定外部依赖,重跑模型,适合调试生成逻辑。重算回放最接近真实运行,但受非确定性影响,适合同口径评测而不是逐字节比对。

选择模式取决于问题。排查“模型为什么选了错误的工具”,应该固定检索和工具返回,只重跑模型;排查“检索是否返回了正确片段”,应该固定查询和索引,只重跑检索。

副作用:回放不能重复执行

回放工具调用时,绝对不能真的再执行一次。录制里“删除文件成功”,回放时再删一次可能失败,也可能删掉别的东西;录制里“发送邮件成功”,回放时再发一次就是事故。

处理方式有三种:

  1. Mock:回放时用录制返回替代真实调用,不产生副作用;
  2. Dry-run:调用真实接口的预演模式,只校验参数;
  3. 隔离环境:在沙箱里执行,副作用随环境销毁。

默认应该是 Mock。只有明确需要验证真实集成时,才在隔离环境里 dry-run;生产环境永远不应该对录制的写操作做真实重放。

隐私与合规

事件日志很容易变成隐私泄露源:

  • 用户输入可能包含个人信息;
  • 检索片段可能包含内部文档;
  • 工具参数可能包含凭据;
  • 模型输出可能包含敏感结论。

记录前应该做字段级脱敏:手机号、邮箱、身份证号、密钥用占位符替换;需要保留可关联性时,用带盐哈希而不是明文。访问日志本身也要有权限控制,不能“为了排障”让所有人可读。

回放与回归测试

录制的事件可以直接变成回归测试集:

  • 用录制的 request + retrieval + tool 作为固定输入;
  • 重跑模型,比对 output 的语义是否一致;
  • 对关键案例,比对工具调用序列和参数;
  • 把差异分类为“预期变化”和“回归”。

这样,线上失败可以沉淀为测试,而不是修完就忘。测试集应该覆盖正常路径、边界输入和已知失败案例;只录成功案例,回归测试会漏掉最重要的部分。

架构含义

记录与回放对架构有四个直接约束:

  1. 事件模型统一。 五类事件有统一 schema,能按 trace 关联。
  2. 分层保留。 摘要长期、结构化中期、全文短期并脱敏。
  3. 回放模式可选。 全录制、部分、重算,按问题选择。
  4. 副作用隔离。 回放默认 Mock,写操作永不真实重放。

第 1 条是基础。如果请求、检索、工具各自打日志,格式不同、ID 不通,事后无法拼出一次完整运行;统一事件模型让回放成为可能,而不是一次考古。

架构判据

判据合格的样子不合格的样子
事件完整五类事件齐全只有最终输出
可对齐trace/step ID 贯穿日志各写各的
分层保留摘要/结构化/全文全存或全丢
回放安全默认 Mock重放真实写操作
隐私可控写入前脱敏明文长期保存

这些判据里,“回放安全”是底线。一次误重放的删除或转账,造成的损失可能远大于它想排查的 bug;默认 Mock 应该是不可协商的设计。

一个失败排查的例子

用户报告 Agent 把订单取消了。回放记录显示:

  1. request:用户说“帮我看看订单状态”;
  2. retrieval:返回订单详情,其中包含“取消订单”按钮的文本;
  3. model:模型选择调用 cancel_order;
  4. tool:调用成功;
  5. output:模型回复“已为您查询”。

问题出在第 2 步到第 3 步:检索把按钮文本带进了上下文,模型把“看到按钮”误解为“用户想取消”。有了事件记录,团队可以定位到“检索内容包含可执行文案”这个模式,进而在提示或检索过滤中修复,而不是笼统地加强“不要取消订单”。

这个例子也说明,记录的价值不只是复现,还包括发现系统性的上下文污染。

如何评测记录质量

指标含义
完整率五类事件齐全的请求比例
可回放率能在固定环境下重跑的比例
差异定位率回放能定位到具体步骤的比例
脱敏覆盖率敏感字段被处理的比例
存储成本每请求的事件体积

完整率和可回放率是基础;差异定位率决定排障效率;脱敏覆盖率是合规底线;存储成本决定能保留多久。几个指标要一起看,不能为了完整率无限存全文。

小结

  • 记录与回放把一次运行拆成 request、model、retrieval、tool、output 五类事件。
  • 摘要用于比对,结构化用于排障,全文用于深度复现;三层分层保留并脱敏。
  • 回放有全录制、部分、重算三种模式,按问题选择。
  • 工具副作用必须隔离,回放默认 Mock,写操作永不真实重放。
  • 录制可以沉淀为回归测试,覆盖正常、边界和已知失败案例。
  • 事件模型统一、trace 可对齐,回放才不是考古。

阅读导航:上一节:11.1 非确定性的来源:采样、并发与浮点 · 下一节:11.3 回放的边界:哪些能复现,哪些不能 。

常见错误与边界

  1. 只记录最终输出。 没有中间事件,无法定位问题出在检索、模型还是工具。
  2. 日志各写各的。 格式不统一、ID 不通,事后拼不出一次完整运行。
  3. 重放真实写操作。 删除、转账、发信绝不能在回放时真实执行。
  4. 明文长期保存。 用户输入和工具参数可能含敏感信息,写入前应脱敏。
  5. 只录成功案例。 回归测试缺少失败样本,最重要的路径没有被覆盖。
  6. 把摘要当全文。 哈希只能判断是否相同,不能解释为什么不同。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图