Anotação de Agentes Web

Revise traces de agentes que navegam na web no Potato com navegação em filmstrip, sobreposições SVG (cliques, caixas delimitadoras, trajetórias do mouse) e controles de anotação por etapa.

Novo na v2.4.0

Avaliar agentes de IA que navegam na web exige ver exatamente o que o agente viu, onde clicou e se cada etapa fez sentido. O Potato oferece um Visualizador de Trace de Agentes Web dedicado com dois modos: revisar traces pré-gravados e criar novos navegando em sites ao vivo.

Visão Geral

Modo	Use Quando
Modo de Revisão	Você tem traces pré-gravados do WebArena, Mind2Web, Anthropic Computer Use ou do próprio gravador do Potato
Modo de Criação	Você quer que os anotadores naveguem em sites e gravem novos traces de interação

Modo de Revisão

Os anotadores percorrem capturas de tela de uma sessão de navegação do agente. Sobreposições SVG renderizam marcadores de clique, caixas delimitadoras, trajetórias do mouse e indicadores de rolagem sobre cada captura de tela.

Configuração

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

Formato dos Dados

Cada instância precisa de um array steps com dados por etapa:

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

Tipos de Ação Suportados

Ação	Sobreposição
`click`	Círculo vermelho com mira e animação de pulso
`type`	Destaque amarelo no elemento alvo
`scroll`	Seta direcional verde
`hover`	Círculo roxo
`select`	Caixa delimitadora azul
`navigate`	Sem sobreposição
`wait`	Sem sobreposição
`done`	Sem sobreposição

Atalhos de Teclado

Tecla	Ação
`←` / `→`	Etapa anterior / seguinte
`1`	Alternar sobreposições de marcadores de clique
`2`	Alternar sobreposições de caixas delimitadoras
`3`	Alternar sobreposições de trajetórias do mouse
`4`	Alternar indicadores de rolagem
`A`	Mostrar todas as sobreposições
`N`	Ocultar todas as sobreposições

Anotações Por Etapa

Adicione per_step: true a qualquer esquema de anotação para criar controles de anotação que aparecem em linha com cada etapa:

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"

As anotações por etapa são armazenadas como {scheme_name}_step_{index} (por exemplo, step_correctness_step_0).

Modo de Criação

Os anotadores navegam em um site ao vivo dentro da interface do Potato, e as interações são gravadas automaticamente como um trace pronto para anotação.

Configuração

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

Modos de Proxy

Modo	Descrição
`auto` (padrão)	Detecta se o site alvo permite incorporação em iframe e escolhe o melhor modo automaticamente
`iframe`	Força o proxy de iframe — funciona em ~90% dos sites com menos de 100ms de overhead
`playwright`	Força o Playwright no servidor — funciona em 100% dos sites, requer o pacote `playwright`

Para habilitar o modo Playwright:

bash

pip install playwright
playwright install chromium

Convertendo Traces Existentes

Use a CLI conversora de traces para normalizar traces de outros frameworks no formato do 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

Formatos de entrada suportados: WebArena, VisualWebArena, Mind2Web, Anthropic Computer Use e gravações brutas do Potato.

Exemplo Completo

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"

Executando Projetos de Exemplo

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

Referência da API

Estes endpoints REST estão disponíveis ao usar o Modo de Criação:

Endpoint	Método	Descrição
`/api/web_agent/start_session`	POST	Inicia uma sessão de gravação
`/api/web_agent/save_step`	POST	Salva uma etapa de interação gravada
`/api/web_agent/save_screenshot`	POST	Envia uma captura de tela para uma etapa
`/api/web_agent/end_session`	POST	Encerra a sessão e persiste o trace
`/api/web_agent/proxy/{url}`	GET	Faz proxy de uma URL externa pelo servidor
`/api/web_agent/check_frameable`	GET	Testa se uma URL permite incorporação em iframe

Leitura Adicional

Avaliação de Agentes ao Vivo — avalie agentes em execução em tempo real
Anotação Agêntica — visão geral dos conversores de formato de trace e tipos de exibição
Aprendizado Ativo — priorize os traces mais informativos para anotação

Para detalhes de implementação, consulte a documentação de origem.