Skip to content

ライブエージェント評価

AIエージェントの作業をリアルタイムで観察し、一時停止・指示・操作引き継ぎのコントロールで実行中にその振る舞いへアノテーションを付けます。Anthropic、Ollama、Claude SDKによるWebエージェントとコーディングエージェントに対応しています。

v2.4.0の新機能

ライブエージェント評価では、アノテーターがAIエージェントのWebブラウジングをリアルタイムで観察し、事後ではなく実行中にその振る舞いへアノテーションを付けられます。エージェントはスクリーンショットを撮り、それをビジョンLLMに送り、アクションを受け取って、ヘッドレスブラウザで実行します。各ステップはアノテーターの画面へライブでストリーミングされます。

要件

bash
pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

設定

yaml
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_typestringanthropic_visionエージェントが使うLLMプロバイダー
ai_config.modelstringclaude-sonnet-4-20250514使用するモデル
ai_config.api_keystring環境変数APIキー(${VAR}の記法を使用)
ai_config.max_tokensint4096LLMの応答あたりの最大トークン数
ai_config.temperaturefloat0.3サンプリング温度
system_promptstring組み込みエージェントのシステムプロンプト
max_stepsint30停止するまでの最大ステップ数
step_delayfloat1.0ステップ間の秒数
viewport.widthint1280ブラウザのビューポート幅
viewport.heightint720ブラウザのビューポート高さ
allow_takeoverbooltrueアノテーターに手動操作を許可する
allow_instructionsbooltrueアノテーターが実行中に指示を送れるようにする
history_windowint5LLMのコンテキストに含める直近のステップ数

データ形式

各インスタンスにはタスクと開始URLを指定します。

json
{
  "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"
}

アノテーターの作業手順

  1. アノテーターがタスクの説明を読み、Start Agentをクリックする
  2. ヘッドレスのChromiumブラウザが起動し、LLMに接続する
  3. エージェントが操作するにつれてスクリーンショットがビューアへライブでストリーミングされる。各ステップにはスクリーンショット、エージェントの思考、実行されたアクションが表示される
  4. アノテーターはコントロールパネルから操作できる
    • Pause / Resume — ステップの切れ目でエージェントを止める
    • Send Instructions — 実行中にエージェントのコンテキストへメッセージを挿入する
    • Take Over — 手動のブラウジング操作に切り替える
    • Stop — セッションを途中で終了する
  5. セッションが終わると(成功、失敗、またはmax_steps到達)、トレースが保存され、表示がレビューモードに切り替わる
  6. アノテーターがアノテーションスキーマに記入し、エージェントの性能を評価する

キーボードショートカット

キー動作
Space一時停止/再開
Escapeセッションの停止

アノテーションスキーマの追加

ライブエージェント表示は、Potatoのどのアノテーションスキーマとも組み合わせられます。

yaml
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

完全な例

yaml
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エンドポイントを呼び出します。

text
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キーなしで、完全にローカルなモデルでコーディングエージェントの評価を実行します。

yaml
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でコーディングエージェントの評価を行います。

yaml
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の機能をそのまま使います。

yaml
live_agent:
  endpoint_type: coding_agent
  backend: claude_agent_sdk
  ai_config:
    max_turns: 50
  project_dir: "./workspace"

ロールバック、分岐、トラジェクトリのエクスポートを含む完全なリファレンスはライブコーディングエージェントを参照してください。

ロールバックとチェックポイント

コーディングエージェントのセッションでは、Potatoがファイル変更のたびにgitコミットを作成します。これにより次のことができます。

  • 過去の任意のチェックポイントへのワンクリックのロールバック
  • 分岐と再生 — 任意のチェックポイントから別のアプローチを試す
  • レビュー用の、すべてのファイル状態の完全な履歴

チェックポイントは、セッションごとの専用gitブランチで自動的に管理されます。

分岐トラジェクトリ

アノテーターがロールバックして別のアプローチを試すと、Potatoは分岐トラジェクトリを作成します。両方の分岐が出力に保持され、次のような訓練データになります。

  • プロセス報酬モデル — 分岐をまたいだステップ単位の正誤ラベル
  • 選好学習 — どちらの分岐がより良い結果を出したか
  • コードレビューのデータセット — アプローチ間でのコード品質の比較

参考資料

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