エージェント型アノテーション
15種類のフレームワークのトレースを変換し、エージェントトレースの表示で描画して、トレースレベルとステップレベルでアノテーションすることで、Potato上のAIエージェントを評価します。
v2.3.0の新機能
How agentic annotation works
エージェントは、ツール呼び出し、中間の推論、スクリーンショット、分岐する判断をまたいで、数十ステップにわたって動きます。エージェントが正しいことをしたかどうかを判断するには、そのすべてを画面に表示し、たどれるようにして、トレースレベルとステップレベルの両方で構造化された質問を用意する必要があります。
Potatoはこれを3つの段階で扱い、段階は意図的に分かれています。
potato.trace_converterのCLIで、生のトレースをPotatoの標準形式に変換する- エージェントのモダリティに合うタイプを選び、
instance_displayを通じて表示する - トレースレベルまたはステップごとに、通常のアノテーションスキームでアノテーションする
agentic: という設定ブロックはありません。変換は、データに対して1回実行するコマンドであり、その後のすべては、どんなタスクにも書く通常の設定です。
トレースの変換
エージェントのログはフレームワークごとに異なります。コンバーターは、そのうち15種類を1つの標準JSONLファイルに正規化します。
python -m potato.trace_converter \
--input raw_traces.json \
--input-format react \
--output data/traces.jsonlコンバーターのリファレンス
| コンバーター | ソース形式 |
|---|---|
openai | OpenAI Chat CompletionsとAssistants APIのトレース |
anthropic | tool_use ブロックを持つAnthropic Messages API |
claude_code | Claude Codeや類似のコーディングエージェントのセッションログ |
aider | Aiderのペアプログラミングのチャット履歴 |
swebench | SWE-benchのタスクのトレース |
swe_agent_trajectory | SWE-Agentのトラジェクトリファイル |
react | ReAct形式の thought / action / observation ログ |
langchain | LangChainとLangSmithの実行エクスポート |
langfuse | Langfuseのオブザベーションエクスポート |
otel | GenAI規約を使うOpenTelemetryのエクスポート |
mcp | Model Context Protocolのセッション |
multi_agent | CrewAI、AutoGen、LangGraphのマルチエージェントログ |
webarena | WebArenaとVisualWebArenaのトレース |
web_agent | Mind2Webやcomputer-useを含む、ブラウザエージェントの記録 |
atif | Agent Trace Interchange Format |
--list-formats は、インストールされているバージョンから同じ一覧を表示します。両者が食い違う場合は、こちらを信頼してください。
自動検出
どの形式か分からない場合は、次のようにします。
python -m potato.trace_converter \
--input traces.json \
--auto-detect \
--output data/traces.jsonl検出はフィールドの特徴を読み取り、順序が重要です。より具体的な形式を先に試すため、SWE-benchはReActより先に、AnthropicはOpenAIより先に調べます。形式が分かったら、明示的に指定してください。サンプルで正しく推測する検出器でも、コーパスの残りでは誤ることがあるためです。
カスタムコンバーター
一覧にないフレームワークには、基底のコンバーターをサブクラス化して登録します。コンバーターはPotatoが設定を読む前に動くため、これは設定ではなく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
ツールを使うエージェントの既定です。各ステップは、タイプごとに色分けされたカードとして描画されます。
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 ディスプレイは、より軽量な選択肢で、インラインのステップごとの評価に対応しているのはこちらです。
instance_display:
fields:
- key: conversation
type: dialogue
label: "Agent trace"
span_target: true
display_options:
show_turn_numbers: true
alternating_shading: true
max_height: 600Webエージェントのトレース
ブラウジングエージェントには、web_agent_trace がクリックと入力のオーバーレイ付きでスクリーンショットを描画します。
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 が差分、ターミナルのブロック、ファイルの読み取りを描画します。
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 は、会話を描画し、ターンごとの評価を受け付けます。
instance_display:
fields:
- key: messages
type: interactive_chat
label: "Conversation"
display_options:
show_turn_numbers: true
alternating_shading: trueスクリーンショットのシーケンス
トレースがほとんど画像である場合は、トレースの表示よりも gallery のほうが単純です。
instance_display:
fields:
- key: screenshots
type: gallery
label: "Screenshots"
display_options:
layout: horizontal
thumbnail_size: 300
zoomable: trueトレースレベルのスキーム
これらには、エージェント特有のものは何もありません。通常のスキームであり、どれにも name と description が必要です。
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分類体系は、エージェントの失敗モードに共通の語彙を与えます。これによって、トレースをまたいでエラーをまとめられるようになります。
- 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 を指定すると、スパンのスキームがテキストそのものにマークを付けます。
- 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 を絞ると、ウィジェットは判断の対象となるターンにだけ付きます。
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 を使います。それぞれが独自のアノテーション列を持ちます。
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 が、設定ではなくアイテムのフィールドから、行列の行を作ります。
- annotation_type: multirate
name: step_ratings
description: "Rate each step"
options_from_data: step_summaries
labels: ["Incorrect", "Questionable", "Correct"]{"id": "trace_001", "step_summaries": ["Search for flights", "Compare prices", "Book cheapest"]}専用の評価タイプ
エージェントの作業のために作られたアノテーションタイプが4つあります。
trajectory_eval は、2階層の分類体系、重大度の重み、実行中のスコアで、ステップごとにエラーを局所化します。error_types はカテゴリのリストで、それぞれがサブタイプのフラットな subtypes リストを持ちます。
- 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つのラベルを持ちます。
- 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つの実行を、バイナリ、スケール、多次元のモードで比較します。
- 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 は、プロセス報酬モデルを訓練するためのステップごとの報酬ラベルを集めます。
- 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 は、アノテーターが見ている間にエージェントを実行し、介入するためのコントロールを備えます。これはトップレベルのブロックです。
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 がバックエンドを選びます。
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プロキシは、自分のエージェントサーバーに転送し、テンプレートを受け取るのではなく、送信と読み取りに使うフィールドを指定します。
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エコープロキシは、あらかじめ用意した応答を返します。エージェントがまだない段階で、インターフェースを作ってテストするには、これで十分です。
agent_proxy:
type: echo
responses:
- "Thanks, let me look into that."
- "I have found your order."sandbox ブロックはすべてのプロキシタイプに適用され、ライブセッションを制限する唯一のものです。これがないと、止まったエージェントは、アノテーターが諦めるまで動き続けます。
完全な例
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データを用意して、サーバーを起動します。
python -m potato.trace_converter --input raw_traces.json --input-format react --output data/traces.jsonl
potato start config.yaml -p 8000参考資料
- コーディングエージェントのアノテーション - 差分、ターミナル出力、ファイルツリー
- プロセス報酬アノテーション - ステップごとの報酬ラベル
- コードレビューのアノテーション - インラインコメントと判定
- ライブコーディングエージェント - ロールバック付きのリアルタイム観察
- ライブエージェント評価 - Webエージェントのリアルタイム観察
- Webエージェントのアノテーション - 事前に記録されたブラウジングトレース
- エクスポート形式 - アノテーションを取り出す
実装の詳細については、ソースドキュメントを参照してください。