Agentsnap：为 AI 智能体提供快照测试的 Python 工具

AI 智能体在迭代过程中常常「沉默回归」：提示词微调、底层模型替换、工具参数接错，都不会抛出异常，也不会让 CI 失败，直到生产环境出现质量下降才被发现。开发者 Faham 在 Hacker News 上发布了开源工具 Agentsnap，把传统软件测试中成熟的快照测试思路引入到 AI 智能体场景。

核心思路：录制一次，回归每次

Agentsnap 在一次「golden run」中记录智能体所有 LLM 调用与工具调用，生成可提交的快照文件。后续每次运行时，它会重放相同输入，并把新一轮的执行轨迹与快照在四个维度上对比：

• 结构（Structural）：工具调用名称与顺序，使用 Levenshtein 编辑距离衡量。
• 参数（Arguments）：工具调用参数，通过 deepdiff 或字典 diff 比对，支持配置忽略字段。
• 模型工具（Model tools）：模型自身请求的工具（而非代码层执行的工具），按请求序列与参数分别对比。
• 语义（Semantic）：LLM 响应与最终输出，默认使用 all-MiniLM-L6-v2 计算余弦相似度，也可配置 LLM judge 获得更高准确度。

任意维度超出阈值，Agentsnap 抛出 AgentRegressionError 并附带结构化 diff 报告。

两种运行模式：Replay 与 Live

Agentsnap 区分两种使用场景，分别适合 CI 和夜间任务：

• Replay（每次 PR）：回放录制的响应而非调用真实 API，确定性、零成本，专门捕捉代码侧回归，例如提示词编辑、工具接线错误、调用次数变化。
• Live（夜间任务）：对当前模型发起真实 API 调用，捕捉模型本身变化导致的漂移。

Replay 模式下工具调用默认仍真实执行，可通过 replay_tools=True 完全 stub。模式可在测试级、会话级通过 pytest 选项或 pyproject.toml 配置。

三步上手

• 安装：pip install agentsnap，随后运行 agentsnap init 在交互向导中选择语义后端，可选 LLM judge（OpenAI / Anthropic / OpenRouter / 自定义）、离线 Embedding（约 22 MB 模型，无需 API key）或本地 LLM judge。
• 录制：通过 PatchSet 在类级别 patch 已安装 LLM SDK，无需修改业务代码即可捕获原始客户端调用。
• 断言：用 AgentAsserter 或 pytest fixture snapshot.run()，首次自动录制，之后每次自动断言。

兼容性与限制

• 当前 Replay 模式支持 Anthropic、OpenAI、Groq、OpenRouter，其他提供方需使用 Live 模式。
• Replay 模式需要 agentsnap >= 0.2.0 录制的快照（含 raw_response），旧快照会抛出 SnapshotFormatError，需重新录制。
• 异步客户端（AsyncAnthropic 等）支持情况以官方文档为准。

对于正在构建生产级 AI 智能体的团队，Agentsnap 提供了一个低门槛的回归检测入口；不过它的实际价值仍取决于团队能否为 agent 维护稳定的「golden run」输入集合。