Checklist di produzione per Agent IA: log, monitoraggio, alert, rollback e canary release
"OpenAI Agents SDK tracing registra LLM generations, tool calls, handoffs, guardrails e custom events, e può essere usato per debugging, visualizzazione e monitoraggio in sviluppo e produzione."
È venerdì pomeriggio e stai per aprire l’Agent di customer support al 5% degli utenti. I parametri del canary sono pronti: percentuale di traffico, finestra di osservazione, soglie di alert. Nell’ultimo controllo emergono tre problemi:
- Non c’è un feature flag; per spegnerlo serve un nuovo deploy.
- Nessuno sa come riportare alla vecchia versione le attività già nella coda di approvazione umana.
- Non è chiaro se le e-mail già inviate siano effetti collaterali degli strumenti, né se il rollback debba ritirarle.
Questi tre problemi non emergono da un HTTP 500 o da un tempo di risposta alto. Il lancio di un Agent richiede otto dimensioni in più rispetto a un servizio web: trace, tool calls, guardrails, HITL, eval, cost, secrets, checkpoint. Questa checklist le organizza in quattro gruppi: gate pre-release, osservazione del canary, monitoraggio post-release e rollback degli incidenti.
1. Gate pre-release: dieci controlli che devono passare
1.1 Controllo di completezza del Trace
Prima del release bisogna confermare che il trace possa ricostruire un Agent run completo. In caso contrario, un incidente diventa difficile da analizzare. OpenAI Agents SDK integra tracing e registra LLM generations, tool calls, handoffs, guardrails e custom events, ma va verificato se queste informazioni restano complete in produzione.
Checklist:
- run ID, trace ID e span ID sono collegati correttamente, così un log di errore può risalire alla richiesta precisa.
- model call, tool call e guardrail result vengono registrati integralmente, senza campi mancanti.
- i campi di durata, uso dei token e codice di errore sono disponibili, così si possono calcolare baseline di costo e performance.
- la retention dei trace e le regole di mascheramento sono esplicite, senza eliminare dati utili per costo di storage o rischio compliance.
- il comportamento di export dei trace è coerente tra sviluppo e produzione.
Se il trace registra solo il LLM call, senza tool call o guardrail result, il canary può sembrare sano con HTTP 200 anche mentre gli argomenti degli strumenti sono sbagliati o i permessi superano il limite.
1.2 Strategia di mascheramento dei dati sensibili
I trace di produzione possono contenere PII, secrets e dati dei clienti. Prima del lancio bisogna decidere cosa catturare e come mascherarlo. OpenAI Agents SDK offre la configurazione trace_include_sensitive_data, che controlla se registrare input e output completi di LLM e tool call.
Checklist:
- posizione e valore di default di
trace_include_sensitive_datasono chiari. - rilevamento e mascheramento delle PII coprono campi comuni come nome, e-mail e numero di telefono.
- l’isolamento dei secrets è in atto, così API key e password del database non appaiono in trace o log.
- i dati dei clienti sono classificati come pubblici, interni o riservati, con strategie di mascheramento diverse.
- i trace mascherati restano utili per il debugging.
In produzione conviene usare rilevamento automatico delle PII più mascheramento a livelli. Così si copre la compliance senza perdere capacità di debug.
1.3 Gate di monitoraggio dei Guardrails
I guardrails validano input utente e output dell’agent, e possono usare un modello più rapido o economico per bloccare richieste non conformi. Il tool input guardrail di OpenAI Agents SDK viene eseguito prima della chiamata a un function tool. Ma i guardrails non sono una difesa assoluta. Prima del release bisogna confermare che siano osservabili, alertabili e collegati al rollback.
Checklist:
- la baseline del tasso di blocco dell’input guardrail è stata misurata.
- sono noti i tassi di falsi positivi e falsi negativi dell’output guardrail.
- il tool input guardrail viene eseguito prima della chiamata allo strumento.
- le soglie di alert per guardrail trip sono configurate.
- esiste un percorso rapido di feedback per i falsi positivi.
Il gate dei guardrails è chiaro: il tasso di blocco ha una baseline, i falsi positivi hanno feedback, gli alert hanno soglie.
1.4 Osservabilità dei Tool Calls
Il fallimento di una chiamata a strumento è uno dei modi di errore più comuni negli Agent. L’interfaccia HTTP può restituire 200 anche se gli argomenti sono sbagliati, i permessi vengono superati o un servizio esterno va in timeout. Il monitoraggio normale del servizio non vede questi errori; si trovano nei trace.
Checklist:
- la baseline di successo/fallimento di ogni strumento è stata misurata.
- la distribuzione di latenza delle chiamate agli strumenti (P50/P95/P99) è nota.
- i confini di permesso sono chiari, con allowlist o denylist di quali strumenti possono accedere a quali risorse.
- i modi di fallimento sono classificati: timeout, permessi, errore di argomento, guasto di servizio esterno hanno strategie diverse.
- retry policy e soglie di circuit breaker sono configurate.
L’osservabilità degli strumenti richiede una baseline di successo per ogni strumento, fallimenti classificati e circuit breaker per i timeout.
1.5 Preparazione del monitoraggio della coda HITL
L’accumulo nella coda Human-in-the-Loop (HITL) è un rischio facile da perdere durante il canary. I checkpointer di LangGraph salvano il graph state a ogni super-step e supportano HITL, time travel e fault tolerance, ma lunghezza della coda e timeout di approvazione vanno monitorati a parte.
Checklist:
- le soglie di alert per la lunghezza della coda HITL sono configurate.
- la strategia automatica per timeout di approvazione è chiara, con regole per rifiutare, passare a un umano o degradare.
- il percorso di resume dopo un’interruzione è stato verificato.
- è definito come trattare le attività nella coda durante un cambio di versione.
Il monitoraggio della coda HITL richiede soglie sulla coda, strategia per i timeout e ripresa verificata dopo interruzione.
1.6 Eval Regression Suite
Prima del release bisogna eseguire una regression suite propria per evitare regressioni di capacità. La regression suite deve contenere attività reali, non solo synthetic examples. Se il tasso di superamento scende sotto la baseline, la nuova versione può avere problemi e non dovrebbe uscire.
Checklist:
- la regression suite contiene abbastanza attività reali.
- la baseline del tasso di superamento è esplicita (consigliato: ≥95%).
- i casi falliti sono classificati chiaramente.
- il tempo di esecuzione della suite è controllato (consigliato: ≤15 minuti).
- il meccanismo per reinserire nella suite i campioni falliti del canary è pronto.
La regression suite è l’ultimo gate. Se il tasso di superamento è sotto il 95%, conviene correggere prima del lancio.
1.7 Cost Budget e Rate Limit
I limiti di costo e rate a livello piattaforma sono l’ultima barriera. OpenAI consiglia usage tracking, billing limits, notification threshold e limiti spend/rate a livello di progetto. Non basta affidarsi ai controlli di budget nel codice business.
Checklist:
- il project-level spend limit è configurato.
- usage notification threshold è impostato (consigliato: 70%/90%).
- rate limit è segmentato per utente o tenant.
- alert di aumento improvviso dei costi sono configurati, per esempio con confronto orario.
- la strategia di degradazione è chiara: disattivare strumenti costosi, cambiare modello o limitare utenti quando si supera il budget.
Il Cost Budget richiede un tetto, alert con soglie e un percorso di degradazione in caso di superamento.
1.8 Isolamento dei Secrets e audit
La fuga di secrets è uno degli incidenti di sicurezza più gravi per un Agent. Un Agent può accedere a database, API di terze parti e servizi interni tramite strumenti. Ogni chiamata richiede audit. I campi actor/subject/tool/resource devono essere completi.
Checklist:
- actor/subject/tool/resource vengono registrati integralmente.
- lo storage dei secrets è isolato, così API key e password del database non appaiono in variabili d’ambiente o file di configurazione.
- la validazione dei secrets viene eseguita prima della chiamata allo strumento.
- il periodo di conservazione degli audit log è chiaro (consigliato: 1 anno).
- esiste un piano di rotazione delle chiavi.
Gli audit log sono una base importante per la revisione degli incidenti.
1.9 Validazione del recupero da Checkpoint
Un Agent di lunga durata deve poter recuperare lo stato corretto dopo un fallimento. I checkpointer di LangGraph salvano il graph state a ogni super-step e supportano time travel debugging e fault-tolerant execution, ma il percorso di recupero va testato separatamente.
Checklist:
- la frequenza di salvataggio dei checkpoint è chiara, a ogni super-step o a ogni nodo importante.
- il test di recupero dopo errore è stato eseguito.
- la correttezza dello stato dopo il recupero è stata verificata.
- la strategia di pulizia delle attività a metà è chiara.
Il recupero da checkpoint è una capacità di base per gli Agent di lunga durata.
1.10 Feature Flag e Kill Switch
Devi poter spegnere l’Agent senza un nuovo deploy. OpenFeature fornisce un modello standard di feature flag, con targeting per tenant, utente, tipo di attività e rollout percentuale.
Checklist:
- i feature flag sono segmentati per tenant, utente o tipo di attività.
- il kill switch ha effetto entro 1 minuto.
- il rollout percentuale è supportato e può essere usato per canary release.
- monitoraggio e audit dello stato dei flag sono configurati.
Il controllo Feature Flag richiede controllo segmentato, effetto rapido e audit dello stato.
2. Osservazione del canary: cosa guardare nei primi 10-30 minuti
Passare i gate pre-release non significa che il canary sarà pulito. Un canary di Agent richiede due livelli di metriche: metriche di servizio (tasso di errore HTTP, tempo di risposta) e metriche Agent (tool failure rate, guardrail trip rate, cost per run, HITL queue).
2.1 Percentuale di traffico e finestra di osservazione
Un canary non si gestisce a sensazione. Kubernetes e AWS consigliano di partire con poco traffico, impostare un periodo di valutazione sufficiente, monitorare le metriche e poi aumentare gradualmente. Percentuale di traffico e parametri temporali devono essere definiti.
Checklist:
- la percentuale iniziale di traffico è chiara (consigliato: 5-10%).
- la finestra minima di osservazione è impostata (consigliato: 10-30 minuti).
- il numero minimo di richieste nella finestra di osservazione è configurato.
- le condizioni per aumentare gradualmente il traffico sono definite.
Percentuale di traffico e finestra di osservazione sono i parametri di base del canary. Se il 5% del traffico attiva alert entro 10 minuti, la nuova versione ha un problema serio e va rollbackata subito.
2.2 Monitoraggio delle metriche di servizio
Tasso di errore HTTP, tempo di risposta e throughput sono il primo livello di metriche del canary, e valgono anche per i servizi normali. Ma se guardi solo questo livello, puoi perdere i modi di fallimento specifici degli Agent.
Checklist:
- la soglia per il tasso di errore HTTP 5xx è configurata (consigliato: ≤1%).
- la soglia P95 del tempo di risposta è chiara.
- la variazione del throughput rispetto alla baseline è monitorata.
- uso di CPU e memoria sono monitorati.
- il tasso di errori di rete è monitorato.
Le metriche di servizio sono la prima linea di difesa, ma non tutta la storia. Un Agent può restituire HTTP 200 mentre tool call falliscono, guardrail vengono aggirati o il costo aumenta di colpo.
2.3 Monitoraggio delle metriche Agent
Le metriche specifiche degli Agent sono il secondo livello del canary. Il monitoraggio normale dei servizi di solito non le copre. Questi segnali vivono nei trace, non negli HTTP log.
Checklist:
- tool failure rate è monitorato per strumento.
- guardrail trip rate è monitorato per tipo.
- cost per run è monitorato rispetto alla baseline precedente.
- la lunghezza della coda HITL è monitorata in tempo reale.
- eval drift è monitorato quando disponibile.
Le metriche Agent vanno raggruppate per strumento e per tipo, non nascoste in una media.
2.4 Condizioni di alert e rollback automatico
Un canary deve poter fare rollback automatico. Non può dipendere solo da qualcuno che guarda il dashboard. La documentazione AWS consiglia di usare CloudWatch alarms per attivare rollback automatico, con condizioni e percorsi di rollback espliciti.
Checklist:
- le condizioni di attivazione del rollback automatico sono definite.
- il percorso di cambio traffico dopo il rollback è chiaro.
- la finestra di osservazione post-rollback è impostata.
- conferma umana e flusso di escalation sono definiti.
Il rollback automatico richiede trigger chiari, percorso di rollback chiaro e conferma umana quando serve.
3. Monitoraggio post-release: la produzione non finisce al lancio
Un canary superato non equivale a production readiness. Dopo il release bisogna continuare a monitorare qualità dei trace, uso dei costi, effetto dei guardrails ed eval regression, per evitare degrado di capacità o esplosione dei costi.
3.1 Monitoraggio della qualità del Trace
Dopo il release i trace possono perdersi, arrivare in ritardo o avere campi mancanti. Questo riduce la capacità di analizzare incidenti e fare debugging. Il monitoraggio della qualità dei trace deve essere indipendente dalle metriche di servizio.
Checklist:
- la completezza dei trace è monitorata, e una correlazione run ID sotto la baseline genera alert.
- la latenza dei trace è monitorata, e un tempo eccessivo prima che siano interrogabili genera alert.
- il trace sampling rate è configurato, con downsampling ad alto traffico per ridurre i costi di storage.
- il trace storage cost è monitorato.
La qualità dei trace richiede baseline di completezza, soglia di latenza e budget di costo.
3.2 Monitoraggio continuo di Cost e Usage
L’aumento improvviso dei costi è uno degli incidenti di produzione più comuni negli Agent. Uso anomalo di token, abuso del modello e crescita improvvisa della frequenza dei tool call possono far esplodere il costo. OpenAI consiglia usage tracking e notification threshold.
Checklist:
- i trend giornalieri di cost sono monitorati, con confronto giorno su giorno e settimana su settimana.
- l’uso dei token è monitorato per modello e per utente.
- gli strumenti ad alto costo sono identificati.
- la velocità di consumo del budget è monitorata.
- il circuit breaker automatico per superamento del budget è configurato.
Il monitoraggio dei costi richiede confronti di trend, classificazione per modello e circuit breaker di budget.
3.3 Monitoraggio continuo dei Guardrails
Variazioni nel tasso di blocco dei guardrail possono indicare attacchi o falsi positivi. Un aumento dell’input guardrail può significare più prompt malevoli. Un aumento del false positive rate dell’output guardrail può indicare regole troppo rigide.
Checklist:
- il trend del tasso di blocco dell’input guardrail è monitorato.
- il false positive rate dell’output guardrail è monitorato.
- la raccolta feedback per guardrail false positive/negative è completa.
- le regole dei guardrails sono valutate periodicamente.
Il monitoraggio dei guardrails richiede trend di blocco, feedback sui falsi positivi e regole aggiornate.
3.4 Eval regression continua
Dopo il release bisogna continuare a verificare che la capacità non degradi. Esegui la regression suite ogni giorno o ogni settimana, genera alert sui casi falliti e aggiungi i nuovi fallimenti alla suite.
Checklist:
- le esecuzioni giornaliere o settimanali della regression suite sono automatizzate.
- i casi falliti generano alert automaticamente.
- i nuovi casi falliti vengono aggiunti alla suite.
- la gestione delle versioni della regression suite è curata.
Eval regression significa esecuzione periodica, alert sui fallimenti e reinserimento dei casi.
4. Rollback degli incidenti: la parte difficile sono gli effetti collaterali degli strumenti
Il rollback di un Agent è più complesso del rollback di un servizio normale. Per un servizio normale spesso basta tornare alla versione del codice. Un Agent deve gestire anche effetti collaterali di strumenti già eseguiti, workflow a metà e attività nelle code di approvazione umana.
4.1 Rollback del codice
Il rollback del codice è il percorso più semplice. Kubernetes Deployment supporta rolling update e rollback, ma la finestra di rollback dovrebbe restare entro 5 minuti.
Checklist:
- il percorso di rollback della versione del codice è chiaro.
- il cambio traffico dopo il rollback è stato verificato.
- la validazione post-rollback, come uno smoke test, viene eseguita.
- la finestra di rollback è impostata (consigliato: ≤5 minuti).
Il rollback del codice richiede percorso chiaro, cambio verificato e finestra limitata.
4.2 Rollback degli effetti collaterali degli strumenti
La parte più difficile del rollback di un Agent sono gli effetti collaterali degli strumenti già eseguiti. Inviare e-mail, creare ordini, chiamare API esterne: nulla di questo viene annullato perché il codice torna indietro. Bisogna distinguere operazioni idempotenti e non idempotenti e progettare azioni di compensazione.
Checklist:
- le operazioni degli strumenti già eseguite sono identificate, e tutti i tool call eseguiti si trovano nei trace.
- le operazioni idempotenti possono essere ripetute in sicurezza.
- le operazioni non idempotenti hanno azioni di compensazione, come inviare una mail correttiva, annullare un ordine o chiamare una reversal API.
- la strategia di pulizia delle attività a metà è chiara.
- il processo di fallback umano è definito.
Il rollback degli effetti collaterali richiede identificare le operazioni eseguite, valutare l’idempotenza e progettare compensazioni.
4.3 Pulizia della coda HITL
Durante il rollback, la coda di approvazione umana può contenere attività a metà. La nuova versione dell’Agent può aver promosso attività a HITL, mentre la vecchia versione potrebbe non richiedere approvazione umana. Le attività in coda devono essere riassegnate o riportate indietro.
Checklist:
- le attività in coda sono identificate per etichetta di versione.
- la strategia di riassegnazione delle attività è chiara.
- il trattamento dei timeout di approvazione è definito.
- il flusso di conferma umana è completo.
La pulizia della coda HITL richiede identificazione per versione, strategia di riassegnazione e gestione dei timeout.
4.4 Conservazione di Trace e Audit log
La revisione post-incidente richiede trace e audit log completi. OpenTelemetry tratta i logs come uno dei telemetry signals e può integrarli con logging frameworks esistenti.
Checklist:
- il periodo di conservazione dei trace è chiaro (consigliato: 30-90 giorni).
- il periodo di conservazione degli audit log è chiaro (consigliato: 1 anno).
- le regole di mascheramento dei dati sensibili sono complete.
- i requisiti di compliance del settore sono rispettati.
La conservazione di Trace e Audit richiede durate adeguate, regole di mascheramento complete e copertura compliance.
4.5 Reinserire i campioni falliti nella Eval Suite
Dopo un incidente, i campioni falliti devono entrare nella regression suite per evitare che lo stesso problema si ripeta. L’estrazione deve trovare i failed case nei trace, e una persona deve etichettare motivo del fallimento e comportamento atteso.
Checklist:
- esiste uno strumento o script per estrarre campioni falliti.
- l’etichettatura dei campioni ha conferma umana.
- esiste un processo per aggiungere campioni alla regression suite.
- esiste un meccanismo per evitare che lo stesso tipo di incidente si ripeta.
Reinserire i fallimenti nella suite richiede estrazione, etichettatura umana, processo di aggiornamento della suite e fix verificati.
Conclusione
Il lancio di un Agent richiede otto dimensioni in più rispetto a un servizio web normale: trace, tool calls, guardrails, HITL, eval, cost, secrets, checkpoint. Queste otto dimensioni si raccolgono in quattro gruppi di checklist:
Gate pre-release (10 controlli): completezza del Trace, mascheramento dei dati sensibili, monitoraggio dei Guardrails, osservabilità dei Tool Calls, preparazione della coda HITL, Eval Regression Suite, Cost Budget e Rate Limit, isolamento dei Secrets e audit, validazione del recupero da Checkpoint, Feature Flag e Kill Switch. Controllali uno per uno prima del release. Ciò che non passa deve bloccare il lancio.
Osservazione del canary (4 controlli): percentuale di traffico e finestra di osservazione, monitoraggio delle metriche di servizio, monitoraggio delle metriche Agent, condizioni di alert e rollback automatico. Un canary non guarda solo il tasso di errore HTTP: segue anche tool failure rate, guardrail trip rate, cost per run e HITL queue length.
Monitoraggio post-release (4 controlli): qualità del Trace, monitoraggio continuo di Cost e Usage, monitoraggio continuo dei Guardrails, eval regression continua. Un canary pulito non basta; il monitoraggio continuo evita degrado di capacità e aumenti improvvisi dei costi.
Rollback degli incidenti (5 controlli): rollback del codice, rollback degli effetti collaterali degli strumenti, pulizia della coda HITL, conservazione di Trace e Audit log, reinserimento dei campioni falliti nella Eval Suite. Il rollback non è solo tornare a una versione del codice. Include anche effetti collaterali già eseguiti, workflow a metà e code di approvazione umana.
Salva questi quattro gruppi di checklist come template e percorri tutto prima di ogni release. Se un controllo fallisce, correggilo prima di andare in produzione, invece di portare un problema noto dentro il canary.
Eseguire un controllo di produzione prima di lanciare un Agent
Prima di spostare un Agent dal demo agli utenti reali, verifica osservabilità, gate di release, controlli di costo, sicurezza e percorsi di rollback prima del release, durante il canary, dopo il release e negli incidenti.
- 1
Step 1: Correlare gli identificatori di esecuzione
Conferma che runId, traceId, spanId, toolCallId, userId/tenantId e workflowVersion possano essere correlati tra log, trace e alert. - 2
Step 2: Controllare la policy sui dati sensibili
Conferma che prompt, argomenti degli strumenti, ritorni degli strumenti, secrets e PII siano mascherati, con tempi di conservazione e controlli di accesso. - 3
Step 3: Eseguire le valutazioni di regressione
Esegui la eval regression suite più recente, coprendo risposte finali, scelta degli strumenti, argomenti, transizioni di stato, permessi, costo e recupero dagli errori. - 4
Step 4: Validare i percorsi di errore
Valida i percorsi di errore di guardrails, HITL, permessi, secret vault, cost budget, rate limit e retry budget. - 5
Step 5: Preparare gli interruttori di rollout
Prepara feature flag, kill switch, per-tenant enablement, canary percentage, observation window e rollback conditions. - 6
Step 6: Monitorare le metriche del canary
Durante il canary, monitora insieme metriche normali di servizio e metriche dell'Agent: tool failure, guardrail trip, cost per run, approval queue e checkpoint resume. - 7
Step 7: Confermare l'operatività post-release
Dopo il release, conferma alert, on-call, runbook, template di postmortem e processo per reinserire i trace falliti nelle eval. - 8
Step 8: Bloccare prima l'incidente
In caso di incidente, spegni prima il flag o fai rollback della versione; poi gestisci attività a metà, effetti collaterali esterni e regression case.
FAQ
Cosa devo controllare prima di lanciare un Agent se il demo funziona già?
In cosa il lancio di un Agent è diverso dal lancio di un normale servizio web?
Quali metriche seguire durante una canary release di un Agent?
Posso salvare prompt completi e argomenti degli strumenti nei trace?
Fare rollback di un Agent significa solo tornare a una vecchia versione del codice?
I guardrails possono sostituire l'approvazione umana o un modello di permessi?
16 min di lettura · Pubblicato il: 21 ott 2026
Guida all'ingegneria degli AI Agent
Se arrivi dalla ricerca, il modo più veloce per orientarti è passare all’articolo precedente o successivo della stessa serie.
Precedente
Come creare un dataset di valutazione per Agent: task reali, traiettorie e test di regressione
Non basta eseguire benchmark pubblici. Questa guida mostra come trasformare task reali degli Agent, trace, tool calls, eventi di stato, feedback umano e casi di errore in un eval dataset per test di regressione e release gate.
Parte 7 di 8
Successivo
Questo è l’articolo più recente della serie per ora.
Commenti
Accedi con GitHub per lasciare un commento