Diese Seite ist in Ihrer Sprache noch nicht verfügbar. Englische Version wird angezeigt.

Annotazione Agentiva

Valuta agenti AI con display specializzati per trace, 12 convertitori di formato e schemi di annotazione dedicati.

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 supportano. 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 tre capacità:

12 convertitori di formato trace che normalizzano i log degli agenti da qualsiasi framework principale in un formato unificato
3 tipi di display specializzati ottimizzati per diverse modalità degli agenti (uso di strumenti, navigazione web, chat)
9 schemi di annotazione preconfigurati che coprono le dimensioni di valutazione degli agenti più comuni

Convertitori di Formato Trace

Le trace degli agenti arrivano in formati molto diversi a seconda del framework. Potato include 12 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

Convertitore	Formato Sorgente	Campi Chiave Estratti
`openai`	OpenAI Assistants API / log di function calling	messages, tool_calls, risultati delle funzioni
`anthropic`	Anthropic Claude tool_use / Messages API	blocchi di contenuto, tool_use, tool_result
`swebench`	Trace di compiti SWE-bench	patch, risultati dei test, trajectory
`opentelemetry`	Esportazioni span OpenTelemetry (JSON)	span, attributi, eventi, genitore-figlio
`mcp`	Sessioni Model Context Protocol	definizioni di strumenti, coppie chiamata/risposta
`multi_agent`	Log multi-agente CrewAI / AutoGen / LangGraph	ruoli degli agenti, delega, passaggio di messaggi
`langchain`	Trace di callback LangChain	esecuzioni chain, chiamate LLM, invocazioni di strumenti
`langfuse`	Esportazioni di osservazioni LangFuse	generazioni, span, punteggi
`react`	Log ReAct-style Thought/Action/Observation	thought, action, action_input, observation
`webarena`	JSON trace WebArena / VisualWebArena	azioni, screenshot, snapshot DOM, URL
`atif`	Agent Trace Interchange Format (ATIF)	passi, osservazioni, metadati
`raw_web`	Registrazioni browser grezze (HAR + screenshot)	richieste, risposte, screenshot, tempi

Configurazione

Specifica il convertitore nella configurazione del progetto:

yaml

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:

yaml

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:

yaml

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:

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:

yaml

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 tre 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.

yaml

agentic:
  enabled: true
  trace_converter: openai
  display_type: agent_trace
 
  agent_trace_display:
    # Codifica cromatica per i tipi di passo
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
      system: "#6b7280"
 
    # Sezioni comprimibili
    collapse_observations: true
    collapse_threshold: 500    # caratteri prima della compressione automatica
 
    # Numerazione dei passi
    show_step_numbers: true
    show_timestamps: true
 
    # Rendering delle chiamate agli strumenti
    render_json: true          # formattazione JSON degli argomenti
    syntax_highlight: true     # evidenziazione del codice nelle osservazioni

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.

yaml

agentic:
  enabled: true
  trace_converter: webarena
  display_type: web_agent
 
  web_agent_display:
    # Rendering degli screenshot
    screenshot_max_width: 900
    screenshot_quality: 85
 
    # Overlay SVG per le azioni dell'agente
    overlay:
      enabled: true
      click_marker: "circle"       # circle, crosshair o arrow
      click_color: "#ef4444"
      click_radius: 20
      type_highlight: "#3b82f6"    # evidenziazione per i campi di input testo
      scroll_indicator: true
 
    # Vista a pellicola
    filmstrip:
      enabled: true
      thumbnail_width: 150
      show_action_labels: true
 
    # Display degli snapshot DOM
    show_dom_snapshot: false        # vista DOM grezza opzionale
    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 'Aggiungi al carrello'")
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.

yaml

agentic:
  enabled: true
  display_type: interactive_chat
 
  interactive_chat_display:
    mode: trace_review         # o "live_chat"
 
    # Impostazioni per la revisione trace
    trace_review:
      show_system_prompt: false
      show_token_counts: true
      show_latency: true
      message_grouping: turn    # "turn" o "message"
 
    # Impostazioni per la chat dal vivo (quando mode: live_chat)
    live_chat:
      proxy: openai             # proxy dell'agente da usare
      max_turns: 20
      timeout_seconds: 60
      show_typing_indicator: true
      allow_regenerate: true
 
    # Impostazioni comuni
    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.

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.

yaml

annotation_schemes:
  # Valutazione complessiva della trace
  - 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"
 
  # Valutazioni per turno
  - annotation_type: per_turn_rating
    name: step_correctness
    description: "Was this step correct?"
    target: agentic_steps        # si collega ai passi della trace
    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:

json

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

yaml

agentic:
  enabled: true
  display_type: interactive_chat
 
  agent_proxy:
    type: openai                 # openai, http o echo
 
    # Proxy OpenAI
    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:

yaml

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):

yaml

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):

yaml

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

Schemi di Annotazione Preconfigurati

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

Schema	Tipo	Descrizione
`agent_task_success`	radio	Successo/fallimento binario con opzione di credito parziale
`agent_step_correctness`	per_turn_rating (radio)	Valutazioni corretto/errato/non necessario per passo
`agent_error_taxonomy`	per_turn_rating (multiselect)	Tassonomia degli errori a 12 categorie (strumento errato, allucinazione, loop, ecc.)
`agent_safety`	radio + text	Rilevamento di violazioni di sicurezza con scala di gravità
`agent_efficiency`	likert	Valuta se l'agente ha usato un percorso efficiente
`agent_instruction_following`	likert	Valuta l'aderenza all'istruzione originale dell'utente
`agent_explanation_quality`	likert	Valuta la qualità dei ragionamenti/spiegazioni dell'agente
`agent_web_action_correctness`	per_turn_rating (radio)	Valutazione per passo delle azioni web (target corretto, tipo di azione corretto)
`agent_conversation_quality`	multirate	Qualità della chat multi-dimensionale (utilità, accuratezza, tono, sicurezza)

Carica uno schema preconfigurato per nome:

yaml

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

Oppure combina preset con schemi personalizzati:

yaml

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
 
  # Schema personalizzato accanto ai preset
  - 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:

yaml

# configurazione del progetto
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):

json

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

bash

potato start config.yaml -p 8000

Ulteriori Letture

Valutare Agenti AI: Una Guida Completa -- guida passo-passo a un progetto completo di valutazione degli agenti
Annotare Agenti di Navigazione Web -- guida alla valutazione di agenti web con screenshot e overlay
Modalità Solo -- combina l'annotazione agentiva con l'etichettatura collaborativa umano-LLM
Valutazioni per Turno per il Dialogo -- ulteriori opzioni di valutazione per turno
Formati di Esportazione -- esporta i dati di valutazione degli agenti

Per i dettagli di implementazione, consulta la documentazione sorgente.