Skip to content

即時智慧體評估

即時觀看 AI 智慧體工作，並在執行過程中標註其行為，支援暫停、下達指令和接管控制。支援 web 智慧體和編碼智慧體，可選 Anthropic、Ollama 和 Claude SDK。

v2.4.0 新增

即時智慧體評估讓標註者即時看著 AI 智慧體瀏覽網頁，並在它執行的過程中標註它的行為，而不是事後再看。智慧體截圖，把截圖發給視覺 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 key（用 ${VAR} 語法）
ai_config.max_tokensint4096每次 LLM 響應的最大 token 數
ai_config.temperaturefloat0.3取樣溫度
system_promptstring內建智慧體的 system prompt
max_stepsint30停止前的最大步數
step_delayfloat1.0每步之間的間隔秒數
viewport.widthint1280瀏覽器視口寬度
viewport.heightint720瀏覽器視口高度
allow_takeoverbooltrue允許標註者手動接管
allow_instructionsbooltrue允許標註者在執行中傳送指令
history_windowint5納入 LLM 上下文的最近步數

資料格式

每條實例提供任務和起始 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），trace 會被儲存，顯示切換到評審模式
  6. 標註者填寫標註 schema，評價智慧體的表現

鍵盤快捷鍵

按鍵動作
Space暫停 / 恢復
Escape結束會話

新增標註 schema

即時智慧體顯示可以和任意 Potato 標註 schema 組合：

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 提供給膠片條檢視。

Trace 匯出

會話結束後，Potato 會自動把完整 trace 匯出為相容 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 也支援即時觀察編碼智慧體。有三種後端可選：

Ollama（本地，無需 API key）

用完全本地的模型做編碼智慧體評估，不需要 API key。

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 會建立一條分支軌跡。兩條分支都保留在輸出中，產出的訓練資料可用於：

  • 過程獎勵模型 —— 跨分支的步級正確性標籤
  • 偏好學習 —— 哪條分支產生了更好的結果
  • 程式碼評審資料集 —— 比較不同做法的程式碼品質

延伸閱讀

有關實現詳情，請參閱源文件。