Un agente che funziona non è un agente che non si rompe: è un agente i cui output sono utili, affidabili e migliorabili nel tempo. Questo modulo ti insegna a definire i criteri di qualità prima di andare in produzione, a trovare i pattern di errore sistematico nei log, e a modificare le istruzioni in modo strutturato — non per tentativi.
Prima di mettere in produzione un agente, devi rispondere a una domanda che sembra ovvia ma quasi nessuno si pone in modo esplicito: come farai a sapere se sta funzionando bene? Non si tratta di capire se l'agente "gira" senza errori tecnici — questo è il requisito minimo. Si tratta di stabilire in anticipo quali criteri usi per giudicare la qualità degli output che produce.
La distinzione è importante. Un agente che classifica email può non andare mai in errore tecnico e produrre output di qualità mediocre: assegna la categoria giusta all'80% dei casi, ma sistematicamente sbaglia a distinguere reclami da richieste di rimborso. Senza un criterio definito a priori, questa differenza resta invisibile nelle prime settimane. Emerge solo quando un cliente lamenta una risposta fuori contesto.
Il modo corretto di affrontare la fase Optimize è definire i criteri di qualità prima di raccogliere i primi dati di produzione, non dopo. I criteri definiti a posteriori tendono a essere distorti dai risultati che già si osservano — si misurano le cose che vanno bene, si trascurano quelle che vanno male.
La qualità degli output di un agente si misura su tre dimensioni distinte, ognuna delle quali richiede criteri e strumenti diversi. Confonderle genera valutazioni incomplete.
Per le PMI italiane del settore produzione e manifattura, la dimensione più critica in genere è la consistenza: gli agenti che gestiscono comunicazioni con fornitori o clienti B2B devono produrre risposte che rispettino il tono e il lessico aziendale in modo stabile, non solo in media. Una risposta eccellente il lunedì e una rischiosa il giovedì sono peggio di due risposte mediocri nello stesso giorno — perché la seconda si vede, la prima si nasconde.
Una metrica senza soglia è una metrica decorativa. Se misuri l'accuratezza ma non hai stabilito quale valore la rende accettabile, stai raccogliendo dati senza un criterio di azione. La domanda giusta non è "che accuratezza ha l'agente?" ma "sotto quale soglia di accuratezza smetti di fidarti dell'output e intervieni manualmente?"
Le soglie operative si definiscono prima del go-live, non dopo. Dipendono dal contesto specifico: un agente che genera bozze di preventivi per un'azienda manifatturiera può tollerare un 15% di errori se chi approva la bozza li intercetta sempre — ma un agente che pubblica comunicazioni automatiche deve avere una soglia molto più alta, perché il punto di controllo non c'è o è successivo all'invio.
| Tipo di output | Soglia minima consigliata | Ragione |
|---|---|---|
| Bozza con revisione umana obbligatoria | Accuratezza > 70% | Chi rivede intercetta l'errore prima che raggiunga il destinatario |
| Classificazione interna (log, tag, routing) | Accuratezza > 85% | L'errore genera inefficienze ma non danni diretti a clienti o fornitori |
| Output verso clienti/fornitori con punto di controllo debole | Accuratezza > 95% | Un errore su venti comunicazioni esterne è già un problema di reputazione |
| Output in contesti regolati (contratti, documentazione tecnica) | Verifica manuale al 100% | Nessuna soglia di automazione è accettabile senza validazione specialistica |
Nelle PMI manifatturiere B2B, gli agenti più comuni operano su comunicazioni con fornitori tecnici, gestione ordini, e reportistica interna. La soglia critica non è l'accuratezza media: è il tasso di errori nei casi limite — quelli con prezzi anomali, clausole di penale, eccezioni al processo standard. Definisci sempre una soglia separata per i casi limite, anche se rappresentano il 5% del volume totale.
Nel Modulo 3 hai costruito un nodo di log nel tuo workflow. Quel nodo non ha solo la funzione di tracciare le esecuzioni: è lo strumento principale con cui misurerai la qualità dell'agente nelle prime settimane di produzione. La differenza tra un log utile e un log decorativo è la struttura dei campi che registra.
Un log utile per la fase Optimize deve contenere almeno: il timestamp dell'esecuzione, l'input (o una sua sintesi), l'output prodotto dall'agente, la categoria o classificazione assegnata, e — quando possibile — l'esito reale dell'operazione (cosa è successo dopo). Questo ultimo campo è il più difficile da raccogliere automaticamente, ma è il più prezioso: è quello che ti permette di confrontare la previsione dell'agente con la realtà.
Un log che registra solo gli errori tecnici dice solo quando l'agente si è fermato, non quando ha prodotto risultati sbagliati. Per le prime settimane di produzione, aggiungi sempre una colonna "verifica manuale" che l'operatore può compilare: anche un campione del 20-30% degli output è sufficiente per costruire un quadro affidabile della qualità reale.
La capacità di definire criteri di qualità verificabili e di strutturare processi di monitoraggio sistematico è una competenza digitale fondamentale nella gestione di sistemi AI in contesti lavorativi. L'AI Act richiede che i sistemi AI utilizzati in contesti professionali siano soggetti a supervisione umana e a forme documentate di verifica della qualità degli output, in particolare quando producono effetti su terzi.
Tutti gli agenti commettono errori. Il problema non è l'errore in sé: è il pattern che emerge quando gli errori si ripetono. Un errore casuale è quello che capita quando un input è formulato in modo insolito, o quando il contesto è ambiguo. Un errore sistematico è quello che si ripresenta nelle stesse condizioni — stesso tipo di input, stesso tipo di output sbagliato.
La distinzione ha un impatto operativo diretto. Un errore casuale richiede una soglia di tolleranza e un punto di controllo a valle. Un errore sistematico richiede una modifica alle istruzioni dell'agente — perché si ripeterà indefinitamente, indipendentemente dal volume. Trattare un errore sistematico come se fosse casuale è uno degli sprechi più frequenti nella fase Optimize: il team continua a correggere manualmente output che potrebbero essere risolti alla radice con una modifica al system prompt.
L'obiettivo di questa lezione è darti gli strumenti per distinguere i due tipi di errore nel log di produzione, e per identificare i pattern senza dover analizzare ogni singolo output.
Analizzare il 100% degli output di un agente attivo non è praticabile oltre le prime ore di test. Nella fase Optimize hai bisogno di un criterio di campionamento che massimizzi la probabilità di trovare errori sistematici senza richiedere una revisione completa.
Il criterio più efficace per le PMI è il campionamento per categoria: invece di analizzare un campione casuale di output, analizzi tutti gli output di un sottoinsieme specifico — tutti i ticket assegnati a una categoria insolita, tutte le email classificate come "reclamo prioritario", tutte le bolle con importo superiore a una soglia. Questo approccio intercetta gli errori sistematici nei casi limite molto prima di quanto farebbe un campione casuale dello stesso volume.
Nell'analisi di agenti per PMI italiane, cinque pattern di errore sistematico emergono con frequenza significativamente superiore agli altri. Conoscerli ti permette di cercarli attivamente nel log invece di aspettare che diventino evidenti attraverso reclami o correzioni manuali accumulate.
| Pattern | Come si manifesta | Causa tipica nelle istruzioni |
|---|---|---|
| Sovra-classificazione | L'agente usa una categoria come "altro" di fatto, assegnandola ogni volta che l'input non corrisponde perfettamente alle categorie principali | Le categorie nel system prompt non coprono i casi limite più frequenti nel dominio specifico |
| Ambiguità di priorità | L'agente non distingue correttamente tra casi urgenti e casi standard quando entrambi usano lo stesso lessico di base | Il system prompt definisce "urgente" in modo generico senza esempi contestuali specifici |
| Deriva di formato | L'output segue il formato corretto all'inizio e poi inizia a variare — campi in ordine diverso, lunghezze diverse, chiavi JSON con nomi leggermente diversi | Le istruzioni di formato non specificano i casi limite, solo il caso standard |
| Contesto ignorato | L'agente produce output corretto per l'input testuale ma ignora informazioni contestuali fornite (storico, tipo cliente, categoria precedente) | Il system prompt non specifica come usare il contesto aggiuntivo né quale peso dargli rispetto all'input corrente |
| Escalation mancata | L'agente non attiva il percorso di fallback nei casi che lo richiederebbero, producendo un output invece di segnalare l'incapacità di gestire il caso | Le condizioni di escalation sono definite in modo troppo restrittivo o con esempi solo positivi |
Nell'analisi degli errori sistematici, una parte degli output sbagliati non dipende dalle istruzioni dell'agente ma dalla qualità degli input che riceve. Questo è un punto critico che molti team sottovalutano nelle prime settimane di produzione: cercano il problema nel system prompt quando il problema è nel dato di ingresso.
Tre segnali indicano che il problema è nell'input, non nell'agente. Primo: l'agente produce output imprevedibili solo su un sottoinsieme di input, e quel sottoinsieme ha qualcosa in comune nella struttura — email con allegati, ordini con codici prodotto non standard, bolle con intestazione di formato diverso dal consueto. Secondo: la correzione manuale dell'input produce l'output corretto senza cambiare nulla nelle istruzioni. Terzo: il pattern di errore cambia nel tempo, in modo correlato a cambiamenti nei sistemi o nei fornitori che generano gli input.
In questi casi, la soluzione corretta non è modificare le istruzioni ma migliorare il pre-processing degli input: aggiungere un nodo di normalizzazione prima del nodo AI, definire regole di validazione nel trigger, o rivedere il formato dei dati che arrivano dai sistemi a monte.
La capacità di distinguere tra errori imputabili al sistema AI e quelli imputabili alla qualità dei dati di ingresso è una competenza tecnica fondamentale per chi gestisce agenti in produzione. L'AI Act richiede che i sistemi AI ad alto impatto mantengano log sufficienti a permettere l'identificazione della causa degli errori — distinguendo tra malfunzionamento del modello e qualità dei dati di input.
Domanda 1: Quale dei cinque pattern di errore sistematico descrive meglio questo caso?
Domanda 2: Quale modifica al system prompt risolve il problema alla radice?
La tentazione più comune nella fase Optimize è modificare le istruzioni in modo intuitivo — aggiungere una frase qui, cambiare un esempio là — e poi osservare se la situazione migliora. Questo approccio ha un problema strutturale: quando le modifiche sono multiple e non documentate, non sai quale cambiamento ha prodotto il miglioramento osservato. E soprattutto non sai quali cambiamenti hanno introdotto regressioni in altri comportamenti dell'agente che non stavi monitorando.
Il concetto di regressione è centrale nella gestione degli agenti in produzione. Una regressione è un comportamento che funzionava correttamente e che si rompe in seguito a una modifica non correlata. Negli agenti AI è molto più comune che nel software tradizionale, perché le istruzioni in linguaggio naturale hanno effetti collaterali difficili da prevedere: aggiungere un esempio per correggere il pattern di sovra-classificazione può modificare il comportamento dell'agente su input che non avevi mai testato.
L'iterazione strutturata risolve questo problema con un metodo semplice: una modifica alla volta, con test su un set fisso di casi, documentazione prima e dopo. Non richiede strumenti specializzati — funziona con un foglio di calcolo e un processo definito.
Il ciclo che segue è progettato per le PMI che gestiscono agenti no-code su Make o n8n, senza un team tecnico dedicato. Richiede circa 30-60 minuti per iterazione, a seconda della complessità del caso.
Non tutte le modifiche alle istruzioni hanno lo stesso impatto. Alcune categorie di modifica sono più efficaci di altre a seconda del tipo di pattern che stai cercando di correggere. Conoscerle riduce il numero di iterazioni necessarie.
| Tipo di modifica | Efficace per | Rischio di regressione |
|---|---|---|
| Aggiunta di esempi (few-shot) | Ambiguità di classificazione, definizione di casi limite specifici | Basso — gli esempi aggiuntivi raramente alterano il comportamento sugli altri input |
| Aggiunta di regola IF/THEN | Comportamenti condizionali, escalation mancata, priorità ambigue | Medio — una regola mal formulata può catturare casi che non dovrebbe |
| Ridefinizione di una categoria o concetto | Sovra-classificazione, deriva di formato | Alto — cambiare la definizione di una categoria può rompere le classificazioni già corrette |
| Modifica dell'ordine delle istruzioni | Contesto ignorato, quando il modello dà troppo peso alle ultime istruzioni | Alto — l'ordine ha effetti non lineari sul comportamento del modello |
| Aggiunta di istruzione di formato | Deriva di formato, campi mancanti nell'output | Basso se limitata al formato, alto se tocca il contenuto |
Inizia sempre dalla modifica a rischio più basso che può risolvere il problema. Se aggiungere un esempio risolve il caso, non riscrivere la definizione della categoria. La complessità del system prompt tende ad aumentare nel tempo — ogni modifica dovrebbe essere la più piccola possibile che produce il risultato atteso.
L'ottimizzazione di un agente non finisce quando l'agente è perfetto — finisce quando il beneficio marginale di un'ulteriore iterazione è inferiore al costo del tempo richiesto. Per le PMI, questo punto arriva prima di quanto ci si aspetti: nella maggior parte dei casi, dopo tre o quattro cicli di iterazione strutturata, i pattern di errore più impattanti sono stati corretti e i rimanenti rientrano nella soglia di tolleranza definita prima del go-live.
Continuare a ottimizzare oltre quel punto genera due rischi. Il primo è il rischio di regressione: più il system prompt cresce, più è difficile prevedere gli effetti di una nuova modifica. Il secondo è il rischio di perfezionismo: cercare di eliminare ogni errore residuale porta a istruzioni così specifiche e rigide che l'agente smette di gestire correttamente i casi leggermente diversi da quelli su cui è stato ottimizzato.
Il segnale operativo che indica quando fermarsi è chiaro: quando il tasso di errori corretti manualmente è stabile e rientra nella soglia operativa definita prima del go-live, e quando due iterazioni consecutive non producono miglioramenti statisticamente rilevanti, è il momento di passare al Pilot vero e proprio.
La gestione strutturata del ciclo di ottimizzazione di un agente AI rientra nella competenza digitale di problem solving applicato ai sistemi automatizzati. L'AI Act prevede che i sistemi AI soggetti a requisiti di gestione del rischio siano oggetto di revisione continua, con documentazione delle modifiche e dei test effettuati — un requisito pienamente soddisfatto dal ciclo di iterazione strutturata in cinque passaggi descritto in questa lezione.
Genera un file Markdown con tutti i prompt pronti all'uso di questo modulo, la tua riflessione e il ciclo di iterazione che hai costruito.
Cos'è un file .md? È un file di testo con una formattazione semplice. Puoi aprirlo con Blocco note o TextEdit — vedrai il testo con qualche simbolo di formattazione. Per visualizzarlo con titoli e sezioni già formattati, importalo in Notion trascinando il file nella barra laterale.
© 2025 AI ADOPT™ — Tutti i diritti riservati.