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 次。初始延遲 1 秒，最大延遲 30 秒。
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

Task: add-retry-logic (各執行 3 次)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent        │ 通過率    │ 成本   │ 時間   │ 一致性      │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ 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