CrossTrace 在 CI 里测试智能体故障恢复
CrossTrace 通过本地代理录制正常调用,并在回放中注入模型或 MCP 调用故障。作者在测试 Pydantic AI 和 CrewAI 时发现,原先依赖原样重试的判定逻辑会误伤拦截无效工具参数、压缩上下文后继续等合理恢复行为。
AI 深度解读
AI Agent 在 CI 里正常退出,退款工具却可能已经执行了两次。CrossTrace 用一次成功录制做基线,回放时故意截断模型响应、制造超时,或丢掉已经执行的 MCP 工具响应,再观察 Agent 怎么收场。
作者拿三个框架跑了一遍,发现工具也会误报。拒绝残缺的工具参数、要求模型重答、压缩上下文后继续,都曾被判成「掩盖失败」。对写 AI 应用的人来说,这篇最值得看的地方,是怎样把可接受的恢复策略和会让 CI 失败的故障区分开。
为什么换了一条请求,不能直接判失败
CrossTrace 在 Agent 和模型 API 之间放了一个本地代理。Agent 通过 OPENAI_BASE_URL 指向代理,工具先录制一次正常执行,再离线回放。每轮只挑一次模型调用注入故障,例如在工具调用还没传完整时切断流、让响应一直卡住、返回 HTTP 500 或给出空回复。判定靠请求和运行结果,无需请另一个模型打分。
早期版本只看故障后的第一条请求。Agent 如果没有原样重试,而是发出一条不同的请求,工具就可能标成 SILENT,让构建失败。问题在于,要求模型重答和忽略异常继续执行,在请求结构上可能一模一样,都是在失败回复后追加一条用户消息。作者实测时,pydantic-ai 拒绝执行被截断的工具调用,并告诉模型参数无效。CrewAI 遇到上下文长度错误后先做摘要,再继续执行。两种合理处理都被误判了。
误报还有一层原因。录制只覆盖正常路径,恢复请求往往根本没有对应的录制响应。旧版回放会在这里提前结束,判定器也就看不到后续行为。新版给匹配不到的请求接上一条正常录制中的回复,让流程继续,观察 Agent 最终是完成、报错退出,还是一直发请求。到 8 条不同请求的上限就标为 RETRY_STORM。如果证据只够说明请求发生了变化,就标成 DIVERGED 或 REPROMPTED 供人工查看,同时展示发送了什么、遇到什么错误、告诉了模型什么。挂起、重试风暴和忽略 Retry-After 这类行为则可以直接观测。
离线跑到结束,能证明恢复成功吗
离线回放能观察 Agent 怎样结束。至于新的提示词能不能让模型给出可用答案,还要看真实模型怎么回。--live 会用作者自己的密钥把这些请求发给真实模型服务,Agent 接触不到密钥,每轮最多 6 次调用。pydantic-ai 拒绝残缺参数后,又发了 3 次请求才完成。CrewAI 在上下文长度错误后做了摘要,又发了 4 次请求才完成。OpenAI Agents SDK 在线和离线的表现一致,直接抛错退出,没有重试。
作者也实际跑了卡住后的修复,在客户端用 timeout= 配了 10 秒。持续故障时,CrewAI 大约 3 秒内重试了 7 次以上。pydantic-ai 收到空回复会要求模型重答。各案例只跑了 1 到 2 轮,真实模型的回复也会变化,所以这些结果能展示恢复路径,无法用来估计恢复成功率。作者把 --live 留给演示,把可重复的离线回放留给 CI。
退款已经成功,为什么 Agent 还会再退一次
工具执行成功和 Agent 收到成功回执是两件事。网络恰好在中间断掉,Agent 看到的是传输错误。如果下一步直接重试,发邮件、下单和退款这些写操作就可能再执行一次。CrossTrace 支持用 crosstrace mcp-wrap 包装 MCP 服务,也支持在 crosstrace.toml 里填远程 HTTP 服务的 URL。默认回放不启动或调用真实服务,它会记下一次工具执行,把回复换成传输错误,再拿后续写入次数和正常录制比较。
仓库里带朴素重试循环的退款示例,会用下面的报告显示重复写入。
✗ lost_response DUPLICATE 1/1
refund({"amount":129.99,"customer_id":"42",...}) ran 2 time(s), 1 in the healthy run;
the agent recovered and finished, but the write was repeated
第二行是检查重点。客户 42 的 129.99 退款在故障回放中记了两次,正常录制中只有一次。示例 Agent 仍然打印了正确答案,并以退出码 0 结束。
作者还用官方 Playwright MCP 服务、真实 Chrome 和本地下单表单做了验证。录制时实际下了一单,回放时没有新订单,丢掉点击响应会让重试被标成 DUPLICATE。这次用的是脚本化 Agent,验证范围是工具调用处理。另一次用 --real-tools 接入远程 HTTP 服务,服务器确实退了两次款,报告会引用服务器对重复调用的回复。这个选项会真实执行写入,作者建议指向沙箱。
我的判断
把退出码和写入次数一起看,是这篇最实用的做法。常见的用例只断言最后一条消息或进程退出状态,退款案例里这两项都能过。反过来,仅凭请求形状去判断 Agent 是否忽略故障,容易误伤不同框架的恢复逻辑。把可测行为设为 CI 门槛,把恢复请求交给人看,判定更容易复核。
离线回放最明显的边界也在退款场景。假如 Agent 重试前先查「这笔钱已经退了吗」,回放仍会给它录制下来的旧回答。这个案例可能显示为报错退出,无法验证查状态后安全恢复。对于已有沙箱的团队,可以在真实服务的集成测试里断言最终只有一笔退款。CrossTrace 的覆盖范围是模型和 MCP 调用,Agent 自己发出的其他 HTTP 请求仍需单独测。MCP 支持 stdio 和 streamable HTTP,服务端在独立流上主动推送消息的场景还不支持。
作者没有给出跨团队对照数据,也提到目前没有外部用户。框架表现来自他自己编写或录制的 Agent,适合用来找测试切入点。至于接进现有 CI 后能发现多少问题、需要维护多少录制,目前仍是开放问题。
能拿来做什么
- 先录一条已有的 Agent 流程,再离线注入故障。下面是作者给的 Python 示例,
examples/broken_agents里也有带录制的演示,无需密钥。
pip install git+https://github.com/mac146/crosstrace
crosstrace init --command "python agent.py {input}"
crosstrace record # runs your agent for real, once per input
crosstrace test # replays with faults, offline; exit code 1 if it hides a failure
第三行 crosstrace record 会对每个输入真实执行一次。给包含下单或退款的流程做录制时,先把写入目标指向测试环境。
- 给 Node 或全栈 Agent 补一条「工具已经写入,响应丢失」的用例。在断言最终回复之外,再断言订单、邮件或退款只产生一次。
- 把模型客户端超时、持续故障时的重试次数,以及是否遵守
Retry-After纳入 CI。遇到REPROMPTED,先从报告看 Agent 给模型补了什么,再按需用--live验证这条恢复路径。