AIエージェントの評価：エージェントトレースの人間アノテーション完全ガイド

自動メトリクスはエージェントがどのくらいの頻度で成功するかを教えてくれます。人間評価は、なぜ失敗するのか、どこで間違えるのか、どのように修正するかを教えてくれます。このガイドでは、Potatoのエージェント型アノテーション機能を使用して、AIエージェントの完全な人間評価パイプラインをセットアップする手順を説明します。

Webを検索して質問に答えるReActスタイルのエージェントを評価します。このガイドの終わりまでに、以下が完了します：

エージェントトレースをPotatoにインポート
エージェントトレース表示を設定
全体およびステップごとのアノテーションスキーマを設定
アノテーションタスクを実行
構造化された評価結果をエクスポート

前提条件

Potato 2.3.0以降をインストールしてください：

bash

pip install --upgrade potato-annotation

評価するエージェントトレースも必要です。このガイドではReActトレースを使用しますが、サポートされている12の形式のいずれにも同じアプローチが適用できます。

ステップ1：エージェントトレースの準備

ReActトレースは、Thought、Action、Observationステップのシーケンスです。以下は最小限の例です。data/traces.jsonlにファイルを作成してください：

json

{
  "trace_id": "trace_001",
  "task": "What is the capital of Australia and what is its population?",
  "trace": [
    {"type": "thought", "content": "I need to find the capital of Australia and its population. Let me search for this."},
    {"type": "action", "content": "search", "action_input": "capital of Australia"},
    {"type": "observation", "content": "Canberra is the capital city of Australia. It was chosen as the capital in 1908 as a compromise between Sydney and Melbourne."},
    {"type": "thought", "content": "The capital is Canberra. Now I need to find its population."},
    {"type": "action", "content": "search", "action_input": "Canberra population 2025"},
    {"type": "observation", "content": "Canberra has a population of approximately 467,000 as of 2025, making it the eighth-largest city in Australia."},
    {"type": "thought", "content": "I now have both pieces of information. The capital of Australia is Canberra with a population of approximately 467,000."},
    {"type": "action", "content": "finish", "action_input": "The capital of Australia is Canberra, with a population of approximately 467,000 as of 2025."}
  ],
  "ground_truth": "Canberra, approximately 467,000"
}

JSONLファイルの各行は1つの完全なエージェントトレースです。traceフィールドにはステップバイステップのログが含まれます。taskフィールドはエージェントに依頼されたタスクです。

トレース形式に関する注意

OpenAI function-callingトレースの場合、形式は異なります：

json

{
  "trace_id": "oai_001",
  "task": "Find cheap flights from NYC to London",
  "messages": [
    {"role": "user", "content": "Find cheap flights from NYC to London"},
    {"role": "assistant", "content": null, "tool_calls": [{"function": {"name": "search_flights", "arguments": "{\"from\": \"NYC\", \"to\": \"LHR\"}"}}]},
    {"role": "tool", "name": "search_flights", "content": "{\"flights\": [{\"airline\": \"BA\", \"price\": 450}, {\"airline\": \"AA\", \"price\": 520}]}"},
    {"role": "assistant", "content": "I found flights from NYC to London. The cheapest is British Airways at $450."}
  ]
}

Potatoのコンバーターがこれらの違いを処理します。正しいコンバーター名を指定するだけです。

ステップ2：プロジェクト設定の作成

config.yamlを作成してください：

yaml

task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
# --- Agentic annotation settings ---
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    show_timestamps: false
    render_json: true
    syntax_highlight: true

これによりPotatoは以下を行います：

data/traces.jsonlからトレースを読み込み
ReActコンバーターを使用してtraceフィールドを解析
色分けされたステップカードを持つエージェントトレース表示でトレースを表示

ステップ3：アノテーションスキーマの設計

エージェント評価では通常、トレースレベルの判断（エージェントは成功したか？）とステップレベルの判断（各ステップは正しかったか？）の両方が必要です。両方を追加しましょう。

config.yamlに以下を追加してください：

yaml

annotation_schemes:
  # --- Trace-level schemas ---
 
  # 1. Task success (the most important metric)
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels:
      - "Success"
      - "Partial Success"
      - "Failure"
    label_requirement:
      required: true
    sequential_key_binding: true
 
  # 2. Answer correctness (if the task has a ground truth)
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Cannot Determine"
    label_requirement:
      required: true
 
  # 3. Efficiency rating
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path to the answer?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient (many unnecessary steps)"
      3: "Average"
      5: "Optimal (no wasted steps)"
 
  # 4. Free-text notes
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  # --- Step-level schemas ---
 
  # 5. Per-step correctness
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct and useful?"
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  # 6. Per-step error type (only shown when step is not correct)
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "What type of error occurred?"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

このスキーマ設計により以下が得られます：

高レベル分析のための二値の成功/失敗メトリック
最終回答を評価するための正確性評価
エージェント戦略を比較するための効率スコア
エージェントがどこで間違えるかを正確に特定するためのステップごとの評価
ステップに問題がある場合にのみ表示される条件付きエラー分類

ステップ4：出力設定とサーバーの起動

config.yamlに出力設定を追加してください：

yaml

output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
# Optional: also export to Parquet for analysis
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

参考用の完全なconfig.yaml：

yaml

task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 400
    show_step_numbers: true
    render_json: true
    syntax_highlight: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent successfully complete the task?"
    labels: ["Success", "Partial Success", "Failure"]
    label_requirement:
      required: true
    sequential_key_binding: true
 
  - annotation_type: radio
    name: answer_correctness
    description: "Is the agent's final answer factually correct?"
    labels: ["Correct", "Partially Correct", "Incorrect", "Cannot Determine"]
    label_requirement:
      required: true
 
  - annotation_type: likert
    name: efficiency
    description: "Did the agent use an efficient path?"
    min: 1
    max: 5
    labels:
      1: "Very Inefficient"
      3: "Average"
      5: "Optimal"
 
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations"
    label_requirement:
      required: false
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    description: "Was this step correct?"
    rating_type: radio
    labels: ["Correct", "Partially Correct", "Incorrect", "Unnecessary"]
 
  - annotation_type: per_turn_rating
    name: error_type
    target: agentic_steps
    description: "Error type"
    rating_type: multiselect
    labels:
      - "Wrong tool/action"
      - "Wrong arguments"
      - "Hallucinated information"
      - "Reasoning error"
      - "Redundant step"
      - "Premature termination"
      - "Other"
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"
 
parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd

サーバーを起動してください：

bash

potato start config.yaml -p 8000

ブラウザでhttp://localhost:8000を開いてください。

ステップ5：アノテーションワークフロー

アノテーターがトレースを開くと、以下が表示されます：

タスク説明（元のユーザークエリ）が上部に表示
ステップカードがフルエージェントトレースをタイプ別に色分けして表示：
- 紫色のカードは思考/推論
- 青色のカードはアクション/ツール呼び出し
- 緑色のカードはオブザベーション/結果
- 赤色のカードはエラー
ステップごとの評価コントロールが各ステップカードの隣に表示
トレースレベルのスキーマがトレース表示の下に表示

典型的なワークフロー：

タスク説明を読んで、エージェントが何をすべきだったかを理解する
トレースステップを順に確認し、各ステップを評価する
「Partially Correct」または「Incorrect」と評価したステップについて、エラータイプを選択する
トレース全体を評価する（成功、正確性、効率）
必要に応じてメモを追加する
送信して次のトレースに進む

アノテーターへのヒント

折りたたまれたオブザベーションを展開して、エージェントが情報を正しく処理したか確認する
タスクの成功を評価する前に、最終回答をグラウンドトゥルス（利用可能な場合）と比較する
「Unnecessary」ステップは「Incorrect」とは別に評価する -- 不要なステップは労力を浪費するがエラーを導入しない
ステップタイムラインサイドバーを使用して、長いトレースの特定のステップにジャンプする

ステップ6：結果の分析

アノテーション後、結果をプログラム的に分析します。

pandasによる基本分析

python

import pandas as pd
import json
 
# Load annotations
annotations = []
with open("output/annotations.jsonl") as f:
    for line in f:
        annotations.append(json.loads(line))
 
df = pd.DataFrame(annotations)
 
# Task success rate
success_counts = df.groupby("annotations").apply(
    lambda x: x.iloc[0]["annotations"]["task_success"]
).value_counts()
print("Task Success Distribution:")
print(success_counts)
 
# Average efficiency rating
efficiency_scores = [
    a["annotations"]["efficiency"]
    for a in annotations
    if "efficiency" in a["annotations"]
]
print(f"\nAverage Efficiency: {sum(efficiency_scores) / len(efficiency_scores):.2f}")

ステップレベルのエラー分析

python

# Collect all step-level errors
error_counts = {}
for ann in annotations:
    step_errors = ann["annotations"].get("error_type", {})
    for step_idx, errors in step_errors.items():
        for error in errors:
            error_counts[error] = error_counts.get(error, 0) + 1
 
print("Error Type Distribution:")
for error, count in sorted(error_counts.items(), key=lambda x: -x[1]):
    print(f"  {error}: {count}")

DuckDBによる分析（Parquet経由）

python

import duckdb
 
# Overall success rate
result = duckdb.sql("""
    SELECT value, COUNT(*) as count
    FROM 'output/parquet/annotations.parquet'
    WHERE schema_name = 'task_success'
    GROUP BY value
    ORDER BY count DESC
""")
print(result)

ステップ7：スケールアップ

より大規模な評価プロジェクト（数百〜数千のトレース）では、以下の設定を検討してください：

複数アノテーター

アノテーター間一致度のために、トレースごとに複数のアノテーターを割り当て：

yaml

annotation_task_config:
  total_annotations_per_instance: 3
  assignment_strategy: random

プリビルトスキーマの使用

クイックセットアップには、Potatoのプリビルトエージェント評価スキーマを使用：

yaml

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_efficiency

品質管理

品質モニタリングのためにゴールドスタンダードインスタンスを有効化：

yaml

phases:
  training:
    enabled: true
    data_file: "data/training_traces.jsonl"
    passing_criteria:
      min_correct: 4
      total_questions: 5

他のエージェントタイプへの適用

OpenAI Function Calling

yaml

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace

Anthropic Tool Use

yaml

agentic:
  enabled: true
  trace_converter: anthropic
  display_type: agent_trace

マルチエージェントシステム（CrewAI/AutoGen）

yaml

agentic:
  enabled: true
  trace_converter: multi_agent
  display_type: agent_trace
  multi_agent:
    agent_converters:
      researcher: react
      writer: anthropic
      reviewer: openai

Webブラウジングエージェント

Webエージェントの場合、Web Agent Displayに切り替えてください：

yaml

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
    filmstrip:
      enabled: true

専用ガイドについてはWebブラウジングエージェントのアノテーションを参照してください。

まとめ

AIエージェントの人間評価には専門的なツールが必要です。Potatoのエージェント型アノテーションシステムは以下を提供します：

あらゆるフレームワークからのトレースを正規化する12のコンバーター
ツール使用、Webブラウジング、会話エージェントに最適化された3つの表示タイプ
ステップレベル評価のためのターンごとの評価
一般的な評価次元をカバーする9つのプリビルトスキーマ
効率的な下流分析のためのParquetエクスポート

重要な洞察は、エージェント評価は単に「エージェントは正しい答えを得たか？」ではなく、「エージェントはすべてのステップで正しく推論したか？」であるということです。ステップごとのアノテーションは、集約メトリクスでは見逃されるエラーパターンを明らかにします。

参考資料

エージェント型アノテーションのドキュメント
Webブラウジングエージェントのアノテーション
Solo Mode -- エージェント型アノテーションと人間-LLM協調評価の組み合わせ
Best-Worst Scaling -- エージェント出力の比較ランキング
Parquetエクスポート -- 分析のための効率的なエクスポート