agent-eval：一个用 Go 写的 AI Agent 评估框架，YAML 配置零代码上手

AI Agent 越来越多，但怎么评估一个 Agent 到底行不行？大多数人还在用"手动试几轮，感觉还行"这种方式。Anthropic 发过一篇博客《Demystifying Evals for AI Agents》，系统讲解了 Agent 评估的方法论，但真正能落地的工具很少。

最近在 GitHub 上发现一个叫 agent-eval 的项目，用 Go 写的，思路很清晰——用 YAML 配置定义评估任务，一行命令跑完，自动生成报告。不依赖 Python 环境，不装一堆包，下载一个二进制文件就能用。

本文提纲

1. 它解决什么问题
2. 核心设计：YAML 驱动 + 8 种评分器
3. 可靠性指标：pass@k 和 pass^k
4. 架构拆解
5. 实际用法
6. 和类似工具的对比
7. 值得关注的技术细节

它解决什么问题

评估 AI Agent 比评估普通 LLM 难得多。普通 LLM 评估可以比对输出文本，但 Agent 会调用工具、执行多步推理、处理错误重试——你需要评估的不只是"答案对不对"，还有"过程靠不靠谱"。

具体来说，agent-eval 解决这几个痛点：

• 没有标准化评估流程：每次评估都临时写脚本，不可复现
• 单一指标不够：光看准确率不够，还要看延迟、成本、稳定性
• 反复测试太贵：API 调用要花钱，跑 100 次评估不能每次都从头来
• 结果难以对比：改了 prompt 后效果变好还是变差？没有量化数据

agent-eval 的方案是：用 YAML 文件定义评估套件（EvalSuite），里面包含多个任务（Task），每个任务可以重复跑多次（Trial），用不同策略打分（Grader），最后汇总成报告。

核心设计：YAML 驱动 + 8 种评分器

最吸引我的一点是——不需要写代码。一个 YAML 文件搞定全部配置：

# eval.yaml
agent:
  type: openai
  model: gpt-4o

tasks:
  - name: "法国首都"
    input: "法国的首都是什么？"
    trials: 5
    graders:
      - type: exact_match
        expected: "巴黎"

跑起来就是一行命令：

agent-eval run -c eval.yaml

8 种内置评分器

这是我觉得设计得比较用心的地方。不同类型的 Agent 输出，用不同的评分策略：

评分器	适用场景	示例
exact_match	有确定答案的问答	"法国首都" → "巴黎"
contains	半结构化输出	回答中包含某个关键词
regex	格式化输出验证	检查是否匹配正则
json_match	API 响应验证	JSON 字段值比对
command	外部命令评分	跑单元测试判断对错
llm	开放式输出评估	用 LLM 按 rubric 打分
pairwise	A/B 对比	两个模型谁更好
constraint	安全/合规检查	是否泄露 PII、是否超字数

一个任务可以配多个评分器，按权重加权计算最终分数。比如一个翻译任务，可以同时用 llm 评翻译质量，用 constraint 检查是否泄露原文中的敏感信息。

4 种 Agent 适配器

支持直接对接常见的 Agent 后端：

• OpenAI：直接调用 OpenAI API
• Anthropic：对接 Claude 系列
• HTTP：任何 HTTP API 都能对接
• Command：执行本地命令，适合测试 CLI 工具型的 Agent

可靠性指标：pass@k 和 pass^k

这个设计直接参考了 Anthropic 的评估方法论，也是 agent-eval 区别于其他工具的核心亮点。

pass@k（乐观估计）：同一个任务跑 k 次，至少 1 次通过的概率。衡量 Agent 的"能力上限"——给它足够多机会，能不能做对。

pass^k（严格估计）：同一个任务跑 k 次，全部通过的概率。衡量 Agent 的"可靠性"——能不能每次都做对。

举个例子：一个编程任务跑 5 次，3 次通过。

• pass@1 = 3/5 = 60%（单次通过率）
• pass@5 ≈ 1 - C(2,5)/C(5,5) = 100%（5 次里至少过 1 次的概率）
• pass^5 ≈ C(3,5)/C(5,5) ≈ 0%（5 次全过的概率）

这两个指标结合起来，能看出 Agent 是"偶尔能做对"还是"每次都稳定"。代码实现用了 log 空间算组合数，避免大数溢出，这个细节处理得不错。

架构拆解

整个项目用 Go 写的，模块划分清晰：

graph TB
    CLI[CLI: Cobra Commands] --> Config[Config: YAML Loader]
    Config --> Engine[Engine: Orchestration]
    Engine --> Scheduler[Scheduler: Concurrent Runner]
    Scheduler --> Runner[Runner: Trial Execution]
    Runner --> Agent[Agent Adapters]
    Runner --> Grader[Graders: 8 Types]
    Engine --> Storage[Storage: SQLite]
    Engine --> Report[Report: Table/JSON/HTML]
    Engine --> Cache[Cache: File-based]
    CLI --> WebUI[Web UI: Vue 3 SPA]

几个值得说的设计决策：

注册表模式（Registry Pattern）：新增 Agent 类型或评分器，不需要改任何已有代码。只要新建一个文件，在 init() 里调用 Register("name", factory) 就行。Go 的 init() 机制在这里用得恰到好处。

纯 Go SQLite：用 modernc.org/sqlite，不需要 CGO。这意味着交叉编译出单个二进制文件时不会遇到 libc 兼容性问题。对 CI/CD 环境特别友好。

嵌入式前端：Web UI（Vue 3 + shadcn-vue + Tailwind CSS）用 go:embed 打包进二进制文件。不需要单独部署前端服务，agent-eval server 一启动就能在浏览器里管理评估任务。

实际用法

最简示例

agent:
  type: openai
  model: gpt-4o
  api_key: ${OPENAI_API_KEY}

tasks:
  - name: "数学测试"
    input: "计算 17 * 23"
    trials: 3
    graders:
      - type: exact_match
        expected: "391"

agent-eval run -c eval.yaml

CI/CD 集成

# 通过率低于 80% 就返回非零退出码，CI 直接失败
agent-eval run -c eval.yaml --fail-under 80

# 输出 summary.json 给下游流程用
agent-eval run -c eval.yaml --format json --output results/

断点续跑

评估跑到一半网络断了？加 --resume 从断点继续，不用重新调用已完成的 API：

agent-eval run -c eval.yaml --resume

Web UI

agent-eval server -p 8080
# 浏览器打开 http://localhost:8080

可以在浏览器里编辑 YAML 配置、触发评估、查看可视化结果。

和类似工具的对比

把 agent-eval 放在当前 AI 评估工具的生态里看：

维度	agent-eval	promptfoo	Ragas	LangSmith
语言	Go（单二进制）	Node.js	Python	Python SDK
配置方式	YAML	YAML/JS	Python 代码	SDK/Web
评估对象	Agent	Prompt/Agent	RAG	全链路
可靠性指标	pass@k + pass^k	无	无	无
内置存储	SQLite	文件	无	云端
Web UI	内嵌	有	无	有
离线使用	完全支持	支持	不支持	不支持

agent-eval 的优势集中在三点：零依赖部署（单二进制）、可靠性量化（pass@k/pass^k）、完整工具链（CLI + Web + 存储 + 报告）。劣势是生态还比较早期，社区和集成不够丰富。

值得关注的技术细节

几个让我觉得作者花过心思的地方：

响应缓存：同一个 input + 配置，不会重复调用 API。对反复调试评估任务的人来说，这能省不少 API 费用。缓存基于文件系统，不用额外装 Redis。

延迟百分位数：不只报平均延迟，还报 P50/P90/P99。对需要满足 SLA 的线上 Agent 来说，P99 延迟比平均值重要得多。

Token 和成本追踪：自动从 Agent 返回的 metadata 里提取 token 用量，按模型估算成本。评估完直接看到这次跑了多少钱。

生命周期钩子：可以在评估前/后执行 shell 命令。比如评估前自动启动本地服务，评估后自动清理环境。

双语文档：README 和 VitePress 文档都提供了中英文版本，对国内开发者比较友好。

---

项目还比较早期（5 stars，2026 年 3 月才开始），但代码结构清晰，功能完整度已经不低了。如果你在做 Agent 开发，需要一个轻量级的评估工具来量化效果，值得试一下。

安装很简单，去 GitHub Releases 下载对应平台的二进制文件就行，不需要装 Go，不需要装 Python。

---

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。