Come creare un dataset di valutazione per Agent: task reali, traiettorie e test di regressione

La settimana scorsa l’Agent dei report giornalieri generava ancora i report senza problemi. Dopo un upgrade del modello, continua a restituire un riepilogo finale che sembra corretto, ma nella traiettoria mancano il controllo dei permessi e il tool di aggiornamento dei dati. Un Agent di supporto dà la risposta finale giusta, ma chiama il tool di rimborso con argomenti sbagliati; un benchmark pubblico non vede questo rischio. In una retrospettiva di incidente ci sono già traceId, tool call, approvalId, state event e giudizio umano, ma nulla è stato trasformato in un test obbligatorio prima del prossimo release.

Questo tipo di regressione non si copre cambiando modello o lanciando un’altra demo. Un dataset di valutazione per Agent deve partire dalla distribuzione reale dei task e dalle traiettorie di errore in produzione: tool calls, formati degli argomenti, transizioni di stato, approval records e human labels. Poi deve entrare in CI come gate di regressione. Qui partiamo da errori e scenari reali: come costruire un eval dataset sostenibile che protegga il confine di qualità di ogni release.

1. Perché i benchmark pubblici non bastano

1.1 I limiti dei benchmark pubblici

I benchmark pubblici misurano la capacità del modello, non la qualità dei tuoi task di business. Dataset come AgentBench e WebArena offrono task standardizzati, ma non coprono la toolchain, il modello di permission e la state machine del tuo team.

Per esempio, il tuo Agent di reporting potrebbe dover chiamare check_permission, refresh_data e generate_report nell’ordine “controlla → aggiorna → genera”. Un benchmark pubblico non testerà quel flusso, perché non conosce i tuoi tool schema né i confini di permission.

Un buon punteggio su un benchmark pubblico non significa che un task di business non possa regredire. Un dataset di valutazione per Agent deve misurare la tua distribuzione reale dei task, non una capacità di reasoning generale.

1.2 Il valore principale di un dataset interno

Un eval dataset interno cattura rischi che i benchmark pubblici non vedono. Ecco un confronto tipico:

Usa i benchmark pubblici per scegliere il modello; usa il dataset interno per proteggere i release gate. Si completano, ma non si sostituiscono. Se hai già letto Benchmark di valutazione degli Agent, sai quali evaluation set pubblici aiutano nella scelta. Qui il punto è costruire dati di valutazione dal tuo ambiente di produzione.

2. Campi chiave di un Agent eval dataset

2.1 Campi obbligatori

Un Agent eval dataset non è solo un elenco di input utente e risposte attese. Deve registrare traiettorie di tool calls, transizioni di stato e giudizi umani. I campi obbligatori sono questi:

LangSmith, in Evaluation concepts, consiglia di coprire scelta degli strumenti, formato degli argomenti e traiettoria di esecuzione nella valutazione degli Agent, non solo la risposta finale. OpenAI Agents SDK Tracing offre campi come trace_id, workflow_name e span per registrare tool calls ed eventi di stato, ma questi campi grezzi vanno anonimizzati ed estratti prima di entrare in un dataset.

2.2 Campi opzionali

Aggiungi questi campi in base alle esigenze del business:

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

Se hai letto il modello di permission degli Agent (N157) e il design della human approval (N155), sai che approval records deve registrare step di approvazione, approvatore e risultato, così da verificare che un’azione ad alto rischio sia stata approvata.

2.3 Anonimizzazione e privacy

Un production trace non può entrare così com’è nel set di valutazione. La documentazione di OpenAI Agents SDK Tracing ricorda che alcuni span possono catturare input/output del modello o input/output di function tool; bisogna quindi configurare se includere dati sensibili.

Campi da anonimizzare obbligatoriamente: PII (nome, email, telefono), secret (API key, password del database), dati cliente (numero d’ordine, importo della transazione).

Campi da conservare: traceId, span_id per diagnosi, workflow_name per classificazione, nome del tool e nome dello stato per le assertion.

I metodi di anonimizzazione includono sostituzione con placeholder come <user_id>, hashing o eliminazione. La documentazione Phoenix Running Evals on Traces mostra che i trace possono diventare input di valutazione, ma servono comunque label, score e rubric. Non mettere un trace grezzo completo direttamente nell’eval dataset.

3. Dal production trace all’eval example

3.1 Flusso di raccolta dati

Per trasformare un production trace in un eval example servono quattro passaggi: anonimizzazione, labeling, stratificazione e salvataggio. Non è un intervento una tantum, ma lavoro operativo continuo.

Checklist:

1. Esporta i trace falliti dalla piattaforma di monitoring (vedi Monitoring degli Agent e recupero dagli errori).
2. Classifica per tipo di errore: errore di tool call, errore di formato degli argomenti, errore di transizione di stato, errore di risposta finale.
3. Anonimizza: rimuovi PII/secret/dati cliente e conserva traceId, span_id, workflow_name.
4. Aggiungi label umane: corretto/errato/parzialmente corretto + motivo dell’errore.
5. Salva per livello: golden set / negative cases / edge cases.

La documentazione Phoenix datasets indica che gli examples possono arrivare da production, staging, evaluations o manual. La produzione fornisce la distribuzione reale dei task; lo staging aiuta a completare gli scenari di bordo.

3.2 Criteri di stratificazione

Dimensioni di labeling, allineate a una rubric LLM-as-judge: correttezza della scelta degli strumenti, correttezza del formato degli argomenti, correttezza dell’ordine di esecuzione, qualità della risposta finale, allineamento con le label umane.

OpenAI Evaluation best practices consiglia dati di test con typical, edge e adversarial cases, usando human expert labellers. La stratificazione qui segue quell’idea, ma enfatizza task frequenti e pattern di errore tipici, perché lo scopo del set di valutazione è proteggere il release gate, non coprire ogni scenario possibile.

4. Come scrivere trajectory assertions

4.1 Tipi di vincoli sulla traiettoria

Le trajectory assertions definiscono le regole che l’Agent deve rispettare per tool calls, formato degli argomenti, transizioni di stato e approval. Cinque tipi comuni:

LangSmith Evaluation concepts cita trajectory, tool selection e argument formatting come parti della valutazione degli Agent. Phoenix Running Evals on Traces usa span_id per collegare il risultato di valutazione a un segmento di esecuzione specifico; questo mostra che le assertion sulla traiettoria possono puntare allo span fallito.

Se hai letto la valutazione della capacità di pianificazione degli Agent (N158) e i confini tra state machine e prompt, sai che i campi di traiettoria dello stato vengono da state/event/checkpoint. Servono a verificare che le transizioni seguano l’ordine atteso.

4.2 Esempio di codice

Ecco uno pseudocodice per trajectory assertions in una valutazione generica di Agent:

# Esempio di trajectory assertions
def assert_trajectory_correct(result):
    # Estrae la lista dei tool calls
    tools_called = [call.tool for call in result.tool_calls]

    # Tool obbligatori
    required_tools = ["check_permission", "refresh_data"]
    for tool in required_tools:
        assert tool in tools_called, f"Missing required tool: {tool}"

    # Tool vietati
    forbidden_tools = ["delete_user"]
    for tool in forbidden_tools:
        assert tool not in tools_called, f"Called forbidden tool: {tool}"

    # Vincoli sul formato degli argomenti
    for call in result.tool_calls:
        if call.tool == "refund":
            assert isinstance(call.args["refund_amount"], (int, float)), "refund_amount must be number"
            assert len(call.args["user_id"]) == 36, "user_id must be uuid format"

    # Ordine delle transizioni di stato
    expected_states = ["init", "check", "approve", "execute"]
    actual_states = [event.state for event in result.state_events]
    assert actual_states == expected_states, "State transition order mismatch"

    # Presenza dello step di approval
    approval_events = [e for e in result.state_events if e.type == "approval"]
    assert len(approval_events) >= 1, "Missing approval step"

Questo codice mostra come controllare tool obbligatori, tool vietati, formato degli argomenti, ordine delle transizioni di stato e step di approval. In una implementazione reale puoi usare le trajectory assertion di LangSmith o i trace eval di Phoenix, ma la logica di base resta la stessa.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

Se hai letto Valutazione della pianificazione degli Agent, sai che anche le traiettorie di pianificazione possono diventare campioni di regressione per verificare task decomposition e self-correction.

5. Rubric a livelli per LLM-as-judge

5.1 Perché il punteggio totale non basta

Se LLM-as-judge restituisce solo un punteggio totale, il risultato oscilla ed è difficile da diagnosticare. Un 80 può significare che la scelta degli strumenti era sbagliata ma la risposta è risultata corretta per caso; oppure che la risposta era sbagliata ma il formato sembrava buono. Non puoi distinguere se il problema è nel prompt, nel tool schema, nel retrieval o nella state machine.

LangSmith Evaluation concepts consiglia di definire criteri di qualità per i componenti chiave dell’Agent: correct tool selection, proper argument formatting e trajectory. Valutare ogni componente separatamente rende molto più rapido localizzare regressioni dopo un cambio di modello o prompt.

Se hai letto Pratiche avanzate di prompt engineering, sai che anche DeepEval enfatizza metriche a livelli come TaskCompletenessMetric, non solo l’output finale.

5.2 Tabella di scoring a livelli

La rubric seguente divide la valutazione degli Agent in cinque dimensioni, ciascuna con 0-2 punti:

Esempio di configurazione rubric per LangSmith o Phoenix:

rubric:
  dimensions:
    - name: tool_selection
      weight: 0.3
      criteria:
        0: "Ha chiamato il tool sbagliato"
        1: "Ha chiamato alcuni tool corretti"
        2: "Scelta degli strumenti completamente corretta"

    - name: argument_formatting
      weight: 0.2
      criteria:
        0: "Tipo dell'argomento errato"
        1: "Alcuni campi hanno errori di formato"
        2: "Formato degli argomenti completamente corretto"

    - name: execution_order
      weight: 0.2
      criteria:
        0: "La transizione di stato salta o si ripete"
        1: "Ordine di esecuzione con deviazioni"
        2: "Ordine di esecuzione completamente corretto"

    - name: final_answer_quality
      weight: 0.2
      criteria:
        0: "Non soddisfa la richiesta dell'utente"
        1: "Soddisfa parzialmente la richiesta"
        2: "Soddisfa completamente la richiesta"

    - name: human_alignment
      weight: 0.1
      criteria:
        0: "Contraddice il giudizio esperto"
        1: "Parzialmente allineato"
        2: "Molto allineato"

La scelta degli strumenti ha il peso più alto (0.3), perché il nucleo di un Agent è chiamare lo strumento corretto. L’allineamento con la label umana ha il peso più basso (0.1), perché serve soprattutto a calibrare quanto LLM-as-judge concorda con il giudizio esperto.

6. Release gate e test di regressione

6.1 Passaggi di integrazione CI

Il valore di un Agent eval dataset emerge quando entra in CI come release gate. Il flusso è questo:

Checklist:

1. Aggiungi uno step di eval nella CI pipeline, per esempio pytest, LangSmith offline eval o Phoenix experiments.
2. Configura una soglia di pass rate, per esempio 90%.
3. Richiedi che il golden set passi completamente (100%).
4. Configura regole di alert per i negative cases. Possono notificare il team senza bloccare.
5. Imposta un confronto tra versioni (improvement/regression) tra baseline e versione corrente.
6. Definisci quando scatta il gate: PR / merge / canary.

LangSmith Evaluation concepts spiega che le offline evaluations possono essere usate per regression testing, unit testing e backtesting sugli examples nei datasets. La documentazione Phoenix experiments descrive il confronto di modifiche a prompt, LLM o logica applicativa per valutare improvement/regression. DeepEval descrive eval pytest-native eseguibili in CI/CD o Python scripts, usando LLMTestCase e TaskCompletenessMetric per valutare Agent trace a livelli.

6.2 Tabella delle soglie

Esempio di configurazione CI:

evaluation:
  triggers:
    - pull_request
    - merge_to_main
    - canary_deployment

  conditions:
    pass_rate: 0.9
    golden_set: 1.0
    no_regression: true

  notifications:
    on_failure: ["team-lead", "on-call"]
    on_negative_alert: ["team-lead"]

I trigger includono PR, per impedire a codice problematico di entrare in main; merge, per verificare che lo stato unito soddisfi ancora le condizioni; e canary, per validare prima del traffico di produzione. Se hai letto controllo dei costi e model routing (N156), sai che anche le soglie di costo possono diventare condizioni di gate. Qui restiamo sulle soglie di valutazione.

7. Retrospettiva di un caso reale

7.1 Descrizione dello scenario

L’Agent del report giornaliero funzionava correttamente la settimana scorsa: chiamava check_permission per verificare i permessi, refresh_data per aggiornare i dati e poi generate_report per generare il report. Dopo l’upgrade del modello, l’Agent restituisce ancora un riepilogo finale che sembra corretto, ma nella traiettoria mancano check_permission e refresh_data.

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

L’utente riceve un report senza controllo dei permessi e con dati vecchi, ma in superficie non si nota. Un benchmark pubblico non rileva questo rischio, perché non ha il tuo tool schema né la tua state machine.

7.2 Individuazione del problema

Esporta il trace fallito dalla piattaforma di monitoring (vedi Monitoring degli Agent e recupero dagli errori). L’analisi della traiettoria mostra che la lista dei tool calls non contiene check_permission né refresh_data, la transizione di stato salta da init direttamente a execute, mancano check e approve, e la risposta finale sembra corretta anche se la fonte dati non è stata aggiornata.

Label: errore di scelta dello strumento + salto di transizione di stato.

7.3 Aggiornamento del dataset

Aggiungi il caso di errore ai negative cases. Rafforza anche il golden set: trova il task di report giornaliero riuscito la settimana precedente, includi la sequenza completa di tool calls e assegnagli la label di caso corretto.

Aggiorna le trajectory assertions: aggiungi check_permission e refresh_data alla required tool list, e imposta l’assertion sull’ordine degli stati a ["init", "check", "approve", "execute"].

7.4 Intercettazione da parte del CI gate

La PR successiva avvia un’esecuzione eval. Il negative case genera un alert: manca la chiamata a check_permission. Il golden set passa completamente, quindi il caso di successo di riferimento è ancora integro.

La causa è nel prompt. Dopo l’upgrade, il modello interpreta “genera un report” come esecuzione diretta e ignora il controllo preliminare e l’aggiornamento dei dati.

7.5 Correzione e regressione

Correggi il prompt, specificando che prima di generare il report l’Agent deve verificare i permessi e aggiornare i dati. Esegui di nuovo eval: il pass rate sale dall’85% al 95%, il negative case passa senza alert, il golden set passa completamente e il confronto di versione mostra improvement senza regression.

Merge e release. Il CI gate ha fermato questa regressione prima della produzione.

7.6 Tabella di mapping dei campi

Questo ciclo mostra il percorso completo dal production failure al test di regressione. Dopo ogni retrospettiva di incidente, trasforma traceId, tool call, approvalId, state event e giudizio umano in un eval example. Così il release successivo non inciampa nello stesso errore.

8. Cosa leggere dopo

• State machine degli Agent e confini del prompt: capire da dove vengono i vincoli di transizione di stato e i campi di trajectory assertion
• Modello di permission degli Agent: capire approval records e regole per tool calls ad alto rischio
• Design della human approval: trasformare approval records e flussi di approvazione in test duraturi
• Controllo dei costi e model routing: capire come le soglie di costo diventano condizioni di gate
• Monitoring degli Agent e recupero dagli errori: esportare failed traces e costruire un ciclo di retrospettiva degli incidenti