agent-eval

Agent Eval 技能

一个轻量级 CLI 工具，用于在可复现的任务上对编码智能体进行两两对比。每个“哪个编码智能体最好？”的比较都基于主观感受——这个工具将其系统化。

何时激活

• 在你的代码库上比较编码智能体（Claude Code、Aider、Codex 等）
• 在采用新工具或模型前衡量智能体性能
• 当智能体更新其模型或工具时运行回归检查
• 为团队提供基于数据的智能体选择决策

安装

注意： 请从其仓库安装 agent-eval，并在安装前审查源代码。

核心概念

YAML 任务定义

声明式定义任务。每个任务指定要做什么、涉及哪些文件以及如何判断成功：

name: add-retry-logic
description: 为 HTTP 客户端添加指数退避重试
repo: ./my-project
files:
  - src/http_client.py
prompt: |
  为所有 HTTP 请求添加带指数退避的重试逻辑。
  最大重试次数 3。初始延迟 1s，最大延迟 30s。
judge:
  - type: pytest
    command: pytest tests/test_http_client.py -v
  - type: grep
    pattern: "exponential_backoff|retry"
    files: src/http_client.py
commit: "abc1234"  # 固定到特定提交以保证可复现性

Git Worktree 隔离

每个智能体运行使用独立的 git worktree——无需 Docker。这提供了可复现性隔离，确保智能体之间不会相互干扰或破坏基础仓库。

收集的指标

指标	衡量内容
通过率	智能体生成的代码是否通过了评判？
成本	每个任务的 API 花费（可用时）
时间	完成任务的挂钟秒数
一致性	多次运行的通过率（例如，3/3 = 100%）

工作流程

1. 定义任务

创建一个 tasks/ 目录，其中包含 YAML 文件，每个任务一个文件：

mkdir tasks
# 编写任务定义（参见上面的模板）

2. 运行智能体

对任务执行智能体：

agent-eval run --task tasks/add-retry-logic.yaml --agent claude-code --agent aider --runs 3

每次运行：

1. 从指定提交创建一个新的 git worktree
2. 将提示交给智能体
3. 运行评判标准
4. 记录通过/失败、成本和时间

3. 比较结果

生成比较报告：

agent-eval report --format table

任务: add-retry-logic (各运行 3 次)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ 智能体       │ 通过率    │ 成本   │ 时间   │ 一致性      │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code  │ 3/3       │ $0.12  │ 45s    │ 100%        │
│ aider        │ 2/3       │ $0.08  │ 38s    │  67%        │
└──────────────┴───────────┴────────┴────────┴─────────────┘

评判类型

基于代码（确定性）

judge:
  - type: pytest
    command: pytest tests/ -v
  - type: command
    command: npm run build

基于模式

judge:
  - type: grep
    pattern: "class.*Retry"
    files: src/**/*.py

基于模型（LLM 作为评判）

judge:
  - type: llm
    prompt: |
      这个实现是否正确处理了指数退避？
      检查：最大重试次数、递增延迟、抖动。

最佳实践

• 从 3-5 个任务开始，这些任务代表你的真实工作负载，而不是玩具示例
• 每个智能体至少运行 3 次试验以捕捉方差——智能体是非确定性的
• 在任务 YAML 中固定提交，以便结果在数天/数周内可复现
• 每个任务至少包含一个确定性评判（测试、构建）——LLM 评判会增加噪声
• 同时跟踪成本和通过率——一个成本高 10 倍的 95% 通过率智能体可能不是正确选择
• 对任务定义进行版本控制——它们是测试夹具，应像代码一样对待

链接

• 仓库：github.com/joaquinhuigomez/agent-eval