コンテンツへスキップ

エージェント型アノテーション

15種類のフレームワークのトレースを変換し、エージェントトレースの表示で描画して、トレースレベルとステップレベルでアノテーションすることで、Potato上のAIエージェントを評価します。

v2.3.0の新機能

Agentic annotation: a raw trace is converted, shown as thought, action, and observation cards, annotated at the step and trace level, and exportedHow agentic annotation works

エージェントは、ツール呼び出し、中間の推論、スクリーンショット、分岐する判断をまたいで、数十ステップにわたって動きます。エージェントが正しいことをしたかどうかを判断するには、そのすべてを画面に表示し、たどれるようにして、トレースレベルとステップレベルの両方で構造化された質問を用意する必要があります。

Potatoはこれを3つの段階で扱い、段階は意図的に分かれています。

  1. potato.trace_converter のCLIで、生のトレースをPotatoの標準形式に変換する
  2. エージェントのモダリティに合うタイプを選び、instance_display を通じて表示する
  3. トレースレベルまたはステップごとに、通常のアノテーションスキームでアノテーションする

agentic: という設定ブロックはありません。変換は、データに対して1回実行するコマンドであり、その後のすべては、どんなタスクにも書く通常の設定です。

トレースの変換

エージェントのログはフレームワークごとに異なります。コンバーターは、そのうち15種類を1つの標準JSONLファイルに正規化します。

bash
python -m potato.trace_converter \
  --input raw_traces.json \
  --input-format react \
  --output data/traces.jsonl

コンバーターのリファレンス

コンバーターソース形式
openaiOpenAI Chat CompletionsとAssistants APIのトレース
anthropictool_use ブロックを持つAnthropic Messages API
claude_codeClaude Codeや類似のコーディングエージェントのセッションログ
aiderAiderのペアプログラミングのチャット履歴
swebenchSWE-benchのタスクのトレース
swe_agent_trajectorySWE-Agentのトラジェクトリファイル
reactReAct形式の thought / action / observation ログ
langchainLangChainとLangSmithの実行エクスポート
langfuseLangfuseのオブザベーションエクスポート
otelGenAI規約を使うOpenTelemetryのエクスポート
mcpModel Context Protocolのセッション
multi_agentCrewAI、AutoGen、LangGraphのマルチエージェントログ
webarenaWebArenaとVisualWebArenaのトレース
web_agentMind2Webやcomputer-useを含む、ブラウザエージェントの記録
atifAgent Trace Interchange Format

--list-formats は、インストールされているバージョンから同じ一覧を表示します。両者が食い違う場合は、こちらを信頼してください。

自動検出

どの形式か分からない場合は、次のようにします。

bash
python -m potato.trace_converter \
  --input traces.json \
  --auto-detect \
  --output data/traces.jsonl

検出はフィールドの特徴を読み取り、順序が重要です。より具体的な形式を先に試すため、SWE-benchはReActより先に、AnthropicはOpenAIより先に調べます。形式が分かったら、明示的に指定してください。サンプルで正しく推測する検出器でも、コーパスの残りでは誤ることがあるためです。

カスタムコンバーター

一覧にないフレームワークには、基底のコンバーターをサブクラス化して登録します。コンバーターはPotatoが設定を読む前に動くため、これは設定ではなくPythonで行います。

python
from typing import Any, Dict, List, Optional
 
from potato.trace_converter.base import BaseTraceConverter, CanonicalTrace
from potato.trace_converter.registry import converter_registry
 
 
class MyConverter(BaseTraceConverter):
    format_name = "my_framework"
 
    def detect(self, data: Any) -> bool:
        return isinstance(data, list) and bool(data) and "log" in data[0]
 
    def convert(self, data: Any, options: Optional[Dict] = None) -> List[CanonicalTrace]:
        return [
            CanonicalTrace(
                id=str(run["run_id"]),
                task_description=run["task"],
                conversation=[
                    {"speaker": entry.get("kind", "Agent"), "text": entry["text"]}
                    for entry in run["log"]
                ],
            )
            for run in data
        ]
 
 
converter_registry.register(MyConverter())

トレースの表示

変換されたファイルは通常のデータなので、トレースは他のコンテンツと同じように宣言します。どの表示タイプを選ぶかが、主な設計上の判断です。

Agent Trace Display

ツールを使うエージェントの既定です。各ステップは、タイプごとに色分けされたカードとして描画されます。

yaml
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
 
    - key: conversation
      type: agent_trace
      label: "Agent trace"
      span_target: true
      display_options:
        show_step_numbers: true
        show_summary: true
        collapse_observations: false
        step_type_colors:
          thought: "#e8f4fd"
          action: "#fff3e0"
          observation: "#e8f5e9"

span_target: true を指定すると、スパンのスキームがトレース内のテキストにマークを付けられます。主張単位のハルシネーションのマーキングは、これで行います。

Dialogue Display

dialogue ディスプレイは、より軽量な選択肢で、インラインのステップごとの評価に対応しているのはこちらです。

yaml
instance_display:
  fields:
    - key: conversation
      type: dialogue
      label: "Agent trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true
        max_height: 600

Webエージェントのトレース

ブラウジングエージェントには、web_agent_trace がクリックと入力のオーバーレイ付きでスクリーンショットを描画します。

yaml
instance_display:
  fields:
    - key: trace
      type: web_agent_trace
      label: "Browsing session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        filmstrip_size: 150
        screenshot_max_width: 900
        show_thought: true
        show_element_info: true

コーディングのトレース

コーディングエージェントには、coding_trace が差分、ターミナルのブロック、ファイルの読み取りを描画します。

yaml
instance_display:
  fields:
    - key: steps
      type: coding_trace
      label: "Coding session"
      span_target: true
      display_options:
        diff_view: unified
        show_file_tree: true
        show_reasoning: true
        terminal_theme: dark
        collapse_long_outputs: true
        max_output_lines: 50

完全なリファレンスは、コーディングエージェントのアノテーションを参照してください。

会話型エージェント

interactive_chat は、会話を描画し、ターンごとの評価を受け付けます。

yaml
instance_display:
  fields:
    - key: messages
      type: interactive_chat
      label: "Conversation"
      display_options:
        show_turn_numbers: true
        alternating_shading: true

スクリーンショットのシーケンス

トレースがほとんど画像である場合は、トレースの表示よりも gallery のほうが単純です。

yaml
instance_display:
  fields:
    - key: screenshots
      type: gallery
      label: "Screenshots"
      display_options:
        layout: horizontal
        thumbnail_size: 300
        zoomable: true

トレースレベルのスキーム

これらには、エージェント特有のものは何もありません。通常のスキームであり、どれにも name と description が必要です。

yaml
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task?"
    labels:
      - name: success
        tooltip: "Fully completed correctly"
      - name: partial
        tooltip: "Partially completed, or completed with errors"
      - name: failure
        tooltip: "Not completed"
    sequential_key_binding: true
 
  - annotation_type: likert
    name: efficiency
    description: "How efficient was the agent's path?"
    size: 5
    min_label: "Very inefficient"
    max_label: "Optimal"
 
  - annotation_type: radio
    name: safety
    description: "Did the agent take any unsafe action?"
    labels:
      - name: safe
      - name: minor_concern
      - name: major_violation

エラー分類体系

MAST分類体系は、エージェントの失敗モードに共通の語彙を与えます。これによって、トレースをまたいでエラーをまとめられるようになります。

yaml
  - annotation_type: multiselect
    name: mast_errors
    description: "Select every failure mode observed in this trace"
    labels:
      - name: disobey_task_spec
        tooltip: "Does not follow the task specification"
      - name: step_repetition
        tooltip: "Repeats the same action unnecessarily"
      - name: loss_of_history
        tooltip: "Forgets prior context"
      - name: unaware_of_termination
        tooltip: "Does not recognize when to stop"
      - name: fail_to_clarify
        tooltip: "Fails to ask for needed clarification"
      - name: task_derailment
        tooltip: "Goes off track from the main task"
      - name: reasoning_action_mismatch
        tooltip: "Reasoning contradicts the action taken"
      - name: premature_termination
        tooltip: "Stops before the task is complete"
      - name: incomplete_verification
        tooltip: "Does not verify the result"
      - name: no_errors
        tooltip: "No errors observed"

トレース内の主張にマークを付ける

表示フィールドに span_target: true を指定すると、スパンのスキームがテキストそのものにマークを付けます。

yaml
  - annotation_type: span
    name: hallucination_spans
    description: "Mark claims the trace does not support"
    labels:
      - name: hallucination
        tooltip: "Claim not grounded in the observations"
      - name: incorrect_fact
        tooltip: "Factually incorrect statement"

ステップレベルの評価

ステップごとの判断を集める仕組みは2つあり、向いている質問が異なります。

インラインのターンごとの評価

per_turn_ratings は、dialogue または interactive_chat ディスプレイの、一致する各ターンの横に評価ウィジェットを置きます。speakers を絞ると、ウィジェットは判断の対象となるターンにだけ付きます。

yaml
display_options:
  show_turn_numbers: true
  per_turn_ratings:
    speakers: ["Agent (Action)"]
    schema_name: "action_correctness"
    scheme:
      type: likert
      size: 3
      labels: ["Wrong", "Right"]

ステップごとに複数の判断が必要な場合は、scheme の代わりに schemes を使います。それぞれが独自のアノテーション列を持ちます。

yaml
display_options:
  per_turn_ratings:
    speakers: ["Agent (Action)"]
    schemes:
      - schema_name: action_correctness
        scheme:
          type: likert
          size: 3
          labels: ["Wrong", "Right"]
      - schema_name: reasoning_quality
        scheme:
          type: likert
          size: 5
          labels: ["Poor", "Excellent"]

データからの動的な行

トレースの長さがまちまちな場合は、options_from_data が、設定ではなくアイテムのフィールドから、行列の行を作ります。

yaml
  - annotation_type: multirate
    name: step_ratings
    description: "Rate each step"
    options_from_data: step_summaries
    labels: ["Incorrect", "Questionable", "Correct"]
json
{"id": "trace_001", "step_summaries": ["Search for flights", "Compare prices", "Book cheapest"]}

専用の評価タイプ

エージェントの作業のために作られたアノテーションタイプが4つあります。

trajectory_eval は、2階層の分類体系、重大度の重み、実行中のスコアで、ステップごとにエラーを局所化します。error_types はカテゴリのリストで、それぞれがサブタイプのフラットな subtypes リストを持ちます。

yaml
  - annotation_type: trajectory_eval
    name: step_eval
    description: "Mark each step and classify any error"
    steps_key: steps
    step_text_key: content
    error_types:
      - name: reasoning
        subtypes:
          - logical_error
          - incorrect_assumption
      - name: action
        subtypes:
          - wrong_tool
          - wrong_arguments
          - premature_termination
    severities:
      - name: minor
        weight: -1
      - name: major
        weight: -5
    show_score: true

トラジェクトリ評価ガイドを参照してください。

rubric_eval は、複数の基準で実行を同時に採点します。scale_labels はリストで、スケールの各点に1つのラベルを持ちます。

yaml
  - annotation_type: rubric_eval
    name: agent_rubric
    description: "Rate this run on each criterion"
    scale_points: 5
    scale_labels: ["Very poor", "Poor", "Acceptable", "Good", "Excellent"]
    criteria:
      - name: correctness
        description: "Did the agent produce the correct result?"
      - name: efficiency
        description: "Did the agent take an efficient path?"
      - name: safety
        description: "Did the agent avoid unsafe actions?"
    show_overall: true

ルーブリック評価のチュートリアルを参照してください。

pairwise は、2つの実行を、バイナリ、スケール、多次元のモードで比較します。

yaml
  - annotation_type: pairwise
    name: agent_comparison
    description: "Which run was better?"
    mode: multi_dimension
    items_key: runs
    labels: ["Agent A", "Agent B"]
    dimensions:
      - name: correctness
        description: "Which result is correct?"
        allow_tie: true
      - name: efficiency
        description: "Which took the shorter path?"
        allow_tie: true

ペアワイズ比較ガイドを参照してください。

process_reward は、プロセス報酬モデルを訓練するためのステップごとの報酬ラベルを集めます。

yaml
  - annotation_type: process_reward
    name: step_rewards
    description: "Click the first step where the agent went wrong"
    mode: first_error
    steps_key: steps
    step_text_key: content

プロセス報酬アノテーションを参照してください。

ライブでのエージェント観察

live_agent は、アノテーターが見ている間にエージェントを実行し、介入するためのコントロールを備えます。これはトップレベルのブロックです。

yaml
live_agent:
  endpoint_type: anthropic_vision   # or openai_vision, ollama_vision
  max_steps: 30
  step_delay: 1.0
  history_window: 5
  timeout: 60
  viewport:
    width: 1280
    height: 720
  system_prompt: "Complete the task using the browser."
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
 
instance_display:
  fields:
    - key: task
      type: live_agent
      label: "Live session"
      display_options:
        show_controls: true
        allow_instructions: true
        allow_takeover: true
        show_overlays: true

ライブエージェント評価とライブコーディングエージェントを参照してください。

エージェントプロキシ

ライブの会話タスクでは、agent_proxy がアノテーションインターフェースとエージェントの間に入り、やり取りを記録します。これもトップレベルのブロックで、type がバックエンドを選びます。

yaml
agent_proxy:
  type: openai
  model: "gpt-4o"
  api_key: ${OPENAI_API_KEY}
  system_prompt: "You are a helpful customer service agent."
  temperature: 0.7
  max_tokens: 1024
 
  sandbox:
    max_steps: 20
    max_session_seconds: 600
    rate_limit_per_minute: 10
    request_timeout_seconds: 60

設定は、タイプの名前を付けたネストされたキーの下ではなく、ブロックの直下に置きます。

HTTPプロキシは、自分のエージェントサーバーに転送し、テンプレートを受け取るのではなく、送信と読み取りに使うフィールドを指定します。

yaml
agent_proxy:
  type: http
  url: "https://my-agent.example.com/chat"
  headers:
    Authorization: "Bearer ${AGENT_API_KEY}"
  message_key: message
  response_key: response
  session_id_key: session_id
  send_history: true
  history_key: messages

エコープロキシは、あらかじめ用意した応答を返します。エージェントがまだない段階で、インターフェースを作ってテストするには、これで十分です。

yaml
agent_proxy:
  type: echo
  responses:
    - "Thanks, let me look into that."
    - "I have found your order."

sandbox ブロックはすべてのプロキシタイプに適用され、ライブセッションを制限する唯一のものです。これがないと、止まったエージェントは、アノテーターが諦めるまで動き続けます。

完全な例

yaml
annotation_task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
 
    - key: conversation
      type: agent_trace
      label: "Agent trace"
      span_target: true
      display_options:
        show_step_numbers: true
        show_summary: true
        collapse_observations: true
        step_type_colors:
          thought: "#e8f4fd"
          action: "#fff3e0"
          observation: "#e8f5e9"
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    description: "Did the agent complete the task?"
    labels:
      - name: success
      - name: partial
      - name: failure
    sequential_key_binding: true
 
  - annotation_type: likert
    name: efficiency
    description: "How efficient was the agent's path?"
    size: 5
    min_label: "Very inefficient"
    max_label: "Optimal"
 
  - annotation_type: multiselect
    name: mast_errors
    description: "Select every failure mode observed"
    labels:
      - name: step_repetition
      - name: task_derailment
      - name: reasoning_action_mismatch
      - name: premature_termination
      - name: no_errors
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    rows: 3
    label_requirement:
      required: false
 
output_annotation_dir: "annotation_output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

データを用意して、サーバーを起動します。

bash
python -m potato.trace_converter --input raw_traces.json --input-format react --output data/traces.jsonl
potato start config.yaml -p 8000

参考資料

実装の詳細については、ソースドキュメントを参照してください。