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

専用のトレース表示、12種類の形式コンバーター、専用アノテーションスキーマでAIエージェントを評価します。

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

v2.3.0の新機能

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

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

あらゆる主要フレームワークからのエージェントログを統一形式に正規化する12種類のトレース形式コンバーター
異なるエージェントモダリティ（ツール使用、Webブラウジング、チャット）に最適化された3種類の専用表示タイプ
最も一般的なエージェント評価次元をカバーする9つのプリビルトアノテーションスキーマ

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

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

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

コンバーター	ソース形式	抽出される主要フィールド
`openai`	OpenAI Assistants API / function callingログ	messages、tool_calls、function results
`anthropic`	Anthropic Claude tool_use / Messages API	content blocks、tool_use、tool_result
`swebench`	SWE-benchタスクトレース	patch、test results、trajectory
`opentelemetry`	OpenTelemetryスパンエクスポート（JSON）	spans、attributes、events、parent-child
`mcp`	Model Context Protocolセッション	tool definitions、call/response pairs
`multi_agent`	CrewAI / AutoGen / LangGraphマルチエージェントログ	agent roles、delegation、message passing
`langchain`	LangChainコールバックトレース	chain runs、LLM calls、tool invocations
`langfuse`	LangFuseオブザベーションエクスポート	generations、spans、scores
`react`	ReActスタイルのThought/Action/Observationログ	thought、action、action_input、observation
`webarena`	WebArena / VisualWebArenaトレースJSON	actions、screenshots、DOM snapshots、URLs
`atif`	Agent Trace Interchange Format（ATIF）	steps、observations、metadata
`raw_web`	生のブラウザ記録（HAR + スクリーンショット）	requests、responses、screenshots、timings

設定

プロジェクト設定でコンバーターを指定してください：

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は3つの専用表示タイプのいずれかを使用してトレースを描画します。それぞれ異なるエージェントモダリティに最適化されています。

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システム（下記参照）を介してアノテーターを実行中のエージェントに接続します。アノテーターはエージェントと会話し、結果の会話をアノテーションします。

ターンごとの評価

対話やマルチステップ評価では、トレース全体だけでなく（またはそれに加えて）個々のターンの評価が必要になることがよくあります。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_success`	radio	部分的なクレジットオプション付きの二値成功/失敗
`agent_step_correctness`	per_turn_rating (radio)	ステップごとの正確/不正確/不要の評価
`agent_error_taxonomy`	per_turn_rating (multiselect)	12カテゴリのエラー分類（間違ったツール、ハルシネーションなど）
`agent_safety`	radio + text	重大度スケール付き安全性違反の検出
`agent_efficiency`	likert	エージェントが効率的なパスを使用したか評価
`agent_instruction_following`	likert	元のユーザー指示への準拠を評価
`agent_explanation_quality`	likert	エージェントの推論/説明の品質を評価
`agent_web_action_correctness`	per_turn_rating (radio)	ステップごとのWebアクション評価（正しいターゲット、正しいアクションタイプ）
`agent_conversation_quality`	multirate	多次元チャット品質（有用性、正確性、トーン、安全性）

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

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

参考資料

AIエージェントの評価：完全ガイド -- 完全なエージェント評価プロジェクトのウォークスルー
Webブラウジングエージェントのアノテーション -- スクリーンショットとオーバーレイを使用したWebエージェント評価ガイド
Solo Mode -- エージェント型アノテーションと人間-LLM協調ラベリングの組み合わせ
対話のターンごとの評価 -- 追加のターンごと評価オプション
エクスポート形式 -- エージェント評価データのエクスポート

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