Valutazione dal vivo degli agenti

Guarda gli agenti AI lavorare in tempo reale e annota il loro comportamento durante l'esecuzione, con controlli di pausa, istruzione e subentro. Supporta agenti web e coding agent con Anthropic, Ollama e Claude SDK.

Novità della v2.4.0

La valutazione dal vivo degli agenti permette agli annotatori di guardare un agente AI navigare sul web in tempo reale e di annotarne il comportamento mentre è in esecuzione, non a cose fatte. L'agente cattura screenshot, li manda a un LLM con capacità visive, riceve azioni e le esegue in un browser headless. Ogni passo arriva in diretta sullo schermo dell'annotatore.

Requisiti

bash

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

Configurazione

yaml

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

Riferimento di configurazione

Opzione	Tipo	Default	Descrizione
`endpoint_type`	string	`anthropic_vision`	Provider LLM per l'agente
`ai_config.model`	string	`claude-sonnet-4-20250514`	Modello da usare
`ai_config.api_key`	string	variabile d'ambiente	Chiave API (usa la sintassi `${VAR}`)
`ai_config.max_tokens`	int	`4096`	Token massimi per risposta dell'LLM
`ai_config.temperature`	float	`0.3`	Temperatura di campionamento
`system_prompt`	string	integrato	System prompt per l'agente
`max_steps`	int	`30`	Numero massimo di passi prima dell'arresto
`step_delay`	float	`1.0`	Secondi tra un passo e l'altro
`viewport.width`	int	`1280`	Larghezza del viewport del browser
`viewport.height`	int	`720`	Altezza del viewport del browser
`allow_takeover`	bool	`true`	Permette agli annotatori di prendere il controllo manuale
`allow_instructions`	bool	`true`	Permette agli annotatori di inviare istruzioni durante l'esecuzione
`history_window`	int	`5`	Numero di passi recenti inclusi nel contesto dell'LLM

Formato dei dati

Ogni istanza indica il compito e l'URL di partenza:

json

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

Flusso di lavoro dell'annotatore

L'annotatore legge la descrizione del compito e clicca su Start Agent
Parte un browser Chromium headless che si collega all'LLM
Gli screenshot arrivano in diretta al visualizzatore mentre l'agente naviga: ogni passo mostra lo screenshot, il ragionamento dell'agente e l'azione eseguita
L'annotatore può intervenire dal pannello di controllo:
- Pause / Resume — ferma l'agente tra un passo e l'altro
- Send Instructions — inietta un messaggio nel contesto dell'agente mentre lavora
- Take Over — passa al controllo manuale della navigazione
- Stop — chiude la sessione in anticipo
Quando la sessione finisce (successo, fallimento o raggiungimento di max_steps), la traccia viene salvata e il display passa alla modalità di revisione
L'annotatore compila gli schemi di annotazione per valutare la prestazione dell'agente

Scorciatoie da tastiera

Tasto	Azione
`Space`	Pausa / Ripresa
`Escape`	Chiudi la sessione

Aggiungere schemi di annotazione

Combina il display dell'agente dal vivo con qualsiasi schema di annotazione di Potato:

yaml

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

Esempio completo

yaml

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"

Architettura

L'agente dal vivo gira come thread in background dentro Flask. Screenshot e cambi di stato vengono trasmessi al browser tramite Server-Sent Events (SSE). I controlli dell'annotatore (pausa, istruzioni, subentro, stop) chiamano endpoint REST che si sincronizzano con il thread in background.

text

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

Gli screenshot vengono salvati in {task_dir}/live_sessions/ e serviti tramite l'API per la vista a filmstrip.

Esportazione delle tracce

Quando una sessione si conclude, Potato esporta da solo la traccia completa in JSON compatibile con web_agent_trace, che comprende:

Tutti i passi con screenshot, azioni, ragionamenti e osservazioni
Le istruzioni inviate dall'annotatore durante l'esecuzione
Timestamp e metadati sulla configurazione dell'agente
Gli eventi di subentro dell'annotatore

Le sessioni dal vivo già concluse si possono quindi rivedere in seguito con il visualizzatore standard dell'annotazione di agenti web.

Risoluzione dei problemi

«Playwright is not installed» — Esegui pip install playwright && playwright install chromium.

«Anthropic API key required» — Imposta la variabile d'ambiente ANTHROPIC_API_KEY oppure usa api_key: ${ANTHROPIC_API_KEY} nella configurazione.

L'agente sembra lento — Ogni passo richiede una chiamata all'API dell'LLM (di solito 3–10 secondi). L'indicatore di elaborazione compare mentre l'LLM lavora. Riduci history_window per accelerare le sessioni lunghe.

Gli screenshot non si caricano — Verifica che task_dir sia scrivibile e che il server abbia spazio su disco.

Backend per i coding agent

Oltre agli agenti che navigano sul web, Potato supporta l'osservazione dal vivo dei coding agent. Sono disponibili tre backend:

Ollama (in locale, senza chiave API)

Esegui la valutazione dei coding agent con modelli interamente locali, senza bisogno di una chiave API.

yaml

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 di Anthropic

Usa Claude con l'uso di strumenti per la valutazione dei coding agent.

yaml

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

Tutte le capacità di Claude Code per le sessioni di coding agent più avanzate.

yaml

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

Vedi Live coding agent per il riferimento completo, comprensivo di rollback, branching ed esportazione delle traiettorie.

Rollback e checkpoint

Nelle sessioni con i coding agent, Potato crea un commit git dopo ogni modifica ai file. Questo permette:

Rollback con un clic a un checkpoint precedente qualsiasi
Branch e replay — prova un approccio diverso a partire da un checkpoint qualsiasi
Cronologia completa di ogni stato dei file per la revisione

I checkpoint sono gestiti in automatico tramite un branch git dedicato a ogni sessione.

Traiettorie con branching

Quando un annotatore torna indietro e prova un approccio diverso, Potato crea una traiettoria che si dirama. Entrambi i branch restano nell'output e producono dati di addestramento per:

Process reward model — etichette di correttezza per singolo passo lungo i vari branch
Apprendimento delle preferenze — quale branch ha dato risultati migliori
Dataset di code review — confronto della qualità del codice tra approcci diversi

Approfondimenti

Live coding agent — osservazione dei coding agent con Ollama, Anthropic e Claude SDK
Annotazione di agenti web — rivedi tracce di agenti già registrate
Annotazione agentica — panoramica dei formati di traccia degli agenti e dei convertitori
Annotazione di process reward — raccolta di dati di addestramento per PRM
Supporto AI — integrazione degli LLM per assistere l'annotazione

Per i dettagli implementativi, vedi la documentazione sorgente.