Avaliação de Agentes ao Vivo

Novidade na v2.4.0

A Avaliação de Agentes ao Vivo permite que os anotadores assistam a um agente de IA navegar na web em tempo real e anotem seu comportamento enquanto ele é executado — e não depois do fato. O agente captura screenshots, envia-os a um LLM de visão, recebe ações e as executa em um navegador headless. Cada passo é transmitido ao vivo para a tela do anotador.

Requisitos

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

Configuração

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

Referência de configuração

Formato de dados

Cada instância fornece a tarefa e a URL inicial:

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

Fluxo de trabalho do anotador

1. O anotador lê a descrição da tarefa e clica em Start Agent
2. Um navegador Chromium headless é iniciado e se conecta ao LLM
3. Os screenshots são transmitidos ao vivo para o visualizador conforme o agente navega — cada passo mostra o screenshot, o pensamento do agente e a ação executada
4. O anotador pode interagir usando o painel de controle:
   • Pause / Resume — interrompe o agente entre os passos
   • Send Instructions — injeta uma mensagem no contexto do agente durante a execução
   • Take Over — alterna para o controle manual de navegação
   • Stop — encerra a sessão antecipadamente
5. Quando a sessão termina (sucesso, falha ou max_steps atingido), o trace é salvo e a exibição muda para o modo de revisão
6. O anotador preenche os esquemas de anotação para avaliar o desempenho do agente

Atalhos de teclado

Adicionando esquemas de anotação

Combine a exibição de agente ao vivo com qualquer esquema de anotação do 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

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

Arquitetura

O agente ao vivo é executado como uma thread em segundo plano no Flask. Screenshots e mudanças de estado são transmitidos para o navegador via Server-Sent Events (SSE). Os controles do anotador (pausar, instruir, assumir o controle, parar) chamam endpoints REST que se sincronizam com a thread em segundo plano.

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

Os screenshots são salvos em {task_dir}/live_sessions/ e servidos via API para a visualização em filmstrip.

Exportação de traces

Quando uma sessão é concluída, o Potato exporta automaticamente o trace completo como JSON compatível com web_agent_trace, incluindo:

• Todos os passos com screenshots, ações, pensamentos e observações
• Quaisquer instruções enviadas pelo anotador durante a execução
• Carimbos de data/hora e metadados de configuração do agente
• Eventos de tomada de controle pelo anotador

Isto significa que sessões ao vivo concluídas podem ser revisadas mais tarde usando o visualizador padrão de Anotação de Agentes Web.

Solução de problemas

"Playwright is not installed" — Execute pip install playwright && playwright install chromium.

"Anthropic API key required" — Defina a variável de ambiente ANTHROPIC_API_KEY ou use api_key: ${ANTHROPIC_API_KEY} na sua configuração.

O agente parece lento — Cada passo exige uma chamada à API do LLM (normalmente 3–10 segundos). O indicador de processamento aparece enquanto o LLM trabalha. Reduza history_window para acelerar sessões longas.

Os screenshots não carregam — Verifique se task_dir tem permissão de escrita e se o servidor tem espaço em disco disponível.

Backends de agentes de programação

Além de agentes de navegação web, o Potato suporta a observação ao vivo de agentes de programação. Três backends estão disponíveis:

Ollama (Local, sem chave de API)

Execute a avaliação de agentes de programação com modelos totalmente locais — sem necessidade de chave 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"

Anthropic API

Use o Claude com uso de ferramentas para a avaliação de agentes de programação.

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

Capacidades completas do Claude Code para sessões avançadas de agentes de programação.

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

Consulte Agente de Programação ao Vivo para a referência completa, incluindo rollback, ramificação e exportação de trajetórias.

Rollback e checkpoints

Para sessões de agentes de programação, o Potato cria um commit git após cada alteração de arquivo. Isto permite:

• Rollback com um clique para qualquer checkpoint anterior
• Ramificar e repetir — experimente uma abordagem diferente a partir de qualquer checkpoint
• Histórico completo de cada estado de arquivo para revisão

Os checkpoints são gerenciados automaticamente por meio de um branch git dedicado por sessão.

Trajetórias ramificadas

Quando um anotador faz rollback e experimenta uma abordagem diferente, o Potato cria uma trajetória ramificada. Ambos os ramos são preservados na saída, gerando dados de treinamento ricos para:

• Modelos de Recompensa de Processo — rótulos de correção por passo entre os ramos
• Aprendizado de Preferências — qual ramo produziu melhores resultados
• Conjuntos de Dados de Revisão de Código — compare a qualidade do código entre abordagens

Leitura adicional

• Agente de Programação ao Vivo — observação de agentes de programação com Ollama, Anthropic e Claude SDK
• Anotação de Agentes Web — revise traces de agentes pré-gravados
• Anotação Agêntica — visão geral dos formatos de trace de agentes e conversores
• Anotação de Recompensa de Processo — coleta de dados de treinamento de PRM
• Suporte de IA — integração de LLM para assistência na anotação

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