Gli agenti AI stanno entrando nei flussi di lavoro aziendali: rispondono a clienti, smistano ticket, interrogano database, scrivono codice, prenotano appuntamenti. Il problema è che, spesso, nessuno sa davvero cosa fanno passo per passo. L’osservabilità degli agenti AI — cioè la capacità di tracciare, loggare e monitorare ogni decisione e ogni azione di un agente in produzione — non è un dettaglio tecnico: è la differenza tra un sistema che puoi fidarti di lasciare acceso di notte e uno che ti costringe a controllarlo ogni ora.
In questo articolo vediamo cosa significa concretamente rendere osservabile un agente AI, cosa tracciare, come organizzare log e metriche, e quando far scattare un alert prima che un errore diventi un problema per il cliente.
Perché l’osservabilità di un agente AI è diversa da quella del software tradizionale
Con un’applicazione web classica, il comportamento è deterministico: stesso input, stesso output, e il logging tradizionale (richieste, errori, tempi di risposta) basta a capire cosa succede. Un agente AI è diverso: lo stesso prompt può produrre percorsi diversi, l’agente decide autonomamente quali strumenti chiamare, in che ordine, e quante volte ripetere un tentativo. Non basta sapere “è andato in errore”: serve capire perché ha scelto quella strada, quali dati ha visto e quale ragionamento lo ha portato a un’azione sbagliata (o giusta, ma inefficiente).
Questo vale ancora di più quando un agente opera con memoria a lungo termine: se un errore di oggi dipende da un fatto memorizzato tre settimane fa, senza tracciamento end-to-end è quasi impossibile risalire alla causa.
Cosa tracciare: il minimo indispensabile
Per un agente AI in produzione, i dati da registrare in modo strutturato sono almeno questi:
- Trigger e input: cosa ha avviato l’esecuzione (un messaggio, un cron, un webhook) e con quale contenuto.
- Prompt e contesto: la versione del prompt di sistema usata e il contesto effettivamente passato al modello, non solo un riassunto.
- Tool call: ogni strumento invocato, con i parametri in ingresso e il risultato ottenuto — inclusi i fallimenti.
- Decisioni intermedie: quando l’agente pianifica più passaggi, vale la pena registrare la sequenza scelta, non solo l’esito finale.
- Costi e token: quante chiamate al modello sono state fatte e quanto sono costate, per capire se un’esecuzione è “esplosa” in loop inutili.
- Esito finale e durata: successo, fallimento parziale, richiesta di intervento umano.
Chi ha già introdotto meccanismi di supervisione umana degli agenti AI sa che questi log servono anche a decidere quando un’azione deve fermarsi e chiedere conferma: senza una traccia chiara delle decisioni, anche il miglior guardrail arriva troppo tardi.
Tracing end-to-end: seguire l’agente dal trigger all’azione finale
La pratica più efficace è assegnare a ogni esecuzione un identificativo unico (un trace ID) che accompagna ogni log, ogni chiamata a strumenti esterni e ogni scrittura su sistemi terzi (CRM, email, database). In questo modo, quando un cliente segnala “l’assistente mi ha risposto in modo sbagliato”, è possibile ricostruire l’intera catena — dal messaggio ricevuto, al prompt usato, alle chiamate effettuate — invece di affidarsi a ipotesi.
Per aziende che orchestrano più agenti specializzati in sequenza (uno che raccoglie dati, uno che li elabora, uno che agisce), il trace ID diventa ancora più importante: permette di capire in quale “anello” della catena si è verificato il problema, senza dover rileggere l’intero flusso da zero.
Log strutturati e metriche: cosa mettere in una dashboard
I log in testo libero vanno bene per il debug manuale, ma non scalano. Conviene registrare eventi in formato strutturato (JSON), con campi coerenti — tipo di evento, trace ID, esito, durata — così da poterli aggregare in metriche utili:
- Tasso di successo per tipo di richiesta gestita dall’agente.
- Numero medio di tool call per esecuzione, e outlier (esecuzioni con troppe chiamate = possibile loop).
- Tempo medio di risposta, con soglie diverse per compiti semplici e complessi.
- Frequenza delle richieste di intervento umano, come indicatore indiretto di quanto l’agente sia effettivamente affidabile.
- Costo per esecuzione, aggregato per giorno o per cliente/processo.
Questi principi non sono diversi da quelli di una buona osservabilità delle web app aziendali: cambiano gli eventi da tracciare, ma l’impostazione — log strutturati, metriche aggregate, dashboard leggibile — resta la stessa disciplina applicata a un sistema più imprevedibile.
Alert e soglie: quando un agente va fermato
Un agente osservabile non serve solo a capire cosa è successo dopo, ma a intervenire prima che il danno si propaghi. Alcune soglie che conviene impostare fin dal primo giorno:
- Numero massimo di tool call per singola esecuzione, oltre il quale l’agente si ferma e chiede conferma.
- Spesa massima giornaliera in chiamate al modello, con notifica automatica al superamento.
- Tasso di errore anomalo su un tipo di richiesta specifico, segno che qualcosa a monte (un’API, un formato dati) è cambiato.
- Azioni “irreversibili” (invio email, scrittura su sistemi esterni, pagamenti) sempre loggate con evidenza separata, indipendentemente dall’esito.
Questi meccanismi si integrano naturalmente con i guardrail di sicurezza per gli agenti AI: l’osservabilità è ciò che permette a un guardrail di scattare al momento giusto, invece di essere una regola statica scollegata da cosa l’agente sta effettivamente facendo.
Come lo imposto in pratica
Nella mia infrastruttura, gli agenti AI girano su container Docker gestiti via Portainer, con log centralizzati e accessibili via SSH per ogni ambiente cliente. Questo permette di avere, per ogni agente in produzione, uno storico consultabile delle esecuzioni, senza dipendere da dashboard di terze parti o da servizi cloud esterni — un vantaggio non da poco quando i log contengono dati aziendali sensibili. Per aziende più piccole, anche un semplice sistema di log strutturati con rotazione e un canale di alert (email o chat) è già un salto di qualità enorme rispetto al “funziona finché non si accorge nessuno che non funziona”.
Conclusione
Un agente AI senza osservabilità è una scatola nera che, prima o poi, produce un errore che nessuno riesce a spiegare al cliente. Investire fin da subito in tracing, log strutturati, metriche e soglie di allarme non è un costo accessorio: è ciò che rende possibile scalare l’uso degli agenti AI in azienda senza perdere il controllo su cosa fanno davvero.
Se la tua azienda sta introducendo agenti AI nei processi interni o rivolti ai clienti e vuoi progettarli in modo che restino tracciabili, sicuri e sotto controllo fin dal primo giorno, contattami: costruisco automazioni e agenti AI su misura, con infrastruttura solida e osservabilità integrata, non aggiunta a posteriori. Scopri anche gli altri progetti nel mio portfolio.
Approfondisci anche: Agenti AI e Tool Calling: Scegliere lo Strumento Giusto, per capire come un agente sceglie quale strumento invocare e come gestire gli errori delle chiamate.
Approfondisci anche: come testare e validare un agente AI prima di metterlo in produzione.
