getedgehq/agent-evals

エージェント評価（Agent evals）

評価（eval）は、エージェントが仕事を正しく完了したかどうかという、ただ一つの問いに答えます。 以下の内容はすべて、その問いをより確実に、より低コストに、より頻繁に問うための方法です。

Alex Lieberman氏（Viv／LangChain、2026年）によるevalsマスタークラスから構築されています： youtube.com/watch?v=zLeG-XJtbIE。構造（Easy、Hard、Godモード）は同氏によるものです。このスキル内の誤りはすべて私たちのものです。

まずはユーザーに3つの質問をする

1. エージェントは実際にどのような業務を行っていますか？ それが触れるシステム（CRM、受信箱、リポジトリ、データベース）を教えてください。
2. 現在、その業務に最も精通している社内の担当者は誰ですか？ その人の判断が正解データ（ground truth）となります。
3. エージェントは本番環境で実行されていますか？ 実行されている場合、トレースはどこかに保存されていますか？

回答に基づいてモードを選択してください。タスクと判定器（verifier）なしにGodモードに進まないでください。

Easyモード：タスクと判定器

**タスク（task）**とは、実際の業務の小さくチェック可能な一部分です。 **判定器（verifier）**とは、そのタスクが正しく実行されたかどうかを判定するものです。

1. 実際の同僚が行っていることを模倣したタスクを10～30個作成します。営業エージェントの例：
   • 通話後にCRMレコードにメモを追加する
   • 明らかなテーブルにいない見込み客を見つける
   • 送信せずに返信メールの下書きを作成する
2. 各タスクに対して、判定器を記述します。優先順位は以下の通り：
   • 状態チェック（スクリプト）：以前は空だったフィールドに正しい値が入っている、email_sentタグが存在する、など。
   • チェックリスト（モデルまたは人間）：直接検証できないものについては、「良い」状態をYes/Noの質問に分解します。「3段落以内か？」「ブランドのトーンルールに従っているか？」
3. すべての判定はバイナリにします。1～10のスコアをモデルに求めると、7付近に集中し、曖昧になります。Yes/Noは曖昧になりません。
4. チェックリストは、その業務に最も精通した担当者から書面で入手します。エージェントを実行し、サンプルを手動でレビューします。出力がチェックリストをパスしたにもかかわらず依然としておかしいと感じる場合、チェックリストは不完全です。不足している質問を追加します。

Easyモードの出力：各タスクに指示と判定器が含まれたフォルダ、および合格率。

Hardモード：環境

**環境（environment）**とは、エージェントが作業を行う場所（ファイル、ツール、データ、権限）です。 本番データに対して評価（eval）を決して実行しないでください。評価に失敗したエージェントが本番CRMを編集してしまう可能性があります。

1. エージェントにとって本番のように見えるコピーを構築します（同じテーブル、同じツール、偽のレコード）。毎回同じ状態にリセットできるようにパッケージ化します（コンテナが一般的な選択肢です）。
2. 1タスク＝指示 ＋ 環境 ＋ 判定器。これらをまとめて保存します。
3. 可能であれば、独自のランナーを作成しないでください。Harbor（github.com/harbor-framework/harbor）は、タスク、環境、判定器の共有フォーマットと、多くの公開タスクを提供しており、それを流用できます。
4. 環境自体をテストしてください。 最初の環境はほぼ間違いなく間違っています。複数の異なるエージェントやモデルで実行し、奇妙なパターンを探します：
   • 強いモデルが弱いモデルに失敗する場所で失敗する
   • エージェントが本来あるべきでない場所（プレースホルダー行、漏洩したファイル）で答えを見つける。エージェントは合格するためにあらゆるショートカットを取ります。漏洩を排除します。
5. すべてのタスクをファミリー（コーディング、営業、コードレビュー）でタグ付けします。 新しいモデルがリリースされたとき、そのモデルが得意そうなファミリーのみを実行します。
6. 感覚ではなく、表を使ってモデルを選択します。 各候補モデルを同じタグ付きタスクで実行します。合格率、コスト、速度を並べて記録します。その後、人間が判断します：「このファミリーでは、3倍のコストを払ってでも精度を5ポイント上げる価値があるか？」 ユーザー向けのタスクは通常、最高のモデルが正当化されますが、内部的なタスクはそうでないことがよくあります。

Hardモードの出力：任意のモデルに対して1つのコマンドで再実行可能な評価スイートと、タスクファミリーごとの結果表。

Godモード：改善ループ

ループ：エージェントが実行 → トレースを生成 → 失敗が新しいタスクになる → エージェントが修正される → 繰り返し。

1. トレースを有効にします。 トレースとは、すべてのアクション（各ツール呼び出し、各メッセージ、各結果）のログです。エージェントが何をするかを予測できる人はいません。しかし、何をしたかを評価することは誰にでもできます。
2. トレースを1か所に保存します。 単一の開発者であれば、エージェント自身のディスク上のログで十分です。チームの場合は、適切な権限を持つトレーシングプロダクトを使用します。
3. 別のエージェントをトレースに向けます。 その唯一の仕事はパターンを見つけることです。良好な振る舞いと不良な振る舞いの簡単なブリーフを与えます。以下の項目を要求します：
   • 失敗した、または繰り返されたツール呼び出し
   • 無視された、または中途半端に従われた指示
   • 繰り返し発生する誤ったパス（常に間違ったテーブルを検索する、3件依頼されたのに1社だけ処理するなど）
4. 確認された各失敗を評価スイートのタスクに変換します。 そうすることで、その失敗が黙って再発することを防ぎます。
5. エージェントを修正します。 最も低コストなレバーから順に試します：
   • ハーネス：プロンプト、ツールの説明、ツールセット、モデルの選択
   • 評価スイートが大きなモデルと同等の性能を証明した後、小さなオープンモデルを特定タスクにファインチューニング
6. 「良い」とは何かを決める人間を維持します。 エージェントは修正案を提案し、タスクの下書きを作成できます。しかし、どのタスクがビジネスにとって重要かを決定し、新しいタスクをレビューするのは依然として人間です。それを文書化することが、このループの中で最もレバレッジの高い部分です。

ルール

• 名前の付いた実際の業務がない評価（eval）は無効です。汎用的なベンチマークでは、エージェントが機能するかどうかはわかりません。
• 判定器はバイナリのみにします。スコアはすべてYes/Noの質問に分割します。
• 評価が本番データに触れることを決して許しません。
• すべてがパスするスイートは壊れたスイートです。漏洩がないか確認してください。
• 合格率は、タスク数を併記して報告します（例：「30件中21件」）。割合のみの報告は禁止です。