Evaluación de Agentes en Vivo

Novedad en la v2.4.0

La evaluación de agentes en vivo permite a los anotadores ver a un agente de IA navegar por la web en tiempo real y anotar su comportamiento mientras se ejecuta, no después. El agente toma capturas de pantalla, las envía a un LLM con visión, recibe acciones y las ejecuta en un navegador headless. Cada paso se transmite en directo a la pantalla del anotador.

Requisitos

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

Configuración

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

Referencia de Configuración

Formato de Datos

Cada instancia aporta la tarea y la URL de partida:

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

Flujo de Trabajo del Anotador

1. El anotador lee la descripción de la tarea y pulsa Start Agent
2. Se lanza un navegador Chromium headless que se conecta al LLM
3. Las capturas de pantalla se transmiten en directo al visor según navega el agente: cada paso muestra la captura, el razonamiento del agente y la acción realizada
4. El anotador puede intervenir desde el panel de control:
   • Pause / Resume: detiene al agente entre pasos
   • Send Instructions: inyecta un mensaje en el contexto del agente durante la ejecución
   • Take Over: pasa al control manual de la navegación
   • Stop: termina la sesión antes de tiempo
5. Cuando la sesión acaba (con éxito, con fallo o al alcanzar max_steps), la traza se guarda y la vista pasa a modo de revisión
6. El anotador completa los esquemas de anotación para evaluar el rendimiento del agente

Atajos de Teclado

Añadir Esquemas de Anotación

Combina la visualización de agente en vivo con cualquier esquema de anotación de Potato:

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

Ejemplo Completo

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"

Arquitectura

El agente en vivo se ejecuta como un hilo en segundo plano dentro de Flask. Las capturas de pantalla y los cambios de estado se transmiten al navegador mediante Server-Sent Events (SSE). Los controles del anotador (pausa, instrucción, toma de control, parada) llaman a endpoints REST que se sincronizan con el hilo en segundo plano.

Annotator (browser)  <── SSE stream ──  Flask Server  ── Playwright ──► Headless Browser
                     ──► REST control ─►              ◄── LLM API ────► Claude Vision

Las capturas se guardan en {task_dir}/live_sessions/ y se sirven a través de la API para la vista de tira de fotogramas.

Exportación de Trazas

Cuando una sesión termina, Potato exporta automáticamente la traza completa como JSON compatible con web_agent_trace, que incluye:

• Todos los pasos con capturas de pantalla, acciones, razonamientos y observaciones
• Cualquier instrucción enviada por el anotador durante la ejecución
• Marcas de tiempo y metadatos de configuración del agente
• Eventos de toma de control por parte del anotador

Esto significa que las sesiones en vivo terminadas se pueden revisar más tarde con el visor estándar de Anotación de Agentes Web.

Resolución de Problemas

«Playwright is not installed»: ejecuta pip install playwright && playwright install chromium.

«Anthropic API key required»: define la variable de entorno ANTHROPIC_API_KEY o usa api_key: ${ANTHROPIC_API_KEY} en tu configuración.

El agente parece lento: cada paso requiere una llamada a la API del LLM (normalmente entre 3 y 10 segundos). El indicador de razonamiento aparece mientras el LLM procesa. Reduce history_window para acelerar las sesiones largas.

Las capturas no cargan: comprueba que se puede escribir en task_dir y que el servidor tiene espacio de disco disponible.

Backends para Agentes de Coding

Además de los agentes de navegación web, Potato admite la observación en vivo de agentes de coding. Hay tres backends disponibles:

Ollama (local, sin clave de API)

Ejecuta la evaluación de agentes de coding con modelos totalmente locales, sin necesidad de clave de API.

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"

API de Anthropic

Usa Claude con uso de herramientas para la evaluación de agentes de coding.

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

Todas las capacidades de Claude Code para sesiones avanzadas de agentes de coding.

live_agent:
  endpoint_type: coding_agent
  backend: claude_agent_sdk
  ai_config:
    max_turns: 50
  project_dir: "./workspace"

Consulta Agente de Coding en Vivo para la referencia completa, incluidas la reversión, la ramificación y la exportación de trayectorias.

Reversión y Puntos de Control

En las sesiones de agente de coding, Potato crea un commit de git tras cada cambio de archivo. Esto permite:

• Reversión con un clic a cualquier punto de control anterior
• Ramificar y reproducir: probar otro enfoque desde cualquier punto de control
• Historial completo del estado de cada archivo para revisarlo

Los puntos de control se gestionan automáticamente en una rama de git dedicada por sesión.

Trayectorias Ramificadas

Cuando un anotador revierte y prueba otro enfoque, Potato crea una trayectoria ramificada. Ambas ramas se conservan en la salida, lo que produce datos de entrenamiento para:

• Modelos de recompensa de proceso: etiquetas de corrección por paso a lo largo de las ramas
• Aprendizaje de preferencias: qué rama dio mejores resultados
• Conjuntos de datos de revisión de código: comparar la calidad del código entre enfoques

Lecturas Adicionales

• Agente de Coding en Vivo: observación de agentes de coding con Ollama, Anthropic y el SDK de Claude
• Anotación de Agentes Web: revisar trazas de agente ya grabadas
• Anotación Agéntica: panorama de los formatos de traza de agente y sus conversores
• Anotación de Recompensa de Proceso: recogida de datos de entrenamiento para PRM
• Soporte de IA: integración de LLM para asistir en la anotación

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