AIエージェント評価（eval）の作り方 ― agent-evalに学ぶ、実務で使える評価基盤の設計

「デモ環境では完璧に動くのに、本番に出した途端に壊れる」――AIエージェント開発に携わるエンジニアなら、一度は経験したことがあるはずです。その根本的な原因の多くは、評価基盤の不在にあります。

Hacker Newsでは最近、agent-evalというOSSが話題になりました。Claude APIのスキルとしてエージェント評価（eval）を自作できるというアプローチで、「既製フレームワークを導入する」から「評価そのものを設計する」へと、業界の関心が移行していることを象徴するプロジェクトです。AutoML AgentsやVokerのような自動化ツールの台頭も同じ方向性を示しており、**「エージェントを評価する基盤をどう構築するか」**というテーマがMLエンジニアの間で急速に注目されています。

本記事では、evalフレームワークの設計原則、テストケースの自動生成、スコアリング方式、そして実務への組み込みまでを体系的に解説します。対象は業務エージェント・RAG・ツール呼び出し型エージェントの品質保証に取り組むMLエンジニアおよびAIプロダクト品質担当者です。

なぜ今「エージェント評価」が注目されているのか

エージェントは「正解が1つでない」システム

従来のソフトウェアテストは決定的です。入力Aを与えれば出力Bが返る。この前提が成り立つからこそ、ユニットテストが機能します。しかしAIエージェントはまったく異なる性質を持ちます。

非決定性: 同じ入力でも異なる出力が返りうる
マルチステップ: ツール呼び出しを複数回繰り返す過程全体を評価する必要がある
外部依存: 検索API・データベース・外部サービスの状態に結果が左右される

これらの特性から、「正解と比較する」という評価手法では不十分で、エージェントの振る舞い全体を評価する仕組みが必要になります。

自動化レイヤーが上がるほど、評価が律速になる

AutoML Agentsのように処理の自動化が高度になるほど、人間が逐一確認するコストは爆発的に増大します。評価を自動化しなければ、エージェント本体の自動化が空洞化してしまう。agent-evalが提示するのは、評価そのものをエージェント（Claudeのスキル）として構築するというメタなアプローチです。評価コードを書くのではなく、評価の設計をClaudeに委ねる――この発想の転換が、業界全体の議論を加速させています。

LLM評価フレームワークの設計原則

原則1: 評価は「プロダクト要件」から逆算する

評価指標を先に決めるのではなく、ビジネスKPIから逆算してください。

ビジネスKPI → 品質特性 → 評価指標

例えば問い合わせ対応エージェントの場合、「一次解決率の向上（KPI）」→「正確な情報を過不足なく提供する（品質特性）」→「正確性スコア・情報完全性スコア（評価指標）」という順序で定義します。この逆算なしに評価を設計すると、測定しやすい指標だけを最適化し、本当に重要な品質を見落とします。

原則2: 「軌跡（trajectory）」と「最終出力」を分けて測る

最終的な回答の品質だけを評価していると、問題が起きたときに原因を特定できません。実際の開発現場では、以下の両軸で評価することがベストプラクティスです。

最終出力評価: 回答の正確性・有用性・トーン
軌跡評価: ツール選択の適切さ・引数の正確さ・ステップ数・不要なリトライの有無

例えば「正しい答えが返ってきたが、6回もツールを呼び出していた」というケースは、最終出力だけを見れば合格ですが、コスト・レイテンシの観点では明らかに失敗です。

原則3: 決定的な部分は必ずルールベースで測る

「LLM-as-a-Judge（LLMを審査員として使う）」は強力ですが、コストがかかり再現性も低い。ルールベースで測れるものは徹底してルールベースで評価しましょう。

評価対象	推奨手法
JSONスキーマの適合性	スキーマバリデーション
特定キーワードの含有・非含有	正規表現
ツール呼び出し回数	カウント比較
応答時間・トークン数	数値比較
自由記述の有用性・トーン	LLM-as-a-Judge

LLM-as-a-Judgeは最後の手段と捉え、機械的に測れるものはすべてルールで済ませることが、評価基盤の安定性と低コスト化に直結します。

原則4: 評価は再現可能でなければ意味がない

「先週は85点だったのに今週は72点になった」――この差がモデルの品質低下なのか、プロンプトの変更なのか、評価環境の違いなのか区別できなければ、数値は信頼できません。再現性を担保するための管理事項は以下の通りです。

モデルバージョンの固定と記録
シード値の固定（可能な場合）
プロンプトのバージョニング（コードと同じGit管理）
評価結果と実験条件のひも付け（MLflow・W&B等）

原則5: 小さく始めて、失敗事例から育てる

最初から完璧な評価セットを作ろうとするのは禁物です。段階的に理解を深めていきましょう。まず20〜50件の失敗事例をケース化するだけで、評価基盤は動き始めます。本番で発生した失敗を自動的にテストケースに昇格させるループを構築することで、評価セットは自然に成熟していきます。

テストケース自動生成 ― 評価データセットをどう作るか

手作業でテストケースを作り続けることは、カバレッジと更新コストの両面でいずれ破綻します。実務で使える3つの生成アプローチを紹介します。

アプローチ1: 仕様書・ドキュメントからの合成

RAGエージェントであれば、ソースドキュメントを起点にQAペアを生成する手法が有効です。Claude APIを使い、「このドキュメントから答えられる質問とその根拠テキストを構造化出力で生成する」というプロセスを自動化できます。

import anthropic

client = anthropic.Anthropic()

def generate_test_cases(document: str, n: int = 10) -> list[dict]:
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=4096,
        tools=[{
            "name": "create_test_case",
            "description": "テストケースを生成する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "question": {"type": "string"},
                    "expected_answer": {"type": "string"},
                    "source_excerpt": {"type": "string"},
                    "difficulty": {"type": "string", "enum": ["easy", "medium", "hard"]}
                },
                "required": ["question", "expected_answer", "source_excerpt", "difficulty"]
            }
        }],
        system="あなたはテストケース生成の専門家です。ドキュメントから多様な難易度のQAペアを生成してください。",
        messages=[{
            "role": "user",
            "content": f"以下のドキュメントから{n}件のテストケースを生成してください:\n\n{document}"
        }]
    )
    # tool_useブロックからケースを抽出
    return [block.input for block in response.content if block.type == "tool_use"]

ポイントは構造化出力（tool use）を使って型付きでケースを取得することです。フリーテキストでパースするよりも信頼性が格段に高まります。

アプローチ2: 本番ログからのケース抽出

実トラフィックは最も信頼できるテストケースの源泉です。ログをクラスタリングして代表的なパターンを抽出し、PII（個人情報）を除去・匿名化した上でテストケースに変換します。「本番で実際に起きたこと」をそのままテストにすることで、評価セットの本番分布との乖離を最小化できます。

アプローチ3: 敵対的（adversarial）ケースの生成

正常系のケースだけでは、エージェントの堅牢性は測れません。以下のような「意地悪なケース」を意図的に生成することが重要です。

プロンプトインジェクション試行
曖昧・矛盾した指示
スコープ外の質問（「答えないのが正解」のケース）
極端に長い入力や異常な形式

「正しく断ること」もエージェントの品質です。adversarialケースを評価セットに必ず含めてください。

スコアリング設計 ― 「良し悪し」を数値にする

スコアラーの3分類と使い分け

分類	具体例	特徴
ルールベース	完全一致・正規表現・スキーマ検証	高速・低コスト・完全再現
統計・埋め込みベース	コサイン類似度・ROUGE	意味的な近さを測れるが閾値調整が難しい
LLM-as-a-Judge	有用性・トーン・複雑な推論	柔軟だが低速・高コスト・バイアスリスク

LLM-as-a-Judgeを信頼できる審査員にする

LLM-as-a-Judgeの最大の問題は再現性とバイアスです。実際の開発現場では以下の対策をセットで実施することをお勧めします。

ルーブリックの明文化: 「有用性とは何か」を具体的な基準で定義し、プロンプトに埋め込む
二値判定の集約: 5段階スコアより「良い/悪い」の二値判定を複数回集約する方が安定する
バイアス対策: 位置バイアス（先に提示した選択肢を選びやすい）・自己選好バイアス（自分のモデルに甘い）を意識し、ランダマイズで対策
審査員の検証: 人間のラベルとの一致率（agreement rate）で審査員自体を評価する

複数指標をどう束ねるか

加重平均は「失敗を隠す」ことに注意が必要です。例えば安全性スコアが0点でも、他の指標が高ければ平均は上がってしまいます。ベストプラクティスとして、指標を2種類に分けて管理することを推奨します。

ゲート指標: 絶対に下回ってはいけない条件（安全性・有害コンテンツ非生成など）
改善指標: 継続的に向上させる目標値（回答品質・効率性など）

また「平均スコア78点」という数字には注意が必要です。重要なのは絶対値ではなく、ベースラインや前バージョンとの相対比較です。p10（下位10パーセンタイル）を追跡することで、「大半は良いが一部が壊滅的」という状況を早期に検知できます。

エージェント品質保証 ― 評価をCI/CDに組み込む

評価の実行タイミング設計

評価をCI/CDに組み込むことで、リグレッションを自動検知できます。実行タイミングは3段階に分けるのが実務的です。

タイミング	規模	目的
PRマージ時	軽量スモークセット（〜50件）	明らかなリグレッションの即時検知
リリース前	フルevalセット	本番投入判断
本番稼働中	オンライン評価・カナリア	ドリフトの継続監視

プロンプト・モデル更新への追従

モデルのバージョンアップはサイレントなリグレッションを引き起こす最大の要因です。モデル更新のたびに差分評価フローを走らせ、以前のバージョンとのスコア比較を記録することが不可欠です。

また、プロンプトの変更はコードと同じくGit管理とコードレビューの対象にすることを強く推奨します。「ちょっとプロンプトを直した」という変更が品質に与える影響は、コードの変更と同等かそれ以上になることがあります。

Claude API活用 ― 評価基盤を安く速く回すために

プロンプトキャッシュで評価コストを削る

評価の実行では、ルーブリック・採点基準・共通コンテキストが全ケースで繰り返し送信されます。Claude APIのプロンプトキャッシュを活用することで、これらの共通部分のコストを大幅に削減できます。

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": rubric_text,  # 評価ルーブリック（長い）
            "cache_control": {"type": "ephemeral"}  # キャッシュ対象
        }
    ],
    messages=[{"role": "user", "content": f"以下の回答を評価してください:\n{response_to_evaluate}"}]
)

共通コンテキストをキャッシュすることで、大規模な評価実行時に最大90%のコスト削減が見込めます。

Batch APIで大規模evalを非同期実行する

レイテンシが問題にならない評価処理は、Batch APIを活用して非同期で実行することを推奨します。通常のAPIと比べてコストを大幅に抑えながら、数千件規模の評価を一括で処理できます。

モデルの使い分けで費用対効果を最大化する

すべての評価に最高性能のモデルを使う必要はありません。

上位モデル（Opusなど）: 複雑な推論・微妙なニュアンスの判定が必要な箇所
軽量モデル（Haiku）: 単純な分類・形式チェック・大量処理

また、審査員モデルと被評価エージェントのモデルは必ず分けてください。同じモデルを審査員として使うと自己選好バイアスが生じ、評価結果の信頼性が著しく低下します。

実務投入の勘どころ ― よくある失敗と回避策

失敗1: 評価セットが本番分布とズレている

手作業で作ったテストケースは往々にして「想定内の正常系」に偏ります。定期的に本番ログと評価セットの分布を比較し、カバーできていないパターンを補充するプロセスが必要です。

失敗2: スコアを上げること自体が目的化する（Goodhartの法則）

「測定される指標は目標でなくなる」というGoodhartの法則は、AI評価にも当てはまります。評価スコアの最適化がユーザーの本当の満足に直結しているか、定期的に人間による定性評価で確認することが重要です。

失敗3: 審査員のバージョンを変えて過去比較が壊れる

LLM-as-a-Judgeのモデルバージョンを変更すると、過去のスコアとの連続性が失われます。審査員モデルの更新は評価指標の再ベースライン化として扱い、過去との比較は慎重に行ってください。

失敗4: 評価基盤の運用コストが開発を圧迫する

評価基盤も「育てるもの」ですが、複雑化しすぎると維持コストで本業が圧迫されます。定期的にケースの重複・陳腐化を整理し、評価セットをスリムに保つことが長期的な持続性につながります。

導入ロードマップ（4ステップ）

フェーズ	期間	アクション
Step 1	1週目	本番の失敗事例20件をテストケース化
Step 2	2週目	ルールベーススコアラーだけでCI化
Step 3	3〜4週目	LLM-as-a-Judgeを追加し審査員の精度を検証
継続	以降	本番ログからケースを自動追加するループを整備

最初の一週間で完璧な評価基盤を目指す必要はありません。今日できる1アクションは「直近の失敗事例を5件書き出すこと」 ――それだけで、評価基盤への第一歩になります。

まとめ ― 評価基盤は「エージェント開発の速度そのもの」

評価がないエージェント開発は、テストがないリファクタリングと同じです。何かを変えるたびに壊れていないか不安になり、安心してデプロイできなくなります。

agent-evalが示した「評価をスキルとして設計する」という思想は、評価基盤をエージェント開発の一等市民として扱うべきだというメッセージです。設計原則の逆算、テストケースの自動生成、スコアリングのレイヤー化、CI/CDへの統合――これらを段階的に積み上げることで、エージェントの品質に自信を持てるようになり、開発そのものの速度が上がります。

本番で壊れてから直すのではなく、壊れる前に検知する。その仕組みを今日から一歩ずつ作っていきましょう。

本記事の技術情報は2026年8月時点のものです。Claude APIの仕様・料金体系は公式ドキュメントを参照してください。