Debugging degli agenti AI: la tua dashboard conosce il costo, non la causa.

Il debugging degli agenti AI inizia dove finisce la tua dashboard di osservabilità. Quando un agente AI di codifica rompe qualcosa e l'esecuzione è già terminata, la dashboard può dirti quanto è costata l'esecuzione (token, dollari, latenza), ma rimane in silenzio sull'unica domanda che hai davvero: perché l'agente ha modificato quel file? L'artefatto che risponde a questa domanda è una traccia registrata che puoi aprire, leggere e riprodurre, perché ti restituisce l'esecuzione invece di descriverla dall'esterno.

Questo ha smesso di essere un evento raro nel momento in cui gli agenti hanno iniziato a fare un lavoro vero. Un agente esaminerà un repository, modificherà diversi file, eseguirà i controlli e riporterà il successo, tutto tra due prompt che hai digitato a distanza di minuti. Se una di quelle modifiche è sbagliata, lo scopri dopo: dopo che il terminale è stato chiuso, dopo che lo scrollback è sparito, dopo che il processo che avrebbe potuto spiegarsi è uscito. Ciò che accade dopo dipende interamente da ciò che hai conservato. Se la risposta è un dashboard dei costi, ti appresti a fare archeologia. Se la risposta è una registrazione, ti appresti a fare lettura.

L'errore che non riesci a riprodurre

Ecco com'è fatta la cosa. Torni al repository e un file che non hai mai chiesto a nessuno di toccare è stato riscritto, o cancellato, o svuotato della funzione da cui dipende tutto il resto. Chiedi all'agente cosa sia successo; la sessione è chiusa, e anche quando sopravvive una trascrizione, il resoconto dell'agente sulla propria esecuzione è una ricostruzione, non una registrazione. Quindi fai la cosa naturale e lo riesegui, e ottieni un'esecuzione diversa. Chiamate a strumenti diverse, modifiche diverse, e forse nessun errore affatto, perché la traiettoria originale dipendeva dal campionamento, dallo stato del repository, dai tempi. L'esecuzione che devi ispezionare non esiste più.

È peggiore della non riproducibilità. È non riproducibile e contrassegnato come successo. Un'esecuzione esce con codice 0 quando l'agente esce con codice 0, anche se un controllo all'interno dell'esecuzione è uscito con codice 1: la pipeline può essere verde mentre una fase di verifica all'interno dell'esecuzione è fallita, e il codice di uscita a cui ti affideresti naturalmente non ti dice nulla.

Non importa quale modello il router abbia scelto per l'esecuzione (GLM 5.3 Flash o qualsiasi altro): una volta che il processo termina, il ragionamento svanisce con esso. Le prove esistevano solo mentre l'esecuzione era attiva: i prompt, le chiamate agli strumenti, gli output, i diff. Se nulla li ha registrati, "perché ha modificato quel file" non ha risposta. Ha solo teorie.

Questa è la modalità di guasto che separa agenti di codifica AI da ogni strumento che li ha preceduti: il danno e la spiegazione avvengono nello stesso luogo, e il luogo si chiude.

Cosa misura una dashboard e cosa tralascia?

L'istinto dopo una brutta esecuzione è quello di aprire la dashboard di osservabilità, e la dashboard sarà davvero brava nel suo lavoro. Il suo lavoro è il traffico: token al giorno, costo per modello, latenza, tassi di errore. Per la pianificazione della capacità e la fatturazione è esattamente lo strumento giusto, e se esegui agenti in produzione dovresti tenerla aperta.

Ma la tua domanda non è di tipo aggregato. È singolare e causale: perché questa esecuzione ha modificato questo file? L'aggregazione scavalca proprio il livello di granularità che fornisce la risposta. Se si fa una media tra le esecuzioni, l'esecuzione che ti interessa è rumore; all'interno di quell'esecuzione, la chiamata allo strumento che ti interessa è di nuovo rumore.

Una dashboard descrive un run dall'esterno: che è accaduto, quanto pesava, quanto costava. Non può consegnarti il run, e il "perché" non è una proprietà della descrizione. È una proprietà della sequenza.

Quanto è costata l'esecuzione? — Il dashboard dei costi risponde vs La traccia registrata risponde

• Perché l'agente ha modificato quel file? — Dashboard dei costi Nessuna risposta vs Traccia registrata La modifica, in sequenza, con il suo diff

• Quale check è fallito all'interno di un run verde? — Dashboard dei costi: nessuna risposta vs traccia registrata. Il check, con il suo codice di uscita.

• Posso riprodurre esattamente lo stesso errore? — Cost dashboard No vs Recorded trace Sì, offline, senza costi

Il livello che risponde a questa domanda si trova al di sotto: log di richieste registrati, catturati mentre l’esecuzione avveniva, con ogni prompt inviato, ogni chiamata di strumento effettuata, ogni risposta ricevuta, in ordine. Non un riepilogo dell’esecuzione. L’esecuzione stessa.

Leggere una singola esecuzione come una timeline

Con una registrazione, il debugging smette di essere archeologia e diventa lettura. L'archeologia è ciò che fai senza: git reflog, voci di stash, cronologia della shell, il tuo stesso ricordo di ciò che avevi chiesto prima quel giorno. La lettura è ciò che fai con una: apri la timeline e scorri.

La timeline presenta l'esecuzione nell'ordine in cui è avvenuta: il prompt che l'ha avviata, ogni chiamata di strumento, ogni modifica di file con il suo diff, ogni controllo, ogni codice di uscita. Uno snapshot del filesystem viene acquisito una volta per turno anziché una volta per chiamata di strumento, il che è sufficiente per vedere lo stato del repository in ogni passo della conversazione senza essere sommersi dal rumore di ogni singola chiamata. Ciò che rende questa attività debugging e non semplice navigazione è l'adiacenza: la modifica e il controllo che l'ha rilevata si trovano uno accanto all'altro, in ordine, senza nulla in mezzo da dover ipotizzare. Il "perché" è principalmente una proprietà dell'adiacenza.

Un esempio concreto, letto da un fix registrato: 14 eventi, tra cui la modifica del file stampata come +1 -3 e un controllo fallito con exit 1. La modifica e, subito dopo, il controllo che è fallito a causa sua: adiacenti nella registrazione. È tutta qui la differenza tra ricostruire un'esecuzione a partire da frammenti e leggerne una. Conta soprattutto per gli agenti di codifica da terminale, il cui spazio di lavoro è un terminale che si chiude nell'istante in cui il lavoro finisce: la timeline è lo scrollback che sopravvive.

Registrato o dedotto: ciò che la traccia sa versus ciò che ha dedotto

Una timeline ti dice cosa è successo in ordine. Il grafico causale ti dice cosa ha portato a cosa, e il divario tra questi due è dove la fiducia deve essere guadagnata.

Il grafico collega gli eventi: questa modifica, poi questo controllo fallito. Alcuni di quei collegamenti sono fatti registrati: la chiamata allo strumento che ha prodotto il diff è proprio lì nella traccia. Altri sono inferiti: la conclusione del grafico che il controllo sia fallito a causa di quel diff. orca graph etichetta ogni collegamento come registrato o inferito e indica la regola usata in entrambi i casi, così sai sempre se stai guardando qualcosa che l'esecuzione ha fatto o qualcosa che lo strumento ha dedotto riguardo all'esecuzione.

Questa distinzione è imposta, non è solo un'aspirazione: gli archi inferiti non vengono mai riscritti nella traccia. La traccia rimane una registrazione fedele di ciò che è accaduto; l'inferenza è una vista sovrapposta ad essa, che puoi ispezionare, mettere in discussione e contestare. Questo è particolarmente importante quando sono coinvolti più agenti. Quando un agente di refactoring e un agente che scrive test intervengono sugli stessi file, "quale agente ha causato questo" è esattamente la domanda a cui l'attribuzione multi-agente esiste per rispondere. Un arco che viene silenziosamente promosso da inferenza a fatto è il modo in cui finisci per fare debug di una storia invece che di un'esecuzione.

Riprodurlo tutte le volte che vuoi, gratuitamente.

Leggere spiega. Rieseguire dimostra. Una volta che hai un'ipotesi (il controllo è fallito perché la modifica ha rimosso la chiamata di reset), vuoi eseguirlo di nuovo e osservarlo accadere. Rieseguire l'agente live ti fa ottenere una nuova traiettoria e una nuova fattura.

Ripetere la registrazione ti garantisce la stessa esecuzione: le esecuzioni di replay avvengono con la rete bloccata, quindi non costano token e non hanno varianza. Stessi eventi, ogni volta, offline. È questa la proprietà che trasforma il debugging degli agenti da gioco d'azzardo a ingegneria: il guasto è diventato deterministico, e i guasti deterministici vengono corretti.

Nemmeno lo strumento è una scatola nera. OrcaReplay è open source con licenza Apache-2.0 e il formato delle tracce è CC BY 4.0, quindi chiunque può reimplementarlo: le tue registrazioni non sono in ostaggio di un formato proprietario, e nemmeno le nostre. Ed è collaudato, non una demo: 1.393 test su Node 20 e Node 22. Puoi leggere il codice sorgente, controllare il formato ed eseguire la suite tu stesso, prima di affidargli le esecuzioni del tuo team.

Il punto chiave

Un dashboard è una fattura. Una traccia registrata è l'esecuzione. Se il tuo piano per il debug degli agenti AI termina con un dashboard dei costi, non hai un piano di debug: hai un sistema di fatturazione. Il dashboard sarà sempre in grado di dirti quanto è costata un'esecuzione, e non sarà mai in grado di dirti perché l'agente ha eliminato il tuo file, perché il "perché" vive nella sequenza, e la sequenza esiste solo se l'hai conservata.

L'intero metodo consiste in quattro passaggi:

• Registra le corse.

• Leggi la cronologia.

Controlla gli spigoli del grafico.

• Rigioca quelli che ti spaventano, gratis, quante volte vuoi.

Nota sulle fonti: Ogni dato in questo articolo è fornito dal vendor, sia dal nostro prodotto sia dal repository OrcaReplay e dalla sua documentazione: il comportamento del codice di uscita di un'esecuzione, il fix registrato di 14 eventi con il suo diff +1 -3 e il suo controllo di exit-1, l'etichettatura degli archi nel grafo orca, la cadenza di snapshot una volta per turno, il replay offline con la rete bloccata e la suite di 1393 test su Node 20 e Node 22. Nessuna misurazione di terze parti è citata in questo articolo. La suite di 1393 test è l'unica affermazione che puoi verificare tu stesso, clonando il repository ed eseguendola. Tutti gli elementi sono stati controllati l'ultima volta il 4 settembre 2026.