Skip to content

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

13種類のトレース形式コンバーター、5種類の表示タイプ、ツール使用・Webブラウジング・コーディング・チャットエージェント向けのプリビルトスキーマでPotato上のAIエージェントを評価します。PRMとルーブリック評価を含みます。

v2.3.0の新機能

AIエージェントは、Webの閲覧、コードの記述、APIの呼び出し、サブエージェントのオーケストレーションなど、複雑なマルチステップタスクにますますデプロイされています。しかし、エージェントが実際に正しいことをしたかを評価するには、従来のアノテーションツールではサポートできない粒度での人間の判断が必要です。1つのエージェントトレースには、数十のステップ、ツール呼び出し、中間推論、スクリーンショット、分岐判断が含まれることがあります。アノテーターはこのすべてのコンテキストを確認し、効率的にナビゲートし、トレースレベルと個々のステップレベルの両方で構造化された評価を提供する必要があります。

Potatoのエージェント型アノテーションシステムは、4つの機能でこれに対応します。

  1. あらゆる主要フレームワークのエージェントログを統一形式に正規化する13種類のトレース形式コンバーター
  2. 異なるエージェントモダリティ（ツール使用、Webブラウジング、コーディング、チャット、ライブ観察）に最適化された5種類の専用表示タイプ
  3. 最も一般的なエージェント評価次元をカバーする9つのプリビルトアノテーションスキーマ
  4. 高度な評価のための4種類の専用アノテーションタイプ：トラジェクトリ評価、ルーブリック評価、ペアワイズ比較、プロセス報酬アノテーション

トレース形式コンバーター

エージェントトレースはフレームワークによって大きく異なる形式で提供されます。Potatoは13種類のコンバーターを搭載しており、これらを統一された内部表現に正規化します。設定でコンバーターを指定するか、Potatoに形式を自動検出させることができます。

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

コンバーターソース形式抽出される主要フィールド
openaiOpenAI Assistants API / function callingログmessages、tool_calls、function results
anthropicAnthropic Claude tool_use / Messages APIcontent blocks、tool_use、tool_result
swebenchSWE-benchタスクトレースpatch、test results、trajectory
opentelemetryOpenTelemetryスパンエクスポート（JSON）spans、attributes、events、parent-child
mcpModel Context Protocolセッションtool definitions、call/response pairs
multi_agentCrewAI / AutoGen / LangGraphマルチエージェントログagent roles、delegation、message passing
langchainLangChainコールバックトレースchain runs、LLM calls、tool invocations
langfuseLangFuseオブザベーションエクスポートgenerations、spans、scores
reactReActスタイルのThought/Action/Observationログthought、action、action_input、observation
webarenaWebArena / VisualWebArenaトレースJSONactions、screenshots、DOM snapshots、URLs
atifAgent Trace Interchange Format（ATIF）steps、observations、metadata
raw_web生のブラウザ記録（HAR + スクリーンショット）requests、responses、screenshots、timings
claude_codeClaude Code / Aider / コーディングエージェントtool_use blocks、diffs、terminal output

設定

プロジェクト設定でコンバーターを指定します。

yaml
agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

トレースファイルの各行は、生のエージェントトレースを含むJSONオブジェクトである必要があります。残りはコンバーターが処理します。

異なるエージェントが異なるフレームワークを使用するマルチエージェントトレースの場合、エージェントごとにコンバーターを指定できます。

yaml
agentic:
  enabled: true
  trace_converter: multi_agent
  trace_file: "data/multi_agent_traces.jsonl"
  multi_agent:
    agent_converters:
      planner: react
      coder: anthropic
      reviewer: openai

自動検出

どのコンバーターを使用すべきかわからない場合は、trace_converter: autoを設定します。

yaml
agentic:
  enabled: true
  trace_converter: auto
  trace_file: "data/traces.jsonl"

Potatoは最初の10件のトレースを検査し、フィールドシグネチャに基づいて最も一致するコンバーターを選択します。信頼度が80%を下回る場合は警告がログに記録されます。その場合はコンバーターを明示的に指定してください。

カスタムコンバーター

お使いのエージェントフレームワークがリストにない場合は、Pythonでコンバーターを記述できます。

python
# converters/my_converter.py
from potato.agentic.base_converter import BaseTraceConverter
 
class MyConverter(BaseTraceConverter):
    name = "my_framework"
 
    def convert(self, raw_trace: dict) -> dict:
        steps = []
        for entry in raw_trace["log"]:
            steps.append({
                "type": entry.get("kind", "action"),
                "content": entry["text"],
                "timestamp": entry.get("ts"),
                "metadata": entry.get("extra", {}),
            })
        return {"steps": steps}

設定に登録します。

yaml
agentic:
  trace_converter: custom
  custom_converter: "converters/my_converter.py:MyConverter"

表示タイプ

トレースが変換されると、Potatoは5種類の専用表示タイプのいずれかを使用してトレースを描画します。それぞれ異なるエージェントモダリティに最適化されています。

1. Agent Trace Display

ツールを使用するエージェント（OpenAI function calling、Anthropic tool_use、ReAct、LangChainなど）のデフォルト表示です。各ステップをステップタイプ別に色分けしたカードとして描画します。

yaml
agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Color coding for step types
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Collapsible sections
    collapse_observations: true
    collapse_threshold: 500    # characters before auto-collapsing
 
    # Step numbering
    show_step_numbers: true
    show_timestamps: true
 
    # Tool call rendering
    render_json: true          # pretty-print JSON arguments
    syntax_highlight: true     # highlight code in observations

機能：

  • タイプ（思考、アクション、オブザベーション、エラー）を示す色付きの左ボーダーを持つステップカード
  • 長いオブザベーションやツール出力のための折りたたみセクション（閾値は設定可能）
  • ツール呼び出し引数と構造化レスポンスのJSONプリティプリント
  • オブザベーション内のコードブロックのシンタックスハイライト
  • トレース全体を一覧できるステップタイムラインサイドバー
  • 長いトレースのためのステップジャンプナビゲーション

2. Web Agent Trace Display

Webブラウジングエージェント（WebArena、VisualWebArena、生のブラウザ記録）向けに専用に構築されています。エージェントがクリック、入力、スクロールした場所を示すSVGオーバーレイ付きのスクリーンショットを描画します。

yaml
agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlay for agent actions
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair, or arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # highlight for text input fields
      scroll_indicator: true
 
    # Filmstrip view
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # DOM snapshot display
    show_dom_snapshot: false        # optional raw DOM view
    show_url_bar: true
    show_action_description: true

機能：

  • フルサイズ表示とズームを備えたスクリーンショットギャラリー
  • クリックターゲット（赤い円）、テキスト入力領域（青いハイライト）、スクロール方向を示すSVGオーバーレイ
  • すべてのスクリーンショットをサムネイルとして表示し、すばやくナビゲートできる下部のフィルムストリップビュー
  • 各スクリーンショットの下に表示されるアクション説明テキスト（例：「'Add to Cart'ボタンをクリック」）
  • 各ステップで現在のページURLを表示するURLバー
  • ページコンテンツを変更するステップの前後比較

3. Interactive Chat Display

会話エージェントとチャットボットの評価用です。2つのサブモードをサポートします。アノテーターがリアルタイムでエージェントと対話するライブチャットと、記録済みの会話を評価するトレースレビューです。

yaml
agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # or "live_chat"
 
    # Trace review settings
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" or "message"
 
    # Live chat settings (when mode: live_chat)
    live_chat:
      proxy: openai             # agent proxy to use
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Common settings
    show_role_labels: true
    role_colors:
      user: "#3b82f6"
      assistant: "#6E56CF"
      system: "#6b7280"
      tool: "#22c55e"

トレースレビューモードは、メッセージごとのトークン数とレイテンシ（オプション）を含む記録済みの会話を描画します。アノテーターは個々のターンまたは会話全体を評価できます。

ライブチャットモードは、Agent Proxyシステム（下記参照）を介してアノテーターを実行中のエージェントに接続します。アノテーターはエージェントと会話し、その結果生じた会話をアノテーションします。

4. Coding Trace Display

コーディングエージェントのセッション（Claude Code、Aider、SWE-Agent）向けに専用に構築されています。シンタックスハイライト付きのコード差分、ダークブロックでのターミナル出力、行番号付きのファイル読み取りを描画します。

yaml
agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified           # unified or split
    terminal_theme: dark
    show_file_tree: true
    collapse_long_output: true
    collapse_threshold: 50        # lines
    show_line_numbers: true
    syntax_highlight: true

機能：

  • 編集操作の赤/緑ハイライトを備えた統合差分ビュー
  • bash/shellコマンド出力のためのダークターミナルブロック
  • ファイル読み取り操作のための行番号付きコードブロック
  • セッション中に操作されたすべてのファイルを表示するファイルツリーサイドバー
  • 冗長なターミナルやファイルコンテンツのための折りたたみ可能な長い出力

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

5. Live Agent Display

人間の介入のためのコントロールを備えた、AIエージェントのリアルタイム観察です。Webブラウジングエージェントとコーディングエージェントをサポートします。

yaml
agentic:
  enabled: true
  display_type: live_agent

機能：

  • Server-Sent Eventsを介したエージェントアクションのリアルタイムストリーミング
  • ステップ間でのエージェントの一時停止/再開
  • タスクの途中でエージェントをリダイレクトするための指示の送信
  • 手動コントロールの引き継ぎ
  • 以前の任意のチェックポイントへのロールバック（コーディングエージェントはgitベースのチェックポイントを使用）
  • 任意のチェックポイントから異なる指示での分岐と再生

設定の詳細についてはライブエージェント評価およびライブコーディングエージェントを参照してください。

高度なアノテーションタイプ

ターンごとの評価やプリビルトスキーマに加えて、Potatoには構造化されたエージェント評価のための4種類の専用アノテーションタイプが含まれています。

トラジェクトリ評価（trajectory_eval）

階層的なエラー分類と重大度スコアリングを用いた、ステップごとのエラー局所化です。各ステップには正確性の評価、エラータイプ、重大度レベル、およびオプションの根拠が付与されます。実行中のスコアトラッカーは重大度に基づいて減点されます。

yaml
annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_eval
    error_taxonomy:
      reasoning:
        - logical_error
        - incorrect_assumption
      action:
        - wrong_tool
        - wrong_arguments
        - premature_termination
    severity_weights:
      minor: -1
      major: -5
      critical: -10

完全なガイドについてはトラジェクトリ評価のブログ記事を参照してください。

ルーブリック評価（rubric_eval）

MT-Benchスタイルの複数基準グリッド評価です。カスタム基準と評価尺度を定義します。アノテーターは各基準を独立して評価します。

yaml
annotation_schemes:
  - annotation_type: rubric_eval
    name: agent_rubric
    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?"
    scale: 5
    scale_labels:
      1: "Very Poor"
      3: "Acceptable"
      5: "Excellent"

セットアップ手順についてはルーブリック評価のチュートリアルを参照してください。

ペアワイズ比較

2つのエージェントトレースを3つのモードで並べて比較します。

  • バイナリ：クリックしてAまたはBを選択（引き分けはオプション）
  • スケール：「Aが大幅に優れている」から「Bが大幅に優れている」までのスライダー
  • 多次元：次元ごとに独立したA/B/引き分け、根拠の入力が必須
yaml
annotation_schemes:
  - annotation_type: pairwise
    name: agent_comparison
    mode: multi_dimension
    dimensions:
      - correctness
      - efficiency
      - safety
    require_justification: true
    allow_tie: true

3つすべてのモードについてはペアワイズ比較ガイドを参照してください。

プロセス報酬アノテーション

プロセス報酬モデルのトレーニングに最適化された、ステップごとのバイナリ正確性アノテーションです。2つのモードがあります。first-error（最初の誤ったステップをクリックし、残りは自動的にマークされる）とper-step（各ステップを独立して評価する）です。

yaml
annotation_schemes:
  - annotation_type: process_reward
    name: prm
    mode: first_error    # or per_step

完全なリファレンスについてはプロセス報酬アノテーションを参照してください。

ターンごとの評価

対話やマルチステップ評価では、トレース全体ではなく（またはそれに加えて）個々のターンの評価が必要になることがよくあります。Potatoはどの表示タイプでもターンごとのアノテーションをサポートしています。

yaml
annotation_schemes:
  # Overall trace rating
  - annotation_type: likert
    name: overall_quality
    description: "Rate the overall quality of this agent trace"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      5: "Excellent"
 
  # Per-turn ratings
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # binds to trace steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: step_explanation
    description: "Explain any issues with this step"
    target: agentic_steps
    rating_type: text
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

ターンごとの評価は各ステップカードの横にインラインで表示されます。conditionalブロックを使用すると、特定の評価が選択された場合にのみフォローアップの質問を表示でき、インターフェースをクリーンに保てます。

ターンごとの出力形式

ターンごとのアノテーションはステップインデックス付きで保存されます。

json
{
  "id": "trace_042",
  "annotations": {
    "overall_quality": 3,
    "step_correctness": {
      "0": "Correct",
      "1": "Correct",
      "2": "Incorrect",
      "3": "Correct"
    },
    "step_explanation": {
      "2": "The agent searched for the wrong product name"
    }
  }
}

Agent Proxyシステム

アノテーターがリアルタイムでエージェントと対話するライブ評価タスクのために、Potatoはエージェントプロキシレイヤーを提供します。プロキシはアノテーションインターフェースとエージェントバックエンドの間に位置し、後でレビューするために完全な会話をログに記録します。

yaml
agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http, or echo
 
    # OpenAI proxy
    openai:
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
      system_prompt: "You are a helpful customer service agent."
      temperature: 0.7
      max_tokens: 1024

プロキシタイプ

OpenAIプロキシはOpenAI互換APIにメッセージを転送します。

yaml
agent_proxy:
  type: openai
  openai:
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
    system_prompt: "You are a helpful assistant."
    temperature: 0.7

HTTPプロキシは任意のHTTPエンドポイント（独自のエージェントサーバー）にメッセージを転送します。

yaml
agent_proxy:
  type: http
  http:
    url: "https://my-agent.example.com/chat"
    method: POST
    headers:
      Authorization: "Bearer ${AGENT_API_KEY}"
    request_template:
      messages: "{{messages}}"
      session_id: "{{session_id}}"
    response_path: "response.content"
    timeout_seconds: 30

Echoプロキシはユーザーのメッセージをそのまま返します（テストとUI開発に便利）。

yaml
agent_proxy:
  type: echo
  echo:
    prefix: "[Echo] "
    delay_ms: 500

プリビルトアノテーションスキーマ

Potatoにはエージェント評価のために専用に設計された9つのアノテーションスキーマが搭載されています。そのまま使用するか、独自のスキーマの出発点として使用できます。

スキーマタイプ説明
agent_task_successradio部分的なクレジットオプション付きのバイナリ成功/失敗
agent_step_correctnessper_turn_rating (radio)ステップごとの正確/不正確/不要の評価
agent_error_taxonomyper_turn_rating (multiselect)12カテゴリのエラー分類（間違ったツール、ハルシネーション、ループなど）
agent_safetyradio + text重大度スケール付きの安全性違反の検出
agent_efficiencylikertエージェントが効率的なパスを使用したかを評価
agent_instruction_followinglikert元のユーザー指示への準拠を評価
agent_explanation_qualitylikertエージェントの推論/説明の品質を評価
agent_web_action_correctnessper_turn_rating (radio)ステップごとのWebアクション評価（正しいターゲット、正しいアクションタイプ）
agent_conversation_qualitymultirate多次元のチャット品質（有用性、正確性、トーン、安全性）

名前でプリビルトスキーマを読み込みます。

yaml
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy

または、プリセットをカスタムスキーマと組み合わせます。

yaml
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Custom schema alongside presets
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations about this agent trace"
    label_requirement:
      required: false

完全な例：ReActエージェントの評価

以下は、ステップごとの評価付きでReActスタイルのエージェントトレースを評価するための完全な設定です。

yaml
# project config
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/react_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
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: 300
    show_step_numbers: true
    render_json: true
 
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_efficiency
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

サンプル入力データ（data/react_traces.jsonl）：

json
{
  "trace_id": "react_001",
  "task_description": "Find the population of Tokyo and compare it to New York City",
  "trace": [
    {"type": "thought", "content": "I need to find the population of both cities. Let me search for Tokyo first."},
    {"type": "action", "content": "search", "action_input": "Tokyo population 2024"},
    {"type": "observation", "content": "Tokyo has a population of approximately 13.96 million in the city proper..."},
    {"type": "thought", "content": "Now I need to find New York City's population."},
    {"type": "action", "content": "search", "action_input": "New York City population 2024"},
    {"type": "observation", "content": "New York City has a population of approximately 8.34 million..."},
    {"type": "thought", "content": "Tokyo (13.96M) has about 67% more people than NYC (8.34M)."},
    {"type": "action", "content": "finish", "action_input": "Tokyo has ~13.96 million people vs NYC's ~8.34 million, making Tokyo about 67% larger by population."}
  ]
}

サーバーを起動します。

bash
potato start config.yaml -p 8000

参考資料

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