웹 에이전트 주석

필름스트립 탐색, SVG 오버레이(클릭, 바운딩 박스, 마우스 경로), 단계별 주석 컨트롤로 Potato에서 웹 브라우징 에이전트 트레이스를 검토합니다.

v2.4.0 신규 기능

웹을 탐색하는 AI 에이전트를 평가하려면 에이전트가 무엇을 보았는지, 어디를 클릭했는지, 각 단계가 타당했는지를 정확히 확인해야 합니다. Potato는 두 가지 모드를 갖춘 전용 웹 에이전트 트레이스 뷰어를 제공합니다: 사전 녹화된 트레이스를 검토하는 모드와 실제 웹사이트를 탐색하며 새 트레이스를 생성하는 모드입니다.

개요

모드	사용 시점
검토 모드	WebArena, Mind2Web, Anthropic Computer Use 또는 Potato 자체 레코더에서 사전 녹화된 트레이스가 있는 경우
생성 모드	주석자가 웹사이트를 탐색하고 새로운 상호작용 트레이스를 기록하도록 하려는 경우

검토 모드

주석자는 에이전트 브라우징 세션의 스크린샷을 단계별로 살펴봅니다. 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 인터페이스 안에서 실제 웹사이트를 탐색하며, 상호작용은 주석 처리 가능한 트레이스로 자동 기록됩니다.

설정

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%의 사이트에서 100ms 미만의 오버헤드로 작동합니다
`playwright`	서버 측 Playwright를 강제합니다 — 100%의 사이트에서 작동하며 `playwright` 패키지가 필요합니다

Playwright 모드를 활성화하려면:

bash

pip install playwright
playwright install chromium

기존 트레이스 변환

트레이스 변환 CLI를 사용하여 다른 프레임워크의 트레이스를 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_session`	POST	녹화 세션을 시작합니다
`/api/web_agent/save_step`	POST	기록된 상호작용 단계를 저장합니다
`/api/web_agent/save_screenshot`	POST	단계에 대한 스크린샷을 업로드합니다
`/api/web_agent/end_session`	POST	세션을 종료하고 트레이스를 영구 저장합니다
`/api/web_agent/proxy/{url}`	GET	외부 URL을 서버를 통해 프록시합니다
`/api/web_agent/check_frameable`	GET	URL이 iframe 임베딩을 허용하는지 테스트합니다

추가 자료

실시간 에이전트 평가 — 실시간으로 실행되는 에이전트를 평가합니다
에이전트 주석 — 트레이스 형식 변환기 및 디스플레이 유형 개요
능동 학습 — 주석 처리에 가장 유익한 트레이스를 우선순위로 지정합니다

구현 세부 정보는 원본 문서를 참조하세요.