Come Debuggare un Agente IA in Produzione (Guida sul Campo)

Indice dei contenuti

Aggiornato giugno 2026.

TL;DR: Debuggare un agente IA in produzione consiste soprattutto nell’isolare quale livello ha fallito — prompt, chiamata a strumento, output del modello o orchestrazione. Registro ogni passo con un ID di traccia, riproduco gli input esatti e biseco da lì. Nei miei agenti, circa il 70% di ciò che sembra un “bug dell’IA” si rivela idraulica: un risultato di strumento malformato, un input troncato, un’eccezione silenziosamente ingoiata.

Lettura dell’operatore: Gestisco oltre 100 agenti in produzione — flussi di prenotazione per Pickleland, pipeline di contenuti, smistatori di posta in arrivo. Si rompono come si rompe ogni software, più qualche modo nuovo. Questa è la guida sul campo che avrei voluto avere: come trovare il livello che fallisce senza fissare un muro di token.

Quando un agente si comporta male in produzione, l’istinto è incolpare il modello. “Claude ha allucinato.” A volte è vero. Di solito no. Il modello è un livello in uno stack di cinque o sei, e il bug è molto più spesso nel livello che hai scritto tu che in quello spedito da Anthropic. Questo articolo è il modo sistematico con cui lo trovo.

Rendi ogni esecuzione tracciabile prima di debuggare qualsiasi cosa

Non puoi debuggare ciò che non puoi vedere. La cosa a più alto rendimento che puoi fare — prima che spunti qualsiasi bug specifico — è agganciare un ID di traccia a ogni esecuzione dell’agente e registrare ogni passo che compie.

Un “passo” è qualsiasi cosa che attraversa un confine: il trigger in entrata, ogni chiamata al modello (con l’array completo dei messaggi), ogni chiamata a strumento (con gli argomenti), ogni risultato di strumento e l’output finale. Registrali come JSON strutturato indicizzato dall’ID di traccia.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

Su Cloudflare Workers li invio a una coda e in una tabella; in locale vanno su stdout. La regola è assoluta: se un passo non è registrato, non è avvenuto per quanto riguarda il debug. Questo rispecchia la strumentazione che descrivo ne lo stack di agenti che uso — l’ID di traccia è la spina dorsale a cui è appeso tutto il resto.

Isola il livello: prompt, strumento, modello o orchestrazione

Una volta che hai una traccia, il debug diventa una bisezione. Ci sono quattro livelli e il bug vive in esattamente uno di essi la maggior parte delle volte.

1. Il livello di input (il colpevole più comune)

Estrai l’esatto array messages che è entrato nella chiamata al modello fallita. Non una ricostruzione — il payload letterale dal log. Poi leggilo come farebbe un estraneo. Metà dei miei bug “il modello ha ignorato le istruzioni” sono in realtà:

• Un risultato di strumento tornato come "[object Object]" perché qualcosa è stato convertito male in stringa.
• Un input troncato a metà frase perché ha fatto esplodere la finestra di contesto e uno slice ingenuo l’ha tagliato.
• Una variabile interpolata come undefined che ha avvelenato silenziosamente il prompt.

Se l’input è sbagliato, il modello ha fatto il suo lavoro alla perfezione su spazzatura. Aggiusta l’idraulica.

2. Il livello degli strumenti

Se l’input sembra pulito, controlla se uno strumento ha restituito un errore che l’agente ha trattato come successo. Un classico: un’API restituisce 200 con un corpo { "error": "rate limited" }, il tuo wrapper dello strumento non controlla il corpo, e l’agente agisce con sicurezza su un messaggio di errore. Registra i risultati degli strumenti grezzi e verifica la loro forma.

3. Il livello del modello

Solo dopo aver escluso 1 e 2 sospetto del modello. Anche allora, “bug del modello” di solito significa “il mio prompt è ambiguo.” Prendi l’input esatto fallito, mettilo in uno script estemporaneo contro lo stesso modello e temperatura, e vedi se si riproduce. Se sì, la soluzione è lavoro sul prompt o una eval più stringente, non un cambio frenetico di modello.

4. Il livello di orchestrazione

Se un singolo passo è a posto in isolamento ma l’esecuzione multi-passo fallisce, il bug è nel passaggio di consegne — stato perso tra i passi, una race condition, un retry che ha rieseguito un’azione non idempotente. Questi sono i più insidiosi e copro i pattern in pattern di orchestrazione multi-agente.

Riproduci il non-determinismo invece di combatterlo

Ciò che fa sembrare gli agenti impossibili da debuggare è il non-determinismo: lo stesso input produce output diversi tra le esecuzioni. Puoi domarlo.

Primo, fissa ciò che puoi. Imposta temperature: 0 durante il debug. Non renderà Claude completamente deterministico, ma restringe nettamente la varianza così puoi distinguere un bug reale dal rumore di campionamento.

Secondo, eseguilo N volte. Se un fallimento si riproduce 1 volta su 20, ripeti l’input esatto 50 volte e cattura ogni output. Ora hai un campione, non un aneddoto. Un bug che scatta il 5% delle volte è un bug reale — ti serve solo volume per vederlo.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# poi conta i fallimenti
grep -c '"status":"fail"' runs.jsonl

Terzo, confronta le esecuzioni che passano e quelle che falliscono. Con la temperatura fissata e lo stesso input, una differenza nell’output significa una differenza nell’input che non hai ancora individuato — un timestamp nel prompt, un risultato di strumento che varia, un documento recuperato che è cambiato.

Costruisci un harness di replay per smettere di debuggare in produzione

Debuggare ri-attivando l’agente dal vivo è lento e rischioso — invia email reali, prenota campi reali. Invece, cattura la traccia e riproducila offline.

L’harness di replay carica una traccia registrata, ricostruisce gli input esatti di qualsiasi passo e riesegue solo quel passo contro il modello. Poiché hai registrato l’array completo messages, non hai affatto bisogno del sistema a monte. Questo trasforma un viaggio di andata e ritorno di 10 minuti in produzione in un ciclo locale di 2 secondi, ed è la più grande accelerazione nel mio flusso di debug.

Un buon harness di replay ti permette anche di mutare e rieseguire: cambia una riga del prompt di sistema, riproduci le stesse 50 tracce fallite e vedi quante passano ora. Questo è il ponte dal debug all’eval — una volta che hai un corpus di tracce fallite, hai l’inizio di una suite di regressione.

Tieni d’occhio le metriche che davvero predicono le rotture

Alcuni fallimenti non lanciano mai un’eccezione. L’agente gira, restituisce qualcosa di plausibile e fa silenziosamente la cosa sbagliata. Per catturare quelli osservi metriche comportamentali, non solo tassi di errore:

• Tasso di successo delle chiamate a strumento per strumento. Un calo qui spesso precede un fallimento visibile.
• Validità dello schema di output — quale % di output fa il parsing rispetto alla struttura attesa. Valido ogni output con Zod e allerto quando la validità cala.
• Lunghezza del ciclo — numero medio di passi per esecuzione. Un picco improvviso di solito significa che l’agente è bloccato a riprovare.
• Costo per esecuzione — un ciclo fuori controllo si mostra come un picco di costo prima di mostrarsi come un reclamo. (Quando il costo conta, vale la pena conoscere la matematica Haiku vs Sonnet.)

Traccio queste come traccio tutto il resto — vedi come misuro se un agente IA funziona davvero. La metrica che cattura un fallimento silenzioso vale dieci che catturano quelli rumorosi.

La checklist di triage di 5 minuti

Quando un agente si rompe e sono contro il tempo, eseguo questo in ordine:

1. Ottieni l’ID di traccia dell’esecuzione fallita.
2. Leggi l’input esatto del passo fallito. È ben formato? (Risolve ~50% dei casi qui.)
3. Controlla i risultati degli strumenti in quella traccia per errori camuffati da successo.
4. Riproduci il passo offline a temperature: 0. Si riproduce?
5. Se si riproduce, è un problema di prompt/modello — aggiusta e riesegui il corpus di tracce. Se no, è non-determinismo o un bug di stato/orchestrazione — ripetilo 50× per caratterizzarlo.

L’isolamento disciplinato batte il prompting astuto ogni volta. Il modello è raramente il problema; il sistema attorno ad esso di solito lo è.

FAQ

Come debuggo un agente IA che fallisce solo a volte?

Cattura l’input esatto da una traccia registrata e riproducilo oltre 50 volte a temperatura 0. I fallimenti intermittenti sono bug reali con bassi tassi di attivazione — il volume trasforma l’aneddoto in un campione riproducibile che puoi confrontare e correggere.

Il bug è di solito nel modello o nel mio codice?

Nei miei agenti di produzione, circa il 70% degli apparenti “bug dell’IA” è idraulica: risultati di strumento malformati, input troncati, eccezioni ingoiate o stato perso tra i passi. Escludi i livelli di input e strumento prima di sospettare del modello.

Qual è il minimo di logging che mi serve per debuggare gli agenti?

Un ID di traccia su ogni esecuzione, più log strutturati del trigger, ogni chiamata al modello (array completo dei messaggi), ogni chiamata a strumento e il suo risultato grezzo, e l’output finale. Se un passo non è registrato, non puoi debuggarlo.

Come smetto di debuggare contro la produzione dal vivo?

Costruisci un harness di replay che carichi una traccia registrata e riesegua qualsiasi singolo passo offline usando gli input catturati. Trasforma un viaggio di andata e ritorno lento e rischioso in produzione in un veloce ciclo locale e diventa il seme della tua suite di regressione.