agent-eval

# エージェント評価スキル 再現可能なタスクでコーディングエージェントをヘッドツーヘッドで比較するための軽量 CLI ツールです。「どのコーディングエージェントが最適か？」という比較はすべて感覚に頼りがちです — このツールはそれを体系化します。 ## 起動タイミング - 自分のコードベースでコーディングエージェント（OpenAI Codex、Aider、Codex など）を比較する - 新しいツールやモデルを採用する前にエージェントパフォーマンスを測定する - エージェントがモデルやツールを更新した際にリグレッションチェックを実行する - チームにデータに基づいたエージェント選択の判断を提供する ## インストール > **注意:** agent-eval はソースを確認した後、リポジトリからインストールしてください。 ## コアコンセプト ### YAML タスク定義 タスクを宣言的に定義します。各タスクは何をするか、どのファイルを操作するか、成功をどう判定するかを指定します： ```yaml name: add-retry-logic description: Add exponential backoff retry to the HTTP client repo: ./my-project files: - src/http_client.py prompt: | Add retry logic with exponential backoff to all HTTP requests. Max 3 retries. Initial delay 1s, max delay 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 ワークツリー分離 各エージェント実行は独自の git ワークツリーを取得します — Docker 不要。これにより再現性の分離が提供され、エージェントが互いに干渉したりベースリポジトリを破壊したりしません。 ### 収集メトリクス | メトリクス | 測定内容 | |--------|-----------------| | 合格率 | エージェントはジャッジをパスするコードを生成できたか？ | | コスト | タスクあたりの API 費用（利用可能な場合） | | 時間 | 完了までのウォールクロック秒数 | | 一貫性 | 繰り返し実行での合格率（例：3/3 = 100%） | ## ワークフロー ### 1. タスクの定義 タスクごとに 1 つの YAML ファイルを持つ `tasks/` ディレクトリを作成します： ```bash mkdir tasks # タスク定義を作成（上記のテンプレートを参照） ``` ### 2. エージェントの実行 タスクに対してエージェントを実行します： ```bash agent-eval run --task tasks/add-retry-logic.yaml --agent codex --agent aider --runs 3 ``` 各実行： 1. 指定されたコミットから新しい git ワークツリーを作成 2. エージェントにプロンプトを渡す 3. ジャッジ基準を実行 4. 合格・不合格、コスト、時間を記録 ### 3. 結果の比較 比較レポートを生成します： ```bash agent-eval report --format table ``` ``` Task: add-retry-logic (3 runs each) ┌──────────────┬───────────┬────────┬────────┬─────────────┐ │ Agent │ Pass Rate │ Cost │ Time │ Consistency │ ├──────────────┼───────────┼────────┼────────┼─────────────┤ │ codex │ 3/3 │ $0.12 │ 45s │ 100% │ │ aider │ 2/3 │ $0.08 │ 38s │ 67% │ └──────────────┴───────────┴────────┴────────┴─────────────┘ ``` ## ジャッジタイプ ### コードベース（決定論的） ```yaml judge: - type: pytest command: pytest tests/ -v - type: command command: npm run build ``` ### パターンベース ```yaml judge: - type: grep pattern: "class.*Retry" files: src/**/*.py ``` ### モデルベース（LLM-as-judge） ```yaml judge: - type: llm prompt: | Does this implementation correctly handle exponential backoff? Check for: max retries, increasing delays, jitter. ``` ## ベストプラクティス - **3〜5 タスクから始める** — おもちゃの例ではなく、実際のワークロードを代表するタスク - **エージェントごとに少なくとも 3 試行実行する** — エージェントは非決定論的なので分散を把握する - **タスク YAML でコミットを固定する** — 日や週をまたいで結果が再現可能になる - **タスクごとに少なくとも 1 つの決定論的ジャッジを含める**（テスト、ビルド）— LLM ジャッジはノイズを加える - **合格率と一緒にコストを追跡する** — 10 倍のコストで 95% のエージェントが正しい選択でない場合もある - **タスク定義をバージョン管理する** — それらはテストフィクスチャであり、コードとして扱う ## リンク - リポジトリ: [github.com/joaquinhuigomez/agent-eval](https://github.com/joaquinhuigomez/agent-eval)