ag2-eval-comparison

評価 — ビルドの比較（バリアントとペアワイズ）

使用する場面

• N 個のモデル／プロンプト／設定をリーダーボードで順位付けする → run_variants
• どちらが優れているかを直接比較する → pairwise_judge（LLM）を指定した run_pairwise、または human_pairwise（人）

単一のエージェントを実行して採点する場合（スコアラー、CI、永続化）には、ag2-evaluation を使用してください。

インストール

pip install "ag2[openai,tracing]"

必須です。コードを提供する前に、このインストールを実行してください。コマンドを実行できない場合は、正確な pip install コマンドを記載してください。

リーダーボード — run_variants

Variants は、名前付きの**Agent インスタンス**のマッピングと、変更した対象を示す axis ラベルを保持する、不変のデータクラスです。異なる点を 1 つだけ設定したエージェント（設定、プロンプト、ツール、ミドルウェアなど）をそれぞれ作成し、それ以外は固定したうえで採点し、順位付けします。

from ag2 import Agent
from ag2.config import OpenAIConfig, GeminiConfig
from ag2.eval import Variants, run_variants
from ag2.eval.scorers import agent_judge

board = await run_variants(
    suite,
    variants=Variants(
        {
            "gpt-4o": Agent("a", prompt="Answer helpfully.", config=OpenAIConfig("gpt-4o")),
            "flash":  Agent("a", prompt="Answer helpfully.", config=GeminiConfig("gemini-3-flash-preview")),
        },
        axis="config",                  # label for what was varied (used in summary)
    ),
    scorers=[agent_judge(OpenAIConfig("gpt-4o"), criterion="Helpful and accurate.", key="quality")],
    store_dir="runs",
    repeats=5,                          # optional: N runs per variant for stability
)
print(board.summary("quality"))         # ranked leaderboard
board.best("quality")                   # winning variant name (None if tied)
board.leaderboard("quality")            # list[LeaderboardRow] — variant, score, n, rank
board.results["gpt-4o"]                 # each variant's full RunResult

エージェント間で変更する対象は自由です。axis にその内容を示すラベルを設定します（例："config"、"prompt"、"tools"）。同点の場合は同じ順位になります。通常、3 者同点になる場合は評価で差を見分けられていません。評価を難しくするか、ジャッジを使って品質を採点してください。

直接比較（LLM）— run_pairwise + pairwise_judge

比較器はタスクごとに勝者を選びます。pairwise_judge はペアを両方の順序で提示し、一貫した結果の場合にのみ勝利としてカウントします。一貫しない場合は引き分けとし、提示順によるバイアスを取り除きます。

from ag2.eval import run_pairwise
from ag2.eval.scorers import pairwise_judge

result = await run_pairwise(
    suite, variant_a=agent_v1, variant_b=agent_v2,
    comparators=[pairwise_judge(OpenAIConfig("gpt-4o"), criterion="more helpful answer", key="quality")],
    store_dir="runs",
)
wr = result.win_rate("quality")         # B's win-rate
print(wr.rate, wr.ci, wr.wins, wr.losses, wr.ties)   # ties count 0.5; ci is a Wilson 95% interval
print(result.flips("quality"))          # int — count of cases where the two orders disagreed

variant_a／variant_b は**Agent インスタンス**で、comparators= は複数の比較器を受け取るイテラブルです。result.agreement("quality", "human") は、2 つの比較器キー間の Agreement（.rate、.cohen_kappa など）を返します。バリアントとは異なるジャッジモデルを使用してください。

直接比較（人）— human_pairwise

同じ単位を人が判定します。ペアはブラインド化され、順序はランダム化されます。デフォルトではペアを表示し、1／2／tie の入力を読み取ります。UI から投票を収集する場合は、独自の非同期 ask(task, response_1, response_2) を渡してください（"1"、"2"、または "tie" を返します）。

from ag2.eval.scorers import human_pairwise

async def ask(task, response_1, response_2) -> str:
    return await my_ui.compare(task.inputs["input"], response_1, response_2)   # "1" / "2" / "tie"

result = await run_pairwise(suite, variant_a=agent_v1, variant_b=agent_v2,
                            comparators=[human_pairwise(key="quality", ask=ask)], store_dir="runs")

大規模に実施する場合は、ブラインド化されたマニフェストをエクスポートし、任意のツールでラベル付けしてからインポートします。evaluate_pairwise は run_pairwise の採点のみを行うバージョンで、既存の 2 つのトレースソースを task_id でペアにします。

from ag2.eval import evaluate_pairwise, DirectoryTraceSource
from ag2.eval.scorers import export_pairwise_cases, human_labels

a, b = DirectoryTraceSource("runs/champion"), DirectoryTraceSource("runs/challenger")
await export_pairwise_cases(a, b, criteria=["more helpful"], out="labels.jsonl", suite=suite)   # blinded JSONL
# a person adds  "preferred": "1" | "2" | "tie"  per line, then:
result = await evaluate_pairwise(a, b, suite=suite, store_dir="runs",
                                 comparators=[human_labels("labels.jsonl", criterion="more helpful", key="helpful")])

マニフェストではどのモデルがどれかが隠されます。first_variant フィールドを使うと、human_labels のためにその情報を明らかにできます。

よくある落とし穴

• ジャッジがバリアントのモデルと同じ — 自己優遇バイアスが生じます。別のジャッジモデルを使用してください。
• 少数のペアで勝率だけを提示する — wr.ci（Wilson）を報告してください。n が小さいと、信頼区間が 50% をまたぐ場合があります。
• エージェントではなくファクトリーを渡す — run_variants（variants=Variants({name: Agent(...)})）と run_pairwise（variant_a=／variant_b=）が受け取るのは、ビルド用の呼び出し可能オブジェクトではなく、Agent インスタンスです。タスクごとにモデルを変えるには、エージェントを再構築するのではなく、model_config=（dict[task_id, ModelConfig]）を使用してください。バイアスのない判定のため、pairwise_judge のデフォルトの入れ替えを維持してください（swap=False は設定しないでください）。

詳しく知る

• website/docs/user-guide/evaluation/ — variants（Variants のマッピングと axis）、pairwise（比較器、勝率、ブラインド化されたラベル付け）
• ag2-evaluation — 単一エージェントの実行／採点、スコアラー、CI、永続化