{"id":2209,"date":"2026-05-20T09:20:43","date_gmt":"2026-05-20T07:20:43","guid":{"rendered":"https:\/\/userbot.ai\/blog\/?p=2209"},"modified":"2026-05-20T09:20:47","modified_gmt":"2026-05-20T07:20:47","slug":"osservabilita-e-debug-degli-agenti-ai","status":"publish","type":"post","link":"https:\/\/userbot.ai\/blog\/osservabilita-e-debug-degli-agenti-ai\/","title":{"rendered":"Osservabilit\u00e0 e debug degli Agenti AI: come funziona in pratica"},"content":{"rendered":"\n

Quando un agente AI fa qualcosa di sbagliato, risponde male o non esegue un’azione che dovrebbe eseguire, qual \u00e8 la prima cosa che fai?<\/p>\n\n\n\n

Se la risposta \u00e8 “rileggo il prompt e sperimento”, sei in buona compagnia. Ma sei anche in un posto che, a lungo andare, non scala.<\/p>\n\n\n\n

Il problema non \u00e8 la risposta sbagliata in s\u00e9. Il problema \u00e8 che non sai perch\u00e9 \u00e8 successa. E se non sai perch\u00e9 \u00e8 successa, non puoi correggere in modo affidabile: puoi solo sperare che la prossima versione funzioni meglio. Questo va bene per un prototipo. Non va bene per un sistema in produzione.<\/p>\n\n\n\n

L’osservabilit\u00e0 e il debug degli agenti AI<\/strong> sono esattamente la risposta a questo problema: la capacit\u00e0 di aprire quella scatola nera e leggere quello che c’\u00e8 dentro. In questo articolo vediamo perch\u00e9 \u00e8 pi\u00f9 difficile di quanto sembri, quali sono i livelli del problema, e come Userbot 3.0 li affronta in modo concreto con strumenti pensati per sviluppatori, team operations e auditor.<\/p>\n\n\n\n

\n\n\n\n

Perch\u00e9 il debug degli agenti AI non funziona come il debug tradizionale<\/strong><\/h2>\n\n\n\n

Con i vecchi chatbot a flusso fisso la vita era pi\u00f9 semplice, almeno su questo fronte. L’utente diceva X, il bot seguiva il ramo Y, qualcosa andava storto nel ramo Y. Trovavi il ramo, correggevi il testo, fine. La logica era tutta l\u00ec, visibile, percorribile passo dopo passo.<\/p>\n\n\n\n

Gli agenti AI funzionano in modo fondamentalmente diverso. Non seguono un percorso predefinito: prendono decisioni<\/strong>. Valutano il contesto della conversazione, scelgono quale tool<\/a> chiamare, stabiliscono se hanno abbastanza informazioni per rispondere o se devono raccoglierne altre, decidono quando passare la mano a un operatore umano. Ogni interazione \u00e8 il risultato di una catena di ragionamenti che, nella maggior parte dei sistemi, rimane completamente invisibile.<\/p>\n\n\n\n

Quello che vedi dall’esterno \u00e8 solo l’inizio e la fine: l’input dell’utente e l’output dell’agente. Tutto ci\u00f2 che \u00e8 successo nel mezzo (quale routing \u00e8 stato scelto, quali fonti sono state consultate, quali tool sono stati invocati, quali variabili erano disponibili in quel momento) rimane opaco. \u00c8 quella che si chiama “black box” dell’AI, e finch\u00e9 resta tale il debug degli agenti AI<\/strong> \u00e8 impossibile da fare in modo sistematico. Si va avanti per tentativi, il che non \u00e8 un metodo: \u00e8 una speranza.<\/p>\n\n\n\n

Cos’\u00e8 l’osservabilit\u00e0 degli agenti AI, e perch\u00e9 \u00e8 pi\u00f9 difficile di quanto sembri<\/strong><\/h2>\n\n\n\n

Nel software tradizionale, l’osservabilit\u00e0 \u00e8 un concetto consolidato: \u00e8 la capacit\u00e0 di capire lo stato interno di un sistema a partire dai suoi output, attraverso metriche, log e trace. \u00c8 una disciplina matura, con strumenti maturi.<\/p>\n\n\n\n

Nei sistemi agentici il concetto di partenza \u00e8 lo stesso, ma la natura del problema \u00e8 diversa. Non stai tracciando l’esecuzione di codice deterministico, dove lo stesso input produce sempre lo stesso output. Stai tracciando il ragionamento di un sistema probabilistico<\/strong>, che pu\u00f2 prendere strade diverse a seconda di come \u00e8 formulata la domanda, di quale versione del modello \u00e8 in uso, di quali informazioni erano disponibili nel knowledge base in quel momento.<\/p>\n\n\n\n

Questo rende l’osservabilit\u00e0 degli agenti AI<\/strong> sia pi\u00f9 difficile che pi\u00f9 necessaria rispetto al software classico. Pi\u00f9 difficile perch\u00e9 non basta loggare “l’agente ha risposto Y a X”: devi documentare perch\u00e9 ha risposto Y, quale percorso ha selezionato, su quali fonti si \u00e8 basato, quali tool ha chiamato con quali parametri, e come tutto questo ha influenzato il risultato finale. Pi\u00f9 necessaria perch\u00e9 senza questa visibilit\u00e0 qualsiasi ottimizzazione \u00e8 un’operazione nel buio: puoi modificare il prompt e vedere che le cose “sembrano andare meglio”, senza poter sapere se hai risolto il problema o se lo stai solo spostando altrove.<\/p>\n\n\n\n

I tre livelli del problema<\/strong><\/h2>\n\n\n\n

Quando si parla di monitoraggio degli agenti AI<\/strong>, vale la pena distinguere tre livelli diversi, perch\u00e9 richiedono risposte diverse.<\/p>\n\n\n\n

Il primo \u00e8 il livello della conversazione<\/strong>: cosa ha detto l’utente, cosa ha risposto l’agente. \u00c8 il pi\u00f9 visibile, ed \u00e8 il livello su cui si concentra di solito il feedback degli utenti finali. Il problema \u00e8 che da solo racconta pochissimo sulle cause. Una risposta sbagliata pu\u00f2 dipendere da un routing errato, da una fonte di conoscenza incompleta, da un tool che ha restituito un errore gestito male, da un prompt che non copre un caso limite. Senza andare pi\u00f9 in profondit\u00e0, questi scenari sono indistinguibili.<\/p>\n\n\n\n

Il secondo \u00e8 il livello dell’esecuzione<\/strong>: quali componenti sono stati attivati, in quale ordine, con quali input e output. Qui troviamo il router (quale percorso ha scelto e perch\u00e9), il retriever (quali documenti ha recuperato), i tool chiamati con i loro parametri e le loro risposte, le condizioni valutate, le variabili aggiornate. \u00c8 il livello che permette di fare debug reale<\/strong>: se il router ha instradato male una richiesta puoi vederlo, se il retriever ha recuperato documenti poco pertinenti puoi intervenire sulla strategia, se un tool ha restituito un errore puoi capire se \u00e8 un problema di schema, di timeout o di parametri.<\/p>\n\n\n\n

Il terzo \u00e8 il livello del ragionamento<\/strong>: perch\u00e9 l’agente ha preso quella decisione? Quali alternative aveva valutato? Su quali criteri si \u00e8 basato? Non \u00e8 una curiosit\u00e0 tecnica. \u00c8 ci\u00f2 che permette di verificare se il comportamento dell’agente \u00e8 davvero allineato con le intenzioni di chi lo ha progettato, e di dimostrarlo quando serve, anche in contesti regolamentati.<\/p>\n\n\n\n

Come funziona in pratica: i badge delle sessioni in Userbot<\/strong><\/h2>\n\n\n\n

Passiamo al concreto. Come si trasforma tutto questo in qualcosa di utilizzabile ogni giorno?<\/p>\n\n\n\n

In Userbot 3.0<\/strong>, il punto di accesso all’osservabilit\u00e0 \u00e8 la sezione Conversazioni<\/strong>. Ogni sessione, di test o di produzione, \u00e8 navigabile nel dettaglio: non una semplice trascrizione di messaggi, ma una mappa di tutti i blocchi che sono stati attraversati durante quell’interazione, ognuno con il proprio badge informativo<\/strong>.<\/p>\n\n\n

\n
\"\"
Esempio di una sessione in Conversazioni<\/strong><\/figcaption><\/figure>\n<\/div>\n\n\n

L’idea alla base \u00e8 semplice: ogni blocco del flusso, nel momento in cui viene eseguito, produce una traccia. Quella traccia viene resa leggibile come badge e resa accessibile direttamente dalla sessione. Il risultato \u00e8 che puoi ripercorrere un’interazione passo dopo passo, dall’input iniziale fino all’ultima azione eseguita, e capire esattamente cosa \u00e8 successo in ogni punto. Non devi ricostruire niente: \u00e8 tutto l\u00ec.<\/p>\n\n\n\n

Blocchi non agentici: codice, HTTP, condizioni<\/strong><\/h3>\n\n\n\n

Anche i blocchi “tradizionali”, quelli senza LLM, hanno il loro badge, e spesso \u00e8 gi\u00e0 sufficiente per risolvere il problema.<\/p>\n\n\n\n

\n
\"\"
Badge di un blocco Codice JS<\/strong><\/figcaption><\/figure>\n<\/div>\n\n
\n
\"\"<\/figure>\n<\/div><\/div>\n\n\n\n

Un blocco di codice JavaScript<\/strong> mostra il codice che \u00e8 stato eseguito, l’esito e, se qualcosa \u00e8 andato storto, il messaggio di errore con il dettaglio necessario per capire dove e perch\u00e9 si \u00e8 rotto. <\/p>\n\n\n\n

\n
\"\"
Badge di un blocco Richiesta HTTP<\/strong><\/figcaption><\/figure>\n\n\n\n
\"\"<\/figure>\n<\/div>\n\n\n\n

Un blocco di request HTTP<\/strong> ti mostra l’input della chiamata, la risposta ricevuta dal sistema esterno e quali valori sono stati poi salvati nelle variabili del flusso, utile per verificare se l’integrazione ha restituito quello che ti aspettavi e se i dati sono stati mappati nel modo corretto. <\/p>\n\n\n\n

\n
\"\"
Badge di un blocco Condizioni<\/strong><\/figcaption><\/figure>\n<\/div><\/div><\/div>\n\n\n\n

Un blocco di verifica condizione<\/strong> ti mostra cosa \u00e8 stato valutato: il valore della variabile presa in esame, la condizione applicata, il ramo che \u00e8 stato scelto.<\/p>\n\n\n\n

In tutti questi casi, e per qualsiasi tipo di blocco, il badge fa una cosa sola, ma la fa bene: trasforma ogni blocco da elemento opaco a elemento leggibile. Non devi ipotizzare cosa ha fatto, lo vedi.<\/p>\n\n\n\n

Blocchi agentici: prompt, parametri e memoria<\/strong><\/h3>\n\n\n\n

Nei blocchi che coinvolgono un agente AI il badge si arricchisce ulteriormente.<\/p>\n\n\n\n

\n
\"\"
Focus sulla sezione Impostazioni del badge del blocco Agente Custom<\/strong><\/figcaption><\/figure>\n<\/div><\/div><\/div>\n\n\n\n

Per ogni agente trovi esposti i parametri di configurazione e di chiamata: il prompt inserito, il modello selezionato, la temperatura, i max token. Trovi la memoria attivata<\/a><\/strong> in quel momento (conversazionale o profonda) cos\u00ec puoi vedere esattamente quale contesto era disponibile per l’agente quando ha elaborato la risposta. Se la risposta \u00e8 sembrata “scollata” dalla conversazione precedente, spesso \u00e8 perch\u00e9 la memoria non era configurata come pensavi.<\/p>\n\n\n\n

\n
\"\"
Focus sui parametri e i chunk del badge del blocco dell’Agente Retriever<\/strong><\/figcaption><\/figure>\n<\/div><\/div><\/div>\n\n\n\n

Nel caso del Retriever Agent<\/strong> trovi anche i chunk estratti<\/a> dalle fonti e utilizzati per costruire la risposta. Non solo “ha consultato la knowledge base”, ma quali porzioni specifiche di quali documenti sono state recuperate. Quando un retriever risponde in modo impreciso o fuori tema, questa \u00e8 la prima cosa da guardare: spesso il problema non \u00e8 nel prompt, ma nella qualit\u00e0 dei chunk o nella pertinenza delle fonti.<\/p>\n\n\n\n

Il Thought of Process: la cosa pi\u00f9 importante<\/strong><\/h3>\n\n\n\n

La sezione pi\u00f9 preziosa del badge agentico si chiama Thought of Process<\/strong>, ed \u00e8 quella che cambia davvero il modo di lavorare con gli agenti AI.<\/p>\n\n\n\n

\n
\"\"
Focus sul Thought of Process del badge del blocco dell’Agente Router<\/strong><\/figcaption><\/figure>\n<\/div><\/div><\/div>\n\n\n\n

Non \u00e8 un log tecnico nel senso tradizionale. \u00c8 la spiegazione che l’agente produce su se stesso: perch\u00e9 ha risposto in quel modo, quale ragionamento ha seguito, quali elementi del contesto o del prompt hanno guidato la sua decisione. In sostanza, l’agente ti racconta cosa ha pensato<\/strong>.<\/p>\n\n\n\n

Immagina di ricevere una risposta inattesa da un agente. Prima del Thought of Process, il processo di debug era: formulare un’ipotesi su dove il prompt poteva essere ambiguo, fare una modifica, ritestare, sperare. Un ciclo lento, costoso, e spesso frustrante. Con il Thought of Process, salti quella fase: l’agente ti dice direttamente dove il prompt non era chiaro, cosa aveva capito e perch\u00e9 ha preso quella direzione.<\/p>\n\n\n\n

\u00c8 anche lo strumento che permette di distinguere due tipi di problema che all’esterno sembrano identici ma richiedono interventi completamente diversi: un agente che ha sbagliato perch\u00e9 il prompt era incompleto<\/strong>, e un agente che ha sbagliato perch\u00e9 le informazioni disponibili erano insufficienti o errate<\/strong>. Nel primo caso lavori sul prompt, nel secondo lavori sulle fonti. Senza il Thought of Process, spesso non sai da dove iniziare.<\/p>\n\n\n\n

I tool: sai sempre se sono stati chiamati e come \u00e8 andata<\/strong><\/h3>\n\n\n\n

Per i blocchi che coinvolgono tool, chiamate ad API esterne, integrazioni con CRM, ERP, sistemi di ticketing, il badge risponde sempre alle due domande fondamentali: il tool \u00e8 stato invocato? La chiamata \u00e8 andata a buon fine?<\/p>\n\n\n\n

\n
\"\"
Focus sulla sezione Tools del badge di un blocco agentico<\/strong><\/figcaption><\/figure>\n<\/div><\/div><\/div>\n\n\n\n

Sembra una cosa ovvia, ma in pratica risolve uno dei pattern di errore pi\u00f9 frustranti nel debug degli agenti AI. Quando un agente “non fa niente”, non apre il ticket, non aggiorna il record nel CRM, non invia la notifica, la prima cosa da capire \u00e8 se il problema \u00e8 nell’agente o nell’integrazione. Il tool \u00e8 stato chiamato? Se s\u00ec, cosa ha restituito? Se no, perch\u00e9 no? Con il badge questa informazione \u00e8 sempre l\u00ec, senza bisogno di andare a cercare nei log di sistema o fare debug lato API.<\/p>\n\n\n\n

Sapere se il tool \u00e8 stato chiamato con successo o meno ti dice immediatamente dove guardare dopo. E questo, in pratica, pu\u00f2 fare la differenza tra mezz’ora di debug e mezza giornata.<\/p>\n\n\n\n

L’osservabilit\u00e0 non si aggiunge dopo: va progettata dall’inizio<\/strong><\/h2>\n\n\n\n

Una cosa che abbiamo imparato costruendo sistemi agentici in produzione \u00e8 che l’osservabilit\u00e0 non \u00e8 una feature che si aggiunge a sistema pronto. \u00c8 una propriet\u00e0 che va progettata dall’inizio, nell’architettura. Se la pensi come un’aggiunta successiva, arrivi tardi: nel momento in cui ne hai davvero bisogno, le informazioni non ci sono.<\/p>\n\n\n\n

Questo significa che ogni componente (router, retriever, tool executor, agente di condizione) deve produrre output strutturati e tracciabili. Il sistema deve mantenere un contesto di esecuzione navigabile attraverso tutti i passaggi di un’interazione. E le informazioni esposte devono essere progettate per rispondere a domande specifiche, non solo per “registrare eventi”.<\/p>\n\n\n\n

In Userbot 3.0, questo principio ha guidato la progettazione della sezione Conversazioni e del sistema di badge fin dall’inizio. L’obiettivo non era costruire uno strumento di debug riservato agli sviluppatori, ma rendere il ragionamento dell’AI leggibile e verificabile per chiunque abbia bisogno di capire o migliorare il comportamento di un agente: un engineer, un team operations, un auditor che deve dimostrare conformit\u00e0 a un processo.<\/p>\n\n\n\n

Nella pratica, questo significa che quando qualcosa non funziona non si parte da zero. Si apre la sessione, si scorrono i blocchi attraversati, si apre il badge del punto in cui il comportamento era inatteso, si legge il Thought of Process. In molti casi la causa \u00e8 immediatamente visibile: un parametro configurato male, una memoria che non era attiva, un chunk poco pertinente recuperato dal retriever, un tool che ha restituito un errore non gestito. Si interviene in modo chirurgico, si ritesta.<\/p>\n\n\n\n

Il legame tra osservabilit\u00e0 e stabilit\u00e0 nel tempo<\/strong><\/h2>\n\n\n\n

C’\u00e8 un ultimo aspetto che vale la pena nominare, perch\u00e9 tende ad essere sottovalutato nelle fasi iniziali di un progetto agentico, e diventa evidente solo pi\u00f9 avanti.<\/p>\n\n\n\n

L’osservabilit\u00e0 degli agenti AI<\/strong> non serve solo a correggere gli errori di oggi. Serve a mantenere il sistema stabile nel tempo, anche quando i componenti sottostanti cambiano, e cambieranno, perch\u00e9 \u00e8 la natura di questo campo. I modelli LLM vengono aggiornati dai provider. Le fonti di conoscenza evolvono. Le policy aziendali cambiano. In un sistema ben osservabile puoi introdurre questi cambiamenti in modo controllato: misuri il comportamento prima, introduci la modifica, verifichi che il comportamento resti allineato con le aspettative.<\/p>\n\n\n\n

In un sistema opaco, ogni cambiamento \u00e8 un rischio che scopri solo dopo. Non sai cosa hai rotto finch\u00e9 qualcuno non se ne accorge, che in produzione di solito significa un utente insoddisfatto o un processo che si \u00e8 interrotto.<\/p>\n\n\n\n

Per questo in Userbot 3.0 l’architettura separa nettamente i layer che devono restare stabili (policy, guardrail, contratti delle API) da quelli che possono variare, come il modello LLM utilizzato per un determinato task. Quando questi layer sono separati, la visibilit\u00e0 su ciascuno diventa uno strumento di governance attivo: ti permette di cambiare quello che vuoi cambiare senza toccare quello che vuoi mantenere stabile.<\/p>\n\n\n\n

In fondo, l’osservabilit\u00e0 \u00e8 la condizione che rende possibile la fiducia verificabile<\/strong> nell’AI. Non la fiducia cieca nel fatto che “di solito funziona bene”, ma quella basata su dati, tracce e misure concrete. Quella che serve quando gli agenti AI entrano nei processi davvero critici, dove sbagliare ha un costo reale.<\/p>\n\n\n\n

Con Userbot 3.0, l’AI non \u00e8 pi\u00f9 un atto di fede. \u00c8 un processo che puoi osservare, misurare e migliorare nel tempo.<\/p>\n\n\n\n

\n\n\n\n