Anotación de Agentes Web

Revisa trazas de agentes de navegación web en Potato con navegación tipo filmstrip, superposiciones SVG (clics, cajas delimitadoras, trayectorias del ratón) y controles de anotación por paso.

Novedad en la v2.4.0

Para evaluar agentes de IA que navegan por la web hace falta ver exactamente lo que vio el agente, dónde hizo clic y si cada paso tenía sentido. Potato incluye un visor de trazas de agentes web con dos modos: revisar trazas ya grabadas y crear trazas nuevas navegando por sitios web en vivo.

Visión General

Modo	Cuándo Usarlo
Modo de revisión	Ya tienes trazas grabadas de WebArena, Mind2Web, Anthropic Computer Use o del propio grabador de Potato
Modo de creación	Quieres que los anotadores naveguen por sitios web y graben trazas de interacción nuevas

Modo de Revisión

Los anotadores recorren paso a paso las capturas de pantalla de una sesión de navegación del agente. Las superposiciones SVG dibujan marcadores de clic, cajas delimitadoras, trayectorias del ratón e indicadores de desplazamiento sobre cada captura.

Configuración

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 de Datos

Cada instancia necesita un array steps con los datos de cada paso:

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 Acción Admitidos

Acción	Superposición
`click`	Círculo rojo con retícula y animación de pulso
`type`	Resaltado amarillo sobre el elemento de destino
`scroll`	Flecha verde direccional
`hover`	Círculo morado
`select`	Caja delimitadora azul
`navigate`	Sin superposición
`wait`	Sin superposición
`done`	Sin superposición

Atajos de Teclado

Tecla	Acción
`←` / `→`	Paso anterior / siguiente
`1`	Alternar las marcas de clic
`2`	Alternar las cajas delimitadoras
`3`	Alternar las trayectorias del ratón
`4`	Alternar los indicadores de desplazamiento
`A`	Mostrar todas las superposiciones
`N`	Ocultar todas las superposiciones

Anotaciones por Paso

Añade per_step: true a cualquier esquema de anotación para crear controles de anotación que aparecen junto a cada paso:

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"

Las anotaciones por paso se guardan como {scheme_name}_step_{index} (por ejemplo, step_correctness_step_0).

Modo de Creación

Los anotadores navegan por un sitio web en vivo dentro de la interfaz de Potato y sus interacciones se graban automáticamente como una traza lista para anotar.

Configuración

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	Descripción
`auto` (predeterminado)	Detecta si el sitio de destino permite incrustarse en un iframe y elige el mejor modo automáticamente
`iframe`	Fuerza el proxy por iframe — funciona en cerca del 90 % de los sitios con menos de 100 ms de sobrecarga
`playwright`	Fuerza Playwright en el servidor — funciona en el 100 % de los sitios, requiere el paquete `playwright`

Para activar el modo Playwright:

bash

pip install playwright
playwright install chromium

Conversión de Trazas Existentes

Usa la CLI de conversión de trazas para normalizar trazas de otros frameworks al formato de 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 admitidos: WebArena, VisualWebArena, Mind2Web, Anthropic Computer Use y grabaciones sin procesar de Potato.

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

Ejecutar los Proyectos de Ejemplo

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

Referencia de la API

Estos endpoints REST están disponibles cuando se usa el modo de creación:

Endpoint	Método	Descripción
`/api/web_agent/start_session`	POST	Inicia una sesión de grabación
`/api/web_agent/save_step`	POST	Guarda un paso de interacción grabado
`/api/web_agent/save_screenshot`	POST	Sube la captura de pantalla de un paso
`/api/web_agent/end_session`	POST	Termina la sesión y guarda la traza
`/api/web_agent/proxy/{url}`	GET	Redirige una URL externa a través del servidor
`/api/web_agent/check_frameable`	GET	Comprueba si una URL permite incrustarse en un iframe

Lectura Adicional

Evaluación de Agentes en Vivo — evaluar agentes que se ejecutan en tiempo real
Anotación Agéntica — conversores de formato de traza y panorama de los tipos de visualización
Aprendizaje Activo — priorizar las trazas más informativas para anotar

Para detalles de implementación, consulta la documentación fuente.