TaimoorKhan10/replayd 源代码：https://github.com/TaimoorKhan10/replayd # replayd PyPI (https://pypi.org/project/replayd/) Python (https://pypi.org/project/replayd/) 许可证：MIT 将失败的AI Agent运行转化为可复现的回归测试。 当AI Agent在生产环境中失败时，这次失败会成为每次部署前运行的测试。如果在提示词、模型或工具变更后同样的失败再次出现，发布将被阻止。 pip install replayd — ## 问题所在 AI Agent会静默地回归故障。团队修复了一个bug，修改了提示词或模型，同一个bug又悄悄重现。传统软件有回归测试和CI/CD来捕获这类问题。AI Agent却没有对等的机制。 replayd是开源的解决方案。它在你发布之前重放已知的失败，确保同样的错误不会再次出现。 — ## 快速开始 python from replayd import Replayd rp = Replayd() # 1. 捕获一次运行 — 在块内赋值 run.output with rp.capture(input=user_input, model="gpt-4o") as run: run.output = your_agent.run(user_input) # 注意：请封装你的agent以记录工具调用 — 见下方“记录工具调用” # 2. 标记为失败 rp.mark_failed(run.id, reason="agent approved refund after policy limit") # 3. 保存为回归测试 rp.save_test( run.id, forbidden_actions=["approve_refund"], expected_action="escalate", ) # 4. 之后 — 修改了提示词或模型后 — 重放所有测试 results = rp.replay_all(agent=your_agent_fn) for r in results: print(r.verdict, r.reason) — ## 查看效果 运行附带的示例（python examples/basic_example.py），会得到如下输出： Capturing a refund-approval agent run... agent called: approve_refund(amount=1200) [policy limit is $500] output: {'action': 'approve_refund', 'amount': 1200} Marking run as failed... reason: agent approved refund of $1200, exceeding $500 policy limit Saving as regression test... forbidden: approve_refund | expected: escalate ----------------------------------------- Replay #1 -- buggy agent (regression should be caught) [FAIL] Forbidden action 'approve_refund' was called during replay. Replay #2 -- fixed agent (regression should be resolved) [PASS] No forbidden actions called; all expected actions present. ----------------------------------------- 1 failure caught. 1 resolved. 失败被捕获、保存，并在有问题的Agent（FAIL）上重放，然后在修复后的Agent（PASS）上再次重放。这就是完整的循环。 — ## 记录工具调用 replayd无法自动拦截工具调用。请封装你的Agent的工具分发器来记录工具调用： python def my_agent(input, run_ctx): result = call_tool("search", {"query": input["query"]}) run_ctx.record_tool_call("search", {"query": input["query"]}, result) # ... 剩余Agent逻辑 return final_output 将这个双参数的可调用对象传递给replay_all： python results = rp.replay_all(agent=my_agent) — ## 评分 replayd 不依赖精确输出匹配。LLM是非确定性的 —— 同样的正确行为每次运行时会产生不同的输出文本，因此精确匹配会导致误报。然而，调用了错误的工具是一个事实。replayd基于事实进行评分。 | 失败类型 | 评分方法 | |—|—| | 调用了错误的工具、错误的参数、错误的状态 | 确定性断言 —— 无需LLM，永远不会不稳定 | | 违反策略、错误的推理、糟糕的决策 | LLM作为评审（通过 grader_prompt） | 结构检查总是先运行。如果触发了禁止的操作，测试立即失败，无需调用LLM。 ### 语义评分 对于只能通过阅读输出内容来评估的失败： python rp.save_test( run.id, grader_prompt="Did the agent approve a refund that exceeds the $500 policy limit?", ) 需要： pip install "replayd[semantic]" export ANTHROPIC_API_KEY=sk-... — ## 存储 运行记录和测试以JSON文件形式存储在工作目录下的.replayd/文件夹中： .replayd/ runs/.json <- captured runs tests/.json <- saved regression tests 无需数据库，无需托管后端。将.replayd/tests/检入版本控制，即可与团队成员共享测试。本仓库附带的.gitignore默认排除了.replayd/ —— 只提交tests/子文件夹，不要提交捕获的运行记录。 — ## CI集成 在scripts/regression_check.py中提供了一个可直接使用的脚本。将其复制到你的仓库，替换Agent的导入，然后将其添加到你的工作流中： yaml # .github/workflows/regression.yml - name: Run regression tests run: python scripts/regression_check.py — ## replayd不是什么 replayd不是可观测性工具。LangSmith、Braintrust和Arize能告诉你事后发生了什么。 replayd是一个主动的发布门禁 —— 它在发布前重放已知的失败。被动 vs 主动。这就是区别。 — ## Stonepath Labs的TAQ的一部分 replayd是TAQ (https://stonepathlab.net) 的开源核心 —— 完整的AI发布控制平台。 TAQ增加了：仪表盘、托管后端、团队访问控制、发布门禁执行和审计日志。 replayd让团队先用这个概念起步。TAQ是你生产环境中运行它的平台。 stonepathlab.net (https://stonepathlab.net) — ## 贡献 欢迎提交bug报告和拉取请求。在发送大型PR之前，先在GitHub上开一个issue讨论。 构建没有依赖 —— pip install -e ".[dev]" 就能获得运行测试所需的一切： pip install -e ".[dev]" pytest — ## 许可证 MIT —— 见 LICENSE。