Annotazione Agentiva

Novità della v2.3.0

Gli agenti AI vengono sempre più impiegati per compiti complessi e multi-fase: navigare il web, scrivere codice, chiamare API e orchestrare sotto-agenti. Ma valutare se un agente ha davvero fatto la cosa giusta richiede un giudizio umano a una granularità che i tradizionali strumenti di annotazione non possono supportare. Una singola trace di agente può contenere decine di passi, chiamate a strumenti, ragionamenti intermedi, screenshot e decisioni ramificate. Gli annotatori devono vedere tutto questo contesto, navigarlo in modo efficiente e fornire valutazioni strutturate sia a livello di trace che a livello di singolo passo.

Il sistema di annotazione agentiva di Potato affronta questo problema con quattro capacità:

1. 13 convertitori di formato trace che normalizzano i log degli agenti da qualsiasi framework principale in un formato unificato
2. 5 tipi di display specializzati ottimizzati per diverse modalità degli agenti (uso di strumenti, navigazione web, coding, chat, osservazione dal vivo)
3. 9 schemi di annotazione predefiniti che coprono le dimensioni di valutazione degli agenti più comuni
4. 4 tipi di annotazione creati su misura per la valutazione avanzata: valutazione di trajectory, valutazione per rubrica, confronto a coppie e annotazione di reward di processo

Convertitori di Formato Trace

Le trace degli agenti arrivano in formati molto diversi a seconda del framework. Potato include 13 convertitori che le normalizzano in una rappresentazione interna unificata. Specifica il convertitore nella tua configurazione, oppure lascia che Potato rilevi automaticamente il formato.

Riferimento ai Convertitori

Configurazione

Specifica il convertitore nella configurazione del progetto:

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

Ogni riga nel file trace deve essere un oggetto JSON contenente la trace grezza dell'agente. Il convertitore gestisce il resto.

Per trace multi-agente in cui diversi agenti usano framework diversi, puoi specificare convertitori per agente:

agentic:
  enabled: true
  trace_converter: multi_agent
  trace_file: "data/multi_agent_traces.jsonl"
  multi_agent:
    agent_converters:
      planner: react
      coder: anthropic
      reviewer: openai

Rilevamento Automatico

Se non sei sicuro di quale convertitore usare, imposta trace_converter: auto:

agentic:
  enabled: true
  trace_converter: auto
  trace_file: "data/traces.jsonl"

Potato esamina le prime 10 trace e seleziona il convertitore più adatto in base alle firme dei campi. Viene registrato un avviso se la confidenza è inferiore all'80%, nel qual caso dovresti specificare il convertitore esplicitamente.

Convertitori Personalizzati

Se il tuo framework di agenti non è elencato, puoi scrivere un convertitore Python:

# converters/my_converter.py
from potato.agentic.base_converter import BaseTraceConverter
 
class MyConverter(BaseTraceConverter):
    name = "my_framework"
 
    def convert(self, raw_trace: dict) -> dict:
        steps = []
        for entry in raw_trace["log"]:
            steps.append({
                "type": entry.get("kind", "action"),
                "content": entry["text"],
                "timestamp": entry.get("ts"),
                "metadata": entry.get("extra", {}),
            })
        return {"steps": steps}

Registralo nella configurazione:

agentic:
  trace_converter: custom
  custom_converter: "converters/my_converter.py:MyConverter"

Tipi di Display

Una volta convertite le trace, Potato le rende usando uno dei cinque tipi di display specializzati. Ciascuno è ottimizzato per una diversa modalità di agente.

1. Display Trace dell'Agente

Il display predefinito per gli agenti che usano strumenti (OpenAI function calling, Anthropic tool_use, ReAct, LangChain, ecc.). Rende ogni passo come una scheda con codifica cromatica per tipo di passo.

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Color coding for step types
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Collapsible sections
    collapse_observations: true
    collapse_threshold: 500    # characters before auto-collapsing
 
    # Step numbering
    show_step_numbers: true
    show_timestamps: true
 
    # Tool call rendering
    render_json: true          # pretty-print JSON arguments
    syntax_highlight: true     # highlight code in observations

Funzionalità:

• Schede dei passi con bordo sinistro colorato che indica il tipo (thought, action, observation, error)
• Sezioni comprimibili per osservazioni lunghe o output degli strumenti (soglia configurabile)
• Formattazione JSON per argomenti delle chiamate agli strumenti e risposte strutturate
• Evidenziazione della sintassi per blocchi di codice nelle osservazioni
• Barra laterale con timeline dei passi che mostra l'intera trace a colpo d'occhio
• Navigazione salta-al-passo per trace lunghe

2. Display Trace Agente Web

Appositamente creato per gli agenti di navigazione web (WebArena, VisualWebArena, registrazioni browser grezze). Rende gli screenshot con overlay SVG che mostrano dove l'agente ha cliccato, digitato o fatto scorrere.

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Screenshot rendering
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # SVG overlay for agent actions
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair, or arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # highlight for text input fields
      scroll_indicator: true
 
    # Filmstrip view
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # DOM snapshot display
    show_dom_snapshot: false        # optional raw DOM view
    show_url_bar: true
    show_action_description: true

Funzionalità:

• Galleria di screenshot con visualizzazione a schermo intero e zoom
• Overlay SVG che mostrano i target dei clic (cerchi rossi), le regioni di input testo (evidenziazioni blu) e le direzioni di scorrimento
• Vista a pellicola in basso che mostra tutti gli screenshot come miniature per una navigazione rapida
• Descrizione dell'azione testo sotto ogni screenshot (es. "Fai clic sul pulsante 'Add to Cart'")
• Barra URL che mostra l'URL della pagina corrente in ogni passo
• Confronto prima/dopo per i passi che modificano il contenuto della pagina

3. Display Chat Interattivo

Per la valutazione di agenti conversazionali e chatbot. Supporta due sotto-modalità: chat dal vivo dove gli annotatori interagiscono con l'agente in tempo reale, e revisione trace dove gli annotatori valutano una conversazione registrata.

agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # or "live_chat"
 
    # Trace review settings
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" or "message"
 
    # Live chat settings (when mode: live_chat)
    live_chat:
      proxy: openai             # agent proxy to use
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Common settings
    show_role_labels: true
    role_colors:
      user: "#3b82f6"
      assistant: "#6E56CF"
      system: "#6b7280"
      tool: "#22c55e"

La modalità di revisione trace rende una conversazione registrata con conteggi opzionali di token e latenza per messaggio. Gli annotatori possono valutare i singoli turni o l'intera conversazione.

La modalità chat dal vivo collega gli annotatori a un agente in esecuzione tramite il Sistema Proxy degli Agenti (vedere di seguito). Gli annotatori conversano con l'agente, poi annotano la conversazione risultante.

4. Display Trace di Coding

Appositamente creato per le sessioni di agenti di coding (Claude Code, Aider, SWE-Agent). Rende i diff di codice con evidenziazione della sintassi, output di terminale in blocchi scuri e letture di file con numeri di riga.

agentic:
  enabled: true
  trace_converter: claude_code
  display_type: coding_trace
 
  coding_trace_display:
    diff_style: unified           # unified or split
    terminal_theme: dark
    show_file_tree: true
    collapse_long_output: true
    collapse_threshold: 50        # lines
    show_line_numbers: true
    syntax_highlight: true

Funzionalità:

• Vista diff unificata con evidenziazione rossa/verde per le operazioni di modifica
• Blocchi di terminale scuri per l'output dei comandi bash/shell
• Blocchi di codice con numerazione di riga per le operazioni di lettura dei file
• Barra laterale con albero dei file che mostra tutti i file toccati durante la sessione
• Output lunghi comprimibili per contenuto verboso di terminale o di file

Vedi Annotazione di Agenti di Coding per il riferimento completo.

5. Display Agente dal Vivo

Osservazione in tempo reale degli agenti AI con controlli per l'intervento umano. Supporta agenti di navigazione web e agenti di coding.

agentic:
  enabled: true
  display_type: live_agent

Funzionalità:

• Streaming in tempo reale delle azioni dell'agente tramite Server-Sent Events
• Pausa/Riprendi l'agente tra un passo e l'altro
• Invia istruzioni per reindirizzare l'agente a metà del compito
• Assumi il controllo manuale
• Rollback a qualsiasi checkpoint precedente (gli agenti di coding usano checkpoint basati su git)
• Ramifica e riproduci da qualsiasi checkpoint con istruzioni diverse

Vedi Valutazione di Agenti dal Vivo e Agente di Coding dal Vivo per i dettagli di configurazione.

Tipi di Annotazione Avanzati

Oltre alle valutazioni per turno e agli schemi predefiniti, Potato include quattro tipi di annotazione creati su misura per la valutazione strutturata degli agenti.

Valutazione di Trajectory (trajectory_eval)

Localizzazione degli errori per passo con tassonomie di errori gerarchiche e punteggio di gravità. Ogni passo riceve una valutazione di correttezza, un tipo di errore, un livello di gravità e una motivazione opzionale. Un contatore di punteggio corrente viene decrementato in base alla gravità.

annotation_schemes:
  - annotation_type: trajectory_eval
    name: step_eval
    error_taxonomy:
      reasoning:
        - logical_error
        - incorrect_assumption
      action:
        - wrong_tool
        - wrong_arguments
        - premature_termination
    severity_weights:
      minor: -1
      major: -5
      critical: -10

Vedi il post del blog sulla valutazione di trajectory per una guida completa.

Valutazione per Rubrica (rubric_eval)

Valutazione multicriterio in griglia in stile MT-Bench. Definisci criteri personalizzati e una scala di valutazione. Gli annotatori valutano ogni criterio in modo indipendente.

annotation_schemes:
  - annotation_type: rubric_eval
    name: agent_rubric
    criteria:
      - name: correctness
        description: "Did the agent produce the correct result?"
      - name: efficiency
        description: "Did the agent take an efficient path?"
      - name: safety
        description: "Did the agent avoid unsafe actions?"
    scale: 5
    scale_labels:
      1: "Very Poor"
      3: "Acceptable"
      5: "Excellent"

Vedi il tutorial sulla valutazione per rubrica per le istruzioni di configurazione.

Confronto a Coppie

Confronta due trace di agente fianco a fianco con tre modalità:

• Binaria: clicca per selezionare A o B (con pareggio opzionale)
• Scala: cursore da "A molto migliore" a "B molto migliore"
• Multidimensione: A/B/pareggio indipendenti per dimensione, con giustificazione obbligatoria

annotation_schemes:
  - annotation_type: pairwise
    name: agent_comparison
    mode: multi_dimension
    dimensions:
      - correctness
      - efficiency
      - safety
    require_justification: true
    allow_tie: true

Vedi la guida al confronto a coppie per tutte e tre le modalità.

Annotazione di Reward di Processo

Annotazione binaria di correttezza per passo, ottimizzata per addestrare modelli di reward di processo. Due modalità: primo-errore (clicca sul primo passo errato, il resto viene marcato automaticamente) e per-passo (valuta ciascuno in modo indipendente).

annotation_schemes:
  - annotation_type: process_reward
    name: prm
    mode: first_error    # or per_step

Vedi Annotazione di Reward di Processo per il riferimento completo.

Valutazioni per Turno

Per valutazioni di dialogo e multi-passo, spesso sono necessarie valutazioni sui singoli turni anziché (o in aggiunta a) sull'intera trace. Potato supporta l'annotazione per turno per qualsiasi tipo di display.

annotation_schemes:
  # Overall trace rating
  - annotation_type: likert
    name: overall_quality
    description: "Rate the overall quality of this agent trace"
    min: 1
    max: 5
    labels:
      1: "Very Poor"
      5: "Excellent"
 
  # Per-turn ratings
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # binds to trace steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"
      - "Unnecessary"
 
  - annotation_type: per_turn_rating
    name: step_explanation
    description: "Explain any issues with this step"
    target: agentic_steps
    rating_type: text
    conditional:
      show_when:
        step_correctness: ["Partially Correct", "Incorrect", "Unnecessary"]

Le valutazioni per turno appaiono in linea accanto a ciascuna scheda del passo. Il blocco conditional consente di mostrare domande di follow-up solo quando vengono selezionate determinate valutazioni, mantenendo l'interfaccia pulita.

Formato di Output per Turno

Le annotazioni per turno vengono salvate con gli indici dei passi:

{
  "id": "trace_042",
  "annotations": {
    "overall_quality": 3,
    "step_correctness": {
      "0": "Correct",
      "1": "Correct",
      "2": "Incorrect",
      "3": "Correct"
    },
    "step_explanation": {
      "2": "The agent searched for the wrong product name"
    }
  }
}

Sistema Proxy degli Agenti

Per i compiti di valutazione dal vivo dove gli annotatori interagiscono con un agente in tempo reale, Potato fornisce un livello proxy per gli agenti. Il proxy si trova tra l'interfaccia di annotazione e il backend dell'agente, registrando l'intera conversazione per la revisione successiva.

agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http, or echo
 
    # OpenAI proxy
    openai:
      model: "gpt-4o"
      api_key: ${OPENAI_API_KEY}
      system_prompt: "You are a helpful customer service agent."
      temperature: 0.7
      max_tokens: 1024

Tipi di Proxy

Il proxy OpenAI inoltra i messaggi a un'API compatibile con OpenAI:

agent_proxy:
  type: openai
  openai:
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
    system_prompt: "You are a helpful assistant."
    temperature: 0.7

Il proxy HTTP inoltra i messaggi a qualsiasi endpoint HTTP (il tuo server agente):

agent_proxy:
  type: http
  http:
    url: "https://my-agent.example.com/chat"
    method: POST
    headers:
      Authorization: "Bearer ${AGENT_API_KEY}"
    request_template:
      messages: "{{messages}}"
      session_id: "{{session_id}}"
    response_path: "response.content"
    timeout_seconds: 30

Il proxy echo rispecchia il messaggio dell'utente (utile per i test e lo sviluppo dell'interfaccia):

agent_proxy:
  type: echo
  echo:
    prefix: "[Echo] "
    delay_ms: 500

Schemi di Annotazione Predefiniti

Potato include 9 schemi di annotazione progettati specificamente per la valutazione degli agenti. Usali direttamente o come punto di partenza per i tuoi schemi.

Carica uno schema predefinito per nome:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy

Oppure combina i preset con schemi personalizzati:

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Custom schema alongside presets
  - annotation_type: text
    name: evaluator_notes
    description: "Any additional observations about this agent trace"
    label_requirement:
      required: false

Esempio Completo: Valutazione di un Agente ReAct

Ecco una configurazione completa per la valutazione di trace di agenti in stile ReAct con valutazioni per passo:

# project config
task_name: "ReAct Agent Evaluation"
task_dir: "."
 
data_files:
  - "data/react_traces.jsonl"
 
item_properties:
  id_key: trace_id
  text_key: task_description
 
agentic:
  enabled: true
  trace_converter: react
  display_type: agent_trace
 
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    collapse_threshold: 300
    show_step_numbers: true
    render_json: true
 
annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_efficiency
 
  - annotation_type: text
    name: failure_reason
    description: "If the agent failed, describe what went wrong"
    label_requirement:
      required: false
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

Dati di input di esempio (data/react_traces.jsonl):

{
  "trace_id": "react_001",
  "task_description": "Find the population of Tokyo and compare it to New York City",
  "trace": [
    {"type": "thought", "content": "I need to find the population of both cities. Let me search for Tokyo first."},
    {"type": "action", "content": "search", "action_input": "Tokyo population 2024"},
    {"type": "observation", "content": "Tokyo has a population of approximately 13.96 million in the city proper..."},
    {"type": "thought", "content": "Now I need to find New York City's population."},
    {"type": "action", "content": "search", "action_input": "New York City population 2024"},
    {"type": "observation", "content": "New York City has a population of approximately 8.34 million..."},
    {"type": "thought", "content": "Tokyo (13.96M) has about 67% more people than NYC (8.34M)."},
    {"type": "action", "content": "finish", "action_input": "Tokyo has ~13.96 million people vs NYC's ~8.34 million, making Tokyo about 67% larger by population."}
  ]
}

Avvia il server:

potato start config.yaml -p 8000

Ulteriori Letture

• Annotazione di Agenti di Coding — rendering dei diff, output di terminale, albero dei file per agenti di coding
• Annotazione di Reward di Processo — dati di addestramento PRM con modalità primo-errore e per-passo
• Annotazione di Revisione del Codice — commenti in linea e verdetti in stile PR di GitHub
• Agente di Coding dal Vivo — osservazione in tempo reale di agenti di coding con rollback e ramificazione
• Valutazione di Agenti dal Vivo — osservazione in tempo reale di agenti web
• Annotazione di Agenti Web — revisione di trace di agenti web preregistrate
• Valutare Agenti AI: Una Guida Completa — guida passo-passo a un progetto completo di valutazione degli agenti
• Formati di Esportazione — esporta i dati di valutazione degli agenti

Per i dettagli di implementazione, consulta la documentazione sorgente.