Skip to content

Web 智能体标注

在 Potato 中审查网页浏览智能体的 trace：胶片条导航、SVG 叠加层（点击、边界框、鼠标轨迹）以及逐步标注控件。

v2.4.0 新增

评估浏览网页的 AI 智能体，需要看到智能体当时看到的画面、它点了哪里，以及每一步是否合理。Potato 提供专门的 Web 智能体 trace 查看器，支持两种模式：审查已录制的 trace，以及在真实网站上浏览来录制新的 trace。

概览

模式适用场景
审查模式你已经有来自 WebArena、Mind2Web、Anthropic Computer Use 或 Potato 自带录制器的 trace
录制模式你希望标注者浏览网站，录下新的交互 trace

审查模式

标注者逐帧查看智能体浏览会话的截图。SVG 叠加层会在每张截图上画出点击标记、边界框、鼠标轨迹和滚动指示。

配置

yaml
instance_display:
  fields:
    - key: steps
      type: web_agent_trace
      label: "Agent Browsing Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_observation: true
        show_element_info: true
        screenshot_max_width: 800
        screenshot_max_height: 600
        filmstrip_size: 80

数据格式

每条数据需要一个 steps 数组，其中包含每一步的信息：

json
{
  "id": "trace_001",
  "task_description": "Find and add a blue wool sweater to cart",
  "site": "amazon.com",
  "steps": [
    {
      "step_index": 0,
      "screenshot_url": "screenshots/step_000.png",
      "action_type": "click",
      "element": {
        "tag": "input",
        "text": "Search",
        "bbox": [340, 45, 680, 75]
      },
      "coordinates": {"x": 510, "y": 60},
      "mouse_path": [[200, 300], [350, 200], [510, 60]],
      "thought": "I need to search for blue wool sweaters",
      "observation": "Search box is focused",
      "timestamp": 1.2,
      "viewport": {"width": 1280, "height": 720}
    }
  ]
}

支持的动作类型

动作叠加层
click带十字准星和脉冲动画的红色圆圈
type目标元素上的黄色高亮
scroll绿色方向箭头
hover紫色圆圈
select蓝色边界框
navigate无叠加层
wait无叠加层
done无叠加层

键盘快捷键

按键操作
← / →上一步 / 下一步
1切换点击标记叠加层
2切换边界框叠加层
3切换鼠标轨迹叠加层
4切换滚动指示
A显示全部叠加层
N隐藏全部叠加层

逐步标注

给任意标注方案加上 per_step: true，就会在每一步旁边生成对应的标注控件：

yaml
annotation_schemes:
  - annotation_type: radio
    name: step_correctness
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: step_notes
    per_step: true
    label: "Notes on this step"

逐步标注以 {scheme_name}_step_{index} 的形式保存（例如 step_correctness_step_0）。

录制模式

标注者在 Potato 界面内浏览真实网站，交互过程会自动录制成可直接标注的 trace。

配置

yaml
instance_display:
  fields:
    - key: browsing_session
      type: web_agent_recorder
      display_options:
        start_url: "https://www.google.com"
        proxy_mode: auto
        record_mouse_path: true
        record_viewport: true
        screenshot_method: server
        max_steps: 50

代理模式

模式说明
auto（默认）检测目标站点是否允许 iframe 嵌入，自动选择最合适的模式
iframe强制使用 iframe 代理 —— 约 90% 的站点可用，额外开销低于 100 毫秒
playwright强制使用服务端 Playwright —— 所有站点都可用，需要安装 playwright 包

启用 Playwright 模式：

bash
pip install playwright
playwright install chromium

转换已有 trace

用 trace 转换 CLI 把其他框架的 trace 归一化成 Potato 的格式：

bash
# Convert from a specific format
python -m potato.trace_converter -i traces.json -f web_agent -o output.jsonl
 
# Auto-detect format
python -m potato.trace_converter -i traces.json --auto-detect -o output.jsonl

支持的输入格式：WebArena、VisualWebArena、Mind2Web、Anthropic Computer Use，以及 Potato 自己录制的原始数据。

完整示例

yaml
task_name: "Web Agent Evaluation"
task_dir: "."
 
data_files:
  - "traces.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: steps
      type: web_agent_trace
      label: "Agent Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task successfully?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: radio
    name: step_correctness
    question: "Was this step correct?"
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: error_description
    question: "Describe any errors in the agent's behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

运行示例项目

bash
# Review Mode
python potato/flask_server.py start examples/agent-traces/web-agent-review/config.yaml -p 8000
 
# Creation Mode
python potato/flask_server.py start examples/agent-traces/web-agent-creation/config.yaml -p 8000

API 参考

使用录制模式时，可以调用以下 REST 接口：

接口方法说明
/api/web_agent/start_sessionPOST开始一次录制会话
/api/web_agent/save_stepPOST保存一步录制到的交互
/api/web_agent/save_screenshotPOST上传某一步的截图
/api/web_agent/end_sessionPOST结束会话并写入 trace
/api/web_agent/proxy/{url}GET通过服务器代理访问外部 URL
/api/web_agent/check_frameableGET检测某个 URL 是否允许 iframe 嵌入

延伸阅读

有关实现详情，请参阅源文档。