L'Harness di Eval che Uso per Rilasciare Agenti IA Senza Paura

Indice dei contenuti

Aggiornato giugno 2026.

TL;DR: Il motivo per cui posso modificare un prompt o sostituire un modello su un agente in produzione senza trattenere il respiro è una cosa sola: un harness di eval. Un insieme fisso di casi di test valutati, calcolati automaticamente — assertion rigide dove posso scriverle, un giudice LLM dove non posso — eseguito prima di ogni modifica. Se il punteggio regge, rilascio. Se cala, no. Il set di test non è sintetico; è costruito dai fallimenti reali in produzione, così ogni bug diventa un test di regressione permanente.

Lettura dell’operatore: Su oltre 100 agenti, la differenza tra quelli che tocco con sicurezza e quelli di cui ho paura sta nel fatto che abbiano o meno degli eval. Nessun harness di eval significa che ogni ritocco al prompt è una scommessa. Un harness di eval trasforma “credo che questo sia meglio” in “questo è misurabilmente 4 punti migliore e non ha rotto nulla”. È tutto lì lo sblocco.

Non rilasceresti codice senza test. La gente rilascia agenti senza eval di continuo, poi si chiede perché un “piccolo ritocco al prompt” ha rotto la produzione. Un harness di eval è la suite di test per il software non deterministico. Ecco quello che eseguo davvero.

Parti da un set di test costruito sui fallimenti reali

L’harness vale tanto quanto i suoi casi di test, e i casi migliori vengono dalla produzione, non dalla tua immaginazione. Ogni volta che un agente fallisce sul campo, catturo l’input esatto (registro ogni esecuzione con un trace ID — vedi come fare il debug di un agente in produzione) e lo trasformo in un caso di eval:

interface EvalCase {
  id: string;
  input: AgentInput;        // l'input esatto di produzione
  expected?: string;        // ground truth, quando esiste
  assertions: Assertion[];  // controlli rigidi che devono passare
  rubric?: string;          // per il giudice LLM, quando l'output è aperto
}

Due pratiche contano qui. Attingi dalla produzione, così i tuoi eval testano ciò che si rompe davvero, non ciò che hai immaginato potesse rompersi. E copri lo spettro — il percorso felice, i casi limite, gli input avversariali e gli input vuoti/malformati che causano fallimenti silenziosi. Un set di test di 30-50 casi ben scelti cattura molto più di 500 pigri. Preferisco avere 40 casi che rappresentino ciascuno un reale modo di fallimento piuttosto che mille che testano tutti lo stesso percorso facile.

Valuta prima con le assertion, poi con un giudice LLM

Non ogni output ha bisogno di un modello che lo valuti. Ricorro al valutatore più economico che funzioni.

Assertion rigide per tutto ciò che è strutturato. L’output si parsa come JSON valido? Contiene il campo richiesto? La data estratta è nell’intervallo? Ha chiamato lo strumento giusto con gli argomenti giusti? Sono deterministiche, gratuite e inequivocabili — scrivine quante più puoi.

const assertions: Assertion[] = [
  (out) => isValidJSON(out),
  (out) => parse(out).category in ALLOWED_CATEGORIES,
  (out) => parse(out).confidence >= 0 && parse(out).confidence <= 1,
];

Un giudice LLM per il resto aperto — tono, utilità, “ha davvero risposto alla domanda”. Qui dai a un modello l’input, l’output e una rubrica, e gli chiedi di valutare. Due regole mantengono onesto il giudice: rendi la rubrica specifica (una scala da 1 a 5 con ancore descritte batte “valuta la qualità”), e usa un modello forte come giudice — giudicare è un compito di ragionamento, quindi questo è un punto in cui pago volentieri per Sonnet anche quando l’agente stesso gira su Haiku secondo la matematica dei costi. Una rubrica vaga o un giudice debole ti dà rumore che sembra segnale.

Esegui l’harness prima di ogni modifica

L’harness esiste per rispondere a una domanda: questa modifica ha reso l’agente migliore o peggiore? Quindi lo eseguo prima di ogni modifica al prompt, sostituzione di modello o cambio di strumento.

# baseline su main
npm run eval -- --suite=booking-agent > baseline.json

# fai la modifica, poi riesegui
npm run eval -- --suite=booking-agent > candidate.json

# confronta
npm run eval:diff baseline.json candidate.json

Il diff mostra il punteggio aggregato, il passa/fallisce per caso e — cosa cruciale — quali casi specifici sono regrediti. Un aggregato che sale mentre tre casi si rompono in silenzio non è un miglioramento; è uno scambio che voglio vedere e approvare, non uno che si insinua. Sorvegliare il diff per caso è come eviti “ho sistemato una cosa, ne ho rotte altre due”, il modo di fallimento che fa avere paura alla gente dei propri prompt.

Imposta un gate di regressione e lascia che blocchi

Una volta che ti fidi dell’harness, collegalo al percorso verso la produzione come gate. La mia regola è netta: una modifica che fa scendere il punteggio sotto la soglia di baseline non si rilascia. Non “ci guarderò dopo” — è bloccata, esattamente come un test CI fallito.

const PASS_THRESHOLD = 0.90; // il 90% dei casi deve passare
if (candidate.passRate < PASS_THRESHOLD || candidate.passRate < baseline.passRate) {
  throw new Error(`Eval regression: ${candidate.passRate} < ${baseline.passRate}`);
}

È questo che trasforma gli eval da un optional nella cosa che ti permette di muoverti veloce. Il gate è ciò che rende “rilasciare senza paura” letteralmente vero: lo scenario peggiore per una modifica sbagliata è un’esecuzione di eval in rosso, non un incidente in produzione. E poiché il set di test cresce ogni volta che qualcosa si rompe, il gate diventa più rigido e più protettivo nel tempo, da solo.

Tieni conto del non-determinismo nella valutazione

Una sottigliezza che fa inciampare la gente: lo stesso input può ottenere punteggi diversi tra le esecuzioni perché il modello campiona in modo diverso. Se esegui ogni caso una volta sola, vedrai regressioni fantasma — un caso “rotto” che in realtà è solo rumore di campionamento.

Due mitigazioni. Esegui gli eval a temperature: 0 per ridurre la varianza (non la eliminerà del tutto). E per i casi che hai visto vacillare, eseguili N volte e prendi il tasso di successo, non un singolo passa/fallisce. Un caso che passa 9 su 10 è in forma migliore di uno che passa 5 su 10 anche se entrambi possono mostrare una singola esecuzione verde. È lo stesso principio del volume-sull’aneddoto che uso quando faccio il debug di fallimenti intermittenti — un’esecuzione è un’opinione, cinquanta esecuzioni sono dati.

Chiudi il ciclo con il monitoraggio in produzione

L’harness di eval testa contro casi noti. La produzione ne lancia di inediti. Quindi il ciclo è: monitora il comportamento dal vivo, cattura un nuovo modo di fallimento, trasformalo in un caso di eval, sistemalo, e ora è protetto in modo permanente. Il lato del monitoraggio — tracciare il tasso di successo, la validità dell’output e il costo per esecuzione sul traffico dal vivo — è ciò che copro in come misuro se un agente IA funziona davvero. Eval e monitoraggio sono due metà dello stesso sistema: il monitoraggio trova i bug, gli eval si assicurano che restino morti.

Quel ciclo di feedback è il vero prodotto. Qualsiasi singolo set di eval invecchia; un processo che converte ogni fallimento in produzione in un test permanente si rafforza ogni settimana. È così che un agente passa da “spaventoso da toccare” a qualcosa che rifattorizzo un venerdì pomeriggio senza battere ciglio.

FAQ

Cosa entra in un set di eval per un agente IA?

Input reali di produzione trasformati in casi valutati — percorso felice, casi limite, input avversariali e malformati — ciascuno con assertion rigide e, per gli output aperti, una rubrica per il giudice LLM. Da 30 a 50 casi tratti da fallimenti reali battono centinaia di casi sintetici che testano tutti il percorso facile.

Dovrei usare un LLM per valutare gli output dell’agente?

Usa assertion rigide ovunque l’output sia strutturato (JSON valido, campo corretto, chiamata allo strumento giusto) — sono gratuite e deterministiche. Riserva un giudice LLM per qualità aperte come tono e utilità, con una rubrica specifica e un modello giudice forte così ottieni segnale, non rumore.

Come impedisco a una modifica del prompt di rompere la produzione in silenzio?

Esegui l’harness di eval prima di ogni modifica e fai il diff contro una baseline, sorvegliando le regressioni per caso, non solo il punteggio aggregato. Poi vincola i deploy al risultato così che ogni modifica che scende sotto la soglia di baseline venga bloccata come un test fallito.

Come gestisco il non-determinismo negli eval?

Esegui a temperatura 0 per ridurre la varianza, e per i casi che vacillano, eseguili più volte e valuta il tasso di successo invece di una singola esecuzione. Un caso che passa 9 volte su 10 è più sano di uno che passa 5 su 10, anche se una singola esecuzione li mostra entrambi verdi.