实时智能体评估

实时观看 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_type`	string	`anthropic_vision`	智能体使用的 LLM 提供方
`ai_config.model`	string	`claude-sonnet-4-20250514`	使用的模型
`ai_config.api_key`	string	环境变量	API key（用 `${VAR}` 语法）
`ai_config.max_tokens`	int	`4096`	每次 LLM 响应的最大 token 数
`ai_config.temperature`	float	`0.3`	采样温度
`system_prompt`	string	内置	智能体的 system prompt
`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：

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

标注者工作流程

标注者读完任务描述，点击 Start Agent
无头 Chromium 浏览器启动并连接到 LLM
智能体导航时截图实时推送到查看器——每一步显示截图、智能体的想法和采取的动作
标注者可以通过控制面板介入：
- Pause / Resume —— 在两步之间让智能体停下
- Send Instructions —— 在运行中往智能体的上下文里注入一条消息
- Take Over —— 切换到手动浏览控制
- Stop —— 提前结束会话
会话结束时（成功、失败或达到 max_steps），trace 会被保存，显示切换到评审模式
标注者填写标注 schema，评价智能体的表现

键盘快捷键

按键	动作
`Space`	暂停 / 恢复
`Escape`	结束会话

添加标注 schema

实时智能体显示可以和任意 Potato 标注 schema 组合：

yaml

annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes, fully"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "How efficiently did the agent work?"
    min_label: "Very inefficient"
    max_label: "Very efficient"
    scale: 5
  - annotation_type: text
    name: errors_observed
    question: "Describe any errors or unnecessary steps"
  - annotation_type: span
    name: error_steps
    question: "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
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "Rate the agent's efficiency"
    scale: 5
    min_label: "Very inefficient"
    max_label: "Very efficient"
  - annotation_type: text
    name: notes
    question: "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 会创建一条分支轨迹。两条分支都保留在输出中，产出的训练数据可用于：

过程奖励模型 —— 跨分支的步级正确性标签
偏好学习 —— 哪条分支产生了更好的结果
代码评审数据集 —— 比较不同做法的代码质量

实时智能体评估

环境要求

配置

配置参考

数据格式

标注者工作流程

键盘快捷键

添加标注 schema

完整示例

架构

Trace 导出

故障排查

编码智能体后端

Ollama（本地，无需 API key）

Anthropic API

Claude Agent SDK

回滚与检查点

分支轨迹

延伸阅读