ag2-evaluation

評価 — エージェントを実行、採点、追跡する

使用する場面

• AG2 の Agent を評価／テスト／ベンチマークする場合、またはリグレッション／CI ゲートを構築する場合
• 正確性、ツールの使用状況、コスト、主観的な品質について回答を採点する場合
• バージョン間で指標を追跡する場合（この変更で改善したか、リグレッションしたか）

2 つ以上のビルドを直接比較したり、リーダーボードで比較したりするには、ag2-eval-comparison を使用してください。

インストール

pip install "ag2[openai,tracing]"

run_agent は OpenTelemetry スパンから各タスクのトレースを再構築するため、tracing エクストラが必要です。コードを納品する前に、このインストールを実行してください。コマンドを実行できない場合は、正確な pip install コマンドを記載してください。

一連の流れ — データセット、エージェント、スコアラー、run_agent

import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.eval import Suite, run_agent
from ag2.eval.scorers import final_answer_matches

suite = Suite.from_list([
    {"task_id": "france", "inputs": {"input": "Capital of France?"}, "reference_outputs": {"answer": "Paris"}},
    {"task_id": "japan",  "inputs": {"input": "Capital of Japan?"},  "reference_outputs": {"answer": "Tokyo"}},
])
agent = Agent("geographer", prompt="Answer with the capital city.", config=OpenAIConfig(model="gpt-4o-mini"))

async def main():
    result = await run_agent(
        suite, agent=agent,
        scorers=[final_answer_matches(field="answer", matcher="contains")],
        store_dir="./runs",
    )
    print(result.summary())                            # the scorecard
    print(result.pass_rate("final_answer_matches"))    # 1.0

asyncio.run(main())

inputs["input"] はプロンプト、reference_outputs は正解の回答です（辞書です。トレースのみを確認する場合は省略してください）。各スコアラーは列となり、key で参照します。

スコアラー

スコアラーは 1 つの質問をします。戻り値の型によって集計方法が決まります。

return	aggregation	accessor
bool	合格率	result.pass_rate(key)
int / float	平均／p50／p95	result.score_stats(key)
str	値の件数	result.value_counts(key)

組み込みスコアラー（ag2.eval.scorers）：final_answer_matches(field=, matcher="contains"|"casefold"|"exact")、tool_called(name)、no_tool_errors()、token_budget(n)、failure_attribution(...)、agent_judge(...)。

カスタムスコアラー — 必要な引数を名前で宣言する関数にデコレーターを付けます（outputs、trace、reference_outputs、inputs、task）。

from ag2.eval import scorer

@scorer
def answered_briefly(outputs) -> bool:
    return len(outputs["body"]) < 100      # outputs["body"] = final answer text

agent_judge は == では確認できない品質を採点します（テスト対象のエージェントとは異なるモデルを使用してください）。

from ag2.eval.scorers import agent_judge
judge = agent_judge(OpenAIConfig(model="gpt-4o"), criterion="Helpful and accurate.", key="quality")

CI — 決定論的、API キー不要

モデルを TestConfig のカセット（タスクごとにあらかじめ用意した応答）に置き換えると、CI を無料で再現可能に実行できます。model_config は dict[task_id, ModelConfig] で、タスクごとに 1 つのカセットを指定します。また、そのタスクではエージェント自身の設定より優先されます。

from ag2.testing import TestConfig

agent = Agent("geographer", prompt="Answer with the capital city.")   # an Agent instance, not a factory

canned = {"france": TestConfig("Paris"), "japan": TestConfig("Tokyo")}
result = await run_agent(suite, agent=agent, scorers=scorers, model_config=canned, store_dir="./runs")
assert result.pass_rate("final_answer_matches") == 1.0      # the gate

保存、追跡、既存のトレースの採点

store_dir= を指定すると、実行ごとに JSON が 1 つ書き込まれます。過去の実行を読み込んでリグレッションを差分比較するか、エージェントを再実行せずに、すでにあるトレース（本番環境のテレメトリーなど）を採点できます。

from ag2.eval import load_run, evaluate_traces, DirectoryTraceSource

assert not result.diff(load_run("./runs/<run_id>.json")).regressions   # scorers that flipped pass -> fail
graded = await evaluate_traces(DirectoryTraceSource("./traces"), scorers=scorers, store_dir="./runs")

よくある落とし穴

• tracing エクストラがない — run_agent はトレースを再構築できません。ag2[<provider>,tracing] をインストールしてください。
• 戻り値の型と集計方法 — 合否には bool、統計には数値、カテゴリには str を使用します。結果はスコアラーの key で参照してください。
• 同じモデルで回答と判定を行う — agent_judge にバイアスがかかります。異なる判定モデルを使用してください。

さらに詳しく

• website/docs/user-guide/evaluation/ — getting-started、scorers（カタログ＋カスタムスコアラー＋戻り値の型に関するルール）、runs、persistence
• ag2-eval-comparison — リーダーボード（run_variants）＋直接比較（run_pairwise）