我为 AI 代理构建了一个类似 pytest 的工具，因为 “it passed once” 还不够。

Source: Dev.to

介绍

你是否有过这样的感觉：你的 AI 代理在开发环境中运行完美，但在生产环境中却随机出错？相同的提示、相同的模型，却得到不同的结果。我花了太多时间调试那些偶尔会失败的代理。最糟糕的不是失败本身，而是根本不知道原因。是工具选择的问题？提示的问题？模型状态不佳？

现有的评估工具帮助不大。它们只运行一次测试，检查输出，然后结束。但代理并非确定性行为。只跑一次测试几乎没有任何意义。

agentrial

我构建了 agentrial，一个类似 pytest 的 AI 代理测试框架，它会对每个测试运行多次并提供真实的统计数据。

安装

pip install agentrial

配置 (agentrial.yml)

suite: my-agent
agent: my_module.agent
trials: 10
threshold: 0.85

cases:
  - name: basic-math
    input:
      query: "What is 15 * 37?"
    expected:
      output_contains: ["555"]
      tool_calls:
        - tool: calculate

运行测试

agentrial run

输出

┌──────────────────────┬────────┬──────────────┬──────────┐
│ 测试用例            │ 通过率 │ 95% 置信区间 │ 平均费用 │
├──────────────────────┼────────┼──────────────┼──────────┤
│ easy-multiply        │ 100.0% │ 72.2%-100.0% │ $0.0005  │
│ medium-population    │ 90.0%  │ 59.6%-98.2%  │ $0.0006  │
│ hard-multi-step      │ 70.0%  │ 39.7%-89.2%  │ $0.0011  │
└──────────────────────┴────────┴──────────────┴──────────┘

置信区间

“95% 置信区间”列显示的是 Wilson 分数区间。进行 10 次试验后，100 % 的通过率实际上意味着在 95 % 置信水平下，真实通过率介于 72 % 到 100 % 之间。看到“100 %（72‑100 %）”而不是单纯的“100 %”，彻底改变了我对代理可靠性的看法。

步骤级别的失败归因

当测试失败时，agentrial 会告诉你是哪一步出现了偏差：

Failures: medium-population (90% pass rate)
  Step 0 (tool_selection): called 'calculate' instead of 'lookup_country_info'

在我的案例中，代理在模糊查询时偶尔会选错工具——这类 bug 若手动排查需要数小时。

实际费用追踪

agentrial 会从 API 响应的元数据中提取 token 使用情况。对 10 个测试用例执行 100 次试验，总费用仅 6 美分，并在扩展前提供了每个测试的精确费用估算。

CI 集成

可以在 GitHub Action 中强制每个 PR 达到可靠性阈值：

- uses: alepot55/agentrial@v0.1.4
  with:
    trials: 10
    threshold: 0.80

如果通过率低于 80 %，PR 将被阻止。上周正是它拦截了两次回归，否则这些问题本会被直接发布。

当前局限

• 目前仅支持 LangGraph；计划后续加入 CrewAI 和 AutoGen 的适配器。
• 仅提供 CLI，尚未有图形界面。
• 暂未实现 LLM‑as‑judge 的语义评估（后续会加入）。

开源

agentrial 采用 MIT 许可证，代码托管在 。

结束语

我用了大约一周时间（主要借助 Claude Code）完成了整个项目。统计部分（Wilson 区间、用于回归检测的 Fisher 精确检验、Benjamini‑Hochberg 校正）是最有趣的环节。如果你在构建代理时已经厌倦了“在我的机器上可以工作”，不妨试试 agentrial。我仍在探索哪些指标最有价值，欢迎分享你的想法！