ライブエージェント評価
AIエージェントの作業をリアルタイムで観察し、一時停止・指示・操作引き継ぎのコントロールで実行中にその振る舞いへアノテーションを付けます。Anthropic、Ollama、Claude SDKによるWebエージェントとコーディングエージェントに対応しています。
v2.4.0の新機能
ライブエージェント評価では、アノテーターがAIエージェントのWebブラウジングをリアルタイムで観察し、事後ではなく実行中にその振る舞いへアノテーションを付けられます。エージェントはスクリーンショットを撮り、それをビジョンLLMに送り、アクションを受け取って、ヘッドレスブラウザで実行します。各ステップはアノテーターの画面へライブでストリーミングされます。
要件
pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here設定
live_agent:
endpoint_type: anthropic_vision
ai_config:
model: claude-sonnet-4-20250514
api_key: ${ANTHROPIC_API_KEY}
max_tokens: 4096
temperature: 0.3
system_prompt: |
You are a web browsing agent. Complete the given task efficiently.
At each step, describe your thought, then output an action.
max_steps: 30
step_delay: 1.0
viewport:
width: 1280
height: 720
allow_takeover: true
allow_instructions: true
instance_display:
fields:
- key: task_description
type: text
label: "Task"
- key: agent_trace
type: live_agent
label: "Live Agent Session"
display_options:
show_overlays: true
show_filmstrip: true
show_thought: true
show_controls: true設定リファレンス
| オプション | 型 | 既定値 | 説明 |
|---|---|---|---|
endpoint_type | string | anthropic_vision | エージェントが使うLLMプロバイダー |
ai_config.model | string | claude-sonnet-4-20250514 | 使用するモデル |
ai_config.api_key | string | 環境変数 | APIキー(${VAR}の記法を使用) |
ai_config.max_tokens | int | 4096 | LLMの応答あたりの最大トークン数 |
ai_config.temperature | float | 0.3 | サンプリング温度 |
system_prompt | string | 組み込み | エージェントのシステムプロンプト |
max_steps | int | 30 | 停止するまでの最大ステップ数 |
step_delay | float | 1.0 | ステップ間の秒数 |
viewport.width | int | 1280 | ブラウザのビューポート幅 |
viewport.height | int | 720 | ブラウザのビューポート高さ |
allow_takeover | bool | true | アノテーターに手動操作を許可する |
allow_instructions | bool | true | アノテーターが実行中に指示を送れるようにする |
history_window | int | 5 | LLMのコンテキストに含める直近のステップ数 |
データ形式
各インスタンスにはタスクと開始URLを指定します。
{
"id": "task_001",
"task_description": "Search for climate change on Wikipedia and find the year it was first described",
"start_url": "https://en.wikipedia.org"
}アノテーターの作業手順
- アノテーターがタスクの説明を読み、Start Agentをクリックする
- ヘッドレスのChromiumブラウザが起動し、LLMに接続する
- エージェントが操作するにつれてスクリーンショットがビューアへライブでストリーミングされる。各ステップにはスクリーンショット、エージェントの思考、実行されたアクションが表示される
- アノテーターはコントロールパネルから操作できる
- Pause / Resume — ステップの切れ目でエージェントを止める
- Send Instructions — 実行中にエージェントのコンテキストへメッセージを挿入する
- Take Over — 手動のブラウジング操作に切り替える
- Stop — セッションを途中で終了する
- セッションが終わると(成功、失敗、または
max_steps到達)、トレースが保存され、表示がレビューモードに切り替わる - アノテーターがアノテーションスキーマに記入し、エージェントの性能を評価する
キーボードショートカット
| キー | 動作 |
|---|---|
Space | 一時停止/再開 |
Escape | セッションの停止 |
アノテーションスキーマの追加
ライブエージェント表示は、Potatoのどのアノテーションスキーマとも組み合わせられます。
annotation_schemes:
- annotation_type: radio
name: task_success
description: "Did the agent complete the task?"
labels:
- name: "Yes, fully"
- name: "Partially"
- name: "No"
- annotation_type: likert
name: efficiency
description: "How efficiently did the agent work?"
min_label: "Very inefficient"
max_label: "Very efficient"
- annotation_type: text
name: errors_observed
description: "Describe any errors or unnecessary steps"
- annotation_type: span
name: error_steps
description: "Mark any steps where the agent made an error"
labels:
- name: hallucination
- name: wrong_target
- name: unnecessary_action完全な例
task_name: "Live Agent Evaluation Study"
task_dir: "."
live_agent:
endpoint_type: anthropic_vision
ai_config:
model: claude-sonnet-4-20250514
api_key: ${ANTHROPIC_API_KEY}
max_tokens: 4096
temperature: 0.3
max_steps: 25
step_delay: 1.5
viewport:
width: 1280
height: 720
allow_takeover: true
allow_instructions: true
history_window: 5
data_files:
- "tasks.jsonl"
instance_display:
fields:
- key: task_description
type: text
label: "Task"
- key: agent_trace
type: live_agent
label: "Live Session"
display_options:
show_overlays: true
show_filmstrip: true
show_thought: true
show_controls: true
annotation_schemes:
- annotation_type: radio
name: task_success
description: "Did the agent complete the task?"
labels:
- name: "Yes"
- name: "Partially"
- name: "No"
- annotation_type: likert
name: efficiency
description: "Rate the agent's efficiency"
min_label: "Very inefficient"
max_label: "Very efficient"
- annotation_type: text
name: notes
description: "Notes on agent behavior"
output_annotation_dir: "output/"
output_annotation_format: "jsonl"アーキテクチャ
ライブエージェントはFlaskのバックグラウンドスレッドとして動きます。スクリーンショットと状態変化は、Server-Sent Events(SSE)でブラウザへストリーミングされます。アノテーターのコントロール(一時停止、指示、操作引き継ぎ、停止)は、バックグラウンドスレッドと同期するRESTエンドポイントを呼び出します。
Annotator (browser) <── SSE stream ── Flask Server ── Playwright ──► Headless Browser
──► REST control ─► ◄── LLM API ────► Claude Vision
スクリーンショットは{task_dir}/live_sessions/に保存され、フィルムストリップ表示のためにAPI経由で配信されます。
トレースのエクスポート
セッションが完了すると、Potatoは完全なトレースをweb_agent_trace互換のJSONとして自動的にエクスポートします。含まれる内容は次のとおりです。
- スクリーンショット、アクション、思考、観測を含むすべてのステップ
- アノテーターが実行中に送った指示
- タイムスタンプとエージェント設定のメタデータ
- アノテーターによる操作引き継ぎのイベント
つまり、完了したライブセッションは後から標準のWebエージェントアノテーションビューアで見返せます。
トラブルシューティング
「Playwright is not installed」 — pip install playwright && playwright install chromiumを実行してください。
「Anthropic API key required」 — 環境変数ANTHROPIC_API_KEYを設定するか、設定でapi_key: ${ANTHROPIC_API_KEY}を使ってください。
エージェントが遅い — 各ステップでLLMのAPI呼び出しが発生します(通常3〜10秒)。LLMの処理中は思考中のインジケーターが表示されます。長いセッションを速くするにはhistory_windowを小さくしてください。
スクリーンショットが読み込まれない — task_dirが書き込み可能で、サーバーに十分なディスク容量があるか確認してください。
コーディングエージェントのバックエンド
PotatoはWebブラウジングのエージェントに加えて、コーディングエージェントのライブ観察にも対応しています。バックエンドは3種類あります。
Ollama(ローカル、APIキー不要)
APIキーなしで、完全にローカルなモデルでコーディングエージェントの評価を実行します。
live_agent:
endpoint_type: coding_agent
backend: ollama
ai_config:
model: qwen2.5-coder:7b
host: "http://localhost:11434"
max_steps: 50
project_dir: "./workspace"Anthropic API
ツール使用を伴うClaudeでコーディングエージェントの評価を行います。
live_agent:
endpoint_type: coding_agent
backend: anthropic
ai_config:
model: claude-sonnet-4-20250514
api_key: ${ANTHROPIC_API_KEY}
max_tokens: 8192
max_steps: 50
project_dir: "./workspace"Claude Agent SDK
高度なコーディングエージェントのセッション向けに、Claude Codeの機能をそのまま使います。
live_agent:
endpoint_type: coding_agent
backend: claude_agent_sdk
ai_config:
max_turns: 50
project_dir: "./workspace"ロールバック、分岐、トラジェクトリのエクスポートを含む完全なリファレンスはライブコーディングエージェントを参照してください。
ロールバックとチェックポイント
コーディングエージェントのセッションでは、Potatoがファイル変更のたびにgitコミットを作成します。これにより次のことができます。
- 過去の任意のチェックポイントへのワンクリックのロールバック
- 分岐と再生 — 任意のチェックポイントから別のアプローチを試す
- レビュー用の、すべてのファイル状態の完全な履歴
チェックポイントは、セッションごとの専用gitブランチで自動的に管理されます。
分岐トラジェクトリ
アノテーターがロールバックして別のアプローチを試すと、Potatoは分岐トラジェクトリを作成します。両方の分岐が出力に保持され、次のような訓練データになります。
- プロセス報酬モデル — 分岐をまたいだステップ単位の正誤ラベル
- 選好学習 — どちらの分岐がより良い結果を出したか
- コードレビューのデータセット — アプローチ間でのコード品質の比較
参考資料
- ライブコーディングエージェント — Ollama、Anthropic、Claude SDKによるコーディングエージェントの観察
- Webエージェントアノテーション — 録画済みのエージェントトレースのレビュー
- エージェント型アノテーション — エージェントトレースの形式とコンバーターの概要
- プロセス報酬アノテーション — PRMの訓練データの収集
- AIサポート — アノテーション支援のためのLLM連携
実装の詳細については、ソースドキュメントを参照してください。