L'osservabilità degli agenti AI vuole contratti

L’osservabilità degli agenti AI ha bisogno di trace contract, non di screenshot.

Sembra una distinzione sottile finché un agente interno sbaglia in produzione. Un agente per il customer success aggiorna il campo sbagliato su un account. Un assistente finance legge numeri dal workspace errato. Un agente di sales operations arricchisce un lead con dati vecchi e apre un task alla persona sbagliata. Il postmortem parte con un thread Slack pieno di screenshot: la chat, la risposta finale, forse il reclamo dell’utente. Tutti vedono cosa ha scritto l’agente. Quasi nessuno vede cosa ha fatto.

Screenshot e log di conversazione creano teatro della visibilità. Sono utili per le demo, per esempi di training e per una prima triage del supporto. Non bastano per governare un sistema in produzione, perché riducono l’esecuzione a una conversazione. Un agente AI non è solo una chat. Riceve un’intenzione, pianifica passaggi, legge contesto, chiama tool, attende approvazioni, gestisce errori e produce conseguenze operative. Se la traccia non mostra questi movimenti, il team non sta osservando l’agente. Sta guardando l’ombra che ha lasciato.

Un trace contract è l’accordo minimo tra prodotto, operations ed engineering su ciò che ogni run in produzione deve registrare. Non deve essere pesante. Deve essere esplicito. Prima di aggiungere altri tool, più autonomia o nuovi agenti, serve auditare un workflow reale e decidere cosa deve essere tracciabile sempre.

Gli screenshot nascondono il rischio vero

La parte rischiosa di una run raramente è la frase finale. È il percorso tra la richiesta dell’utente e l’esito.

Uno screenshot può mostrare che l’agente ha risposto: “Ho aggiornato la data di rinnovo”. Non mostra quale account ID è stato toccato, quale sistema ha accettato l’update, quale permesso ha consentito la chiamata, se l’utente ha approvato l’azione, quale fallback è partito dopo un errore API o chi possiede l’incidente se l’update è sbagliato.

Questa differenza conta perché gli agenti interni stanno tra sistemi di record e decisioni umane. La domanda di produzione non è “L’agente sembrava ragionevole?” La domanda è “Possiamo ricostruire la run abbastanza bene da fare debug, audit e assegnare responsabilità?”

Langfuse descrive il tracing per applicazioni LLM come record strutturati di una richiesta, capaci di catturare prompt, risposte del modello, uso dei token, latenza, tool, passaggi di retrieval, timing, input, output e metadati. È la direzione corretta: osservabilità significa struttura causale, non cattura dello schermo. La documentazione di riferimento è qui: Langfuse observability documentation.

Per questo la governance degli agenti non può fermarsi ai permessi. In Agenti AI: servono permessi, non accesso totale, la domanda è cosa l’agente può toccare. L’osservabilità aggiunge la domanda successiva: quando l’agente usa quel permesso, il team può dimostrare perché, quando, come e sotto la responsabilità di chi?

Cosa deve contenere un trace contract?

Un trace contract utile non è un dump generico di log. È un piccolo schema costruito intorno a domande operative. Quando una run fallisce, un leader dovrebbe rispondere a sette domande senza chiedere a un engineer di ricostruire tutto a memoria.

Primo, ogni run ha bisogno di un run ID. Il run ID è la maniglia che collega richiesta utente, step dell’agente, tool call, approvazioni, errori, output e lavoro successivo. Senza run ID, l’investigazione diventa archeologia tra log, dashboard, cronologia chat e ticket.

Secondo, va registrata l’intenzione dell’utente così come è stata interpretata all’inizio della run. Non basta salvare il prompt grezzo. Serve l’intento normalizzato su cui il workflow ha agito: “aggiorna data di rinnovo”, “riassumi fatture non pagate”, “prepara nota di escalation”, “crea ticket di supporto”. Questo permette a prodotto e operations di confrontare ciò che l’utente ha chiesto con ciò che l’agente ha creduto di dover fare.

Terzo, servono gli step principali dell’agente. Non ogni token deve essere esposto, e il reasoning sensibile può richiedere cautele. Ma la traccia operativa dovrebbe mostrare la sequenza: classifica richiesta, recupera contesto account, chiama tool CRM, chiede approvazione, scrive aggiornamento, notifica owner. È la differenza tra una trascrizione e un record della run.

Quarto, vanno catturate le tool call con input, output, sistema target, permission scope e stato. La specifica Model Context Protocol distingue i tool, cioè funzioni che il modello può eseguire, dalle risorse, cioè contesto e dati. Questa distinzione è utile per l’osservabilità: una traccia deve mostrare quando l’agente ha solo letto contesto e quando ha eseguito un’azione tramite tool. Il riferimento tecnico è la Model Context Protocol specification.

Quinto, vanno registrate le approvazioni. Se il workflow prevede controllo umano, la traccia deve dire chi ha approvato, cosa ha visto, cosa è cambiato dopo l’approvazione e se l’approvazione era obbligatoria o facoltativa. “C’era un umano nel loop” non basta. I sistemi di produzione hanno bisogno del punto decisionale preciso.

Sesto, errori e fallback vanno classificati con una tassonomia condivisa. Timeout, permesso negato, intento ambiguo, contesto mancante, azione non sicura, record duplicato, bassa confidenza e violazione di policy non sono lo stesso fallimento. Trattarli tutti come “l’agente ha fallito” produce retry ciechi e alert rumorosi. È lo stesso principio di L’automazione AI ha bisogno di classi di errore: l’osservabilità serve solo se gli errori sono nominati in modo azionabile.

Settimo, vanno registrati impatto decisionale ed escalation owner. L’agente ha solo preparato una bozza, aggiornato un campo, attivato un workflow di pagamento, inviato un messaggio esterno o modificato uno stato visibile al cliente? Chi possiede la run se l’esito è sbagliato: prodotto, support ops, data, security, finance o service owner? Una traccia senza ownership è un reperto da museo. Spiega il passato, ma non migliora la prossima run.

Come cambia il monitoraggio in produzione?

Un trace contract sposta il monitoraggio da “l’agente è online?” a “l’agente si comporta dentro il modello operativo?”

Il monitoring tradizionale parte spesso da latenza, error rate, costo e volume. Sono metriche ancora importanti. Anche i sistemi agentici ne hanno bisogno. Però non bastano, perché gli agenti combinano interpretazione probabilistica ed effetti deterministici. Una run veloce può essere pericolosa. Una tool call senza errore tecnico può rappresentare l’azione business sbagliata. Una completion riuscita può essere comunque un fallimento di governance se ha saltato un’approvazione.

La panoramica di Microsoft Agent Framework evidenzia agenti che processano input e chiamano tool, workflow con checkpointing e human-in-the-loop, middleware per intercettare azioni, telemetry e gestione dello stato. La lezione pratica non è che ogni team debba usare quel framework. È che i sistemi agentici in produzione hanno bisogno di superfici esplicite dove l’esecuzione possa essere controllata, osservata e interrotta. Il riferimento è la Microsoft Agent Framework overview.

Una volta definito il trace contract, le dashboard diventano più utili. Invece di contare solo conversazioni, puoi segmentare le run per intento, tool, stato di approvazione, fallback, classe di errore, owner e livello di impatto. Invece di chiedere “Quale agente produce più messaggi?”, puoi chiedere “Quale intento produce più override manuali?” oppure “Quale tool genera più escalation?”

Questa è la differenza tra analytics e operations. L’analytics descrive l’uso. Le operations cambiano il comportamento.

Un trace contract minimo per un agente

Parti piccolo. Scegli un agente interno che tocca già un workflow reale. Non iniziare dalla più ambiziosa architettura multi-agente. Scegli un agente noioso in produzione: triage ticket, enrichment CRM, spiegazione fatture, bozza per knowledge base, sintesi rinnovo o routing lead.

Scrivi un trace contract minimo con questi campi:

• Run ID
• Timestamp e ambiente
• Utente o sistema che avvia la run
• Intento normalizzato
• Versione agente o versione workflow
• Modello e versione prompt, se rilevanti
• Fonti di contesto usate
• Tool call tentate
• Input e output delle tool call, con redazione dei campi sensibili dove necessario
• Permission scope usato
• Approvazione richiesta, approvazione domandata, approvazione concessa o negata
• Classe di errore e percorso di fallback
• Output finale o azione finale
• Oggetto business impattato, come account, ticket, fattura o lead
• Livello di impatto decisionale
• Escalation owner
• Regola di retention e accesso alla traccia stessa

Questa lista non serve a creare burocrazia. Serve a forzare una conversazione adulta prima dello scale. Se il team non riesce a concordare chi possiede un aggiornamento sbagliato su un rinnovo, l’agente non è pronto per ampia autonomia. Se nessuno sa quali campi siano sicuri da salvare nelle tracce, il progetto di osservabilità sta rendendo visibile un problema di data governance, non lo sta inventando.

Lo stesso vale per il design dei workflow. In Agenti AI: servono code operative, non solo prompt, la coda crea una superficie operativa visibile per priorità, retry e handoff. Il trace contract crea la superficie di evidenza per ogni run. La coda dice cosa dovrebbe succedere dopo. La traccia dice cosa è successo davvero.

Prima di aggiungere tool, fai audit di una run

La tentazione è risolvere l’incertezza degli agenti aggiungendo un’altra dashboard, un’altra eval o un’altra integrazione. A volte servono. Ma se manca la traccia di base, ogni nuova capacità aumenta il raggio d’impatto più rapidamente del controllo.

Fai un audit semplice questa settimana. Scegli una run completata in produzione e chiedi al team di ricostruirla usando solo le evidenze disponibili. Qual era l’intento dell’utente? Quale contesto è stato letto? Quali tool sono stati chiamati? Quale sistema è cambiato? L’approvazione era richiesta? Chi ha approvato? Cosa è fallito? Quale fallback è partito? Quale decisione business è stata impattata? Chi possiede il risultato?

Se le risposte richiedono screenshot, memoria tribale o query dirette sul database, l’agente non è abbastanza osservabile. Crea il trace contract prima di espandere lo scope.

L’osservabilità degli agenti AI non consiste nel collezionare log più belli. Consiste nel rendere l’autonomia responsabile. Uno screenshot mostra la conversazione. Un trace contract mostra il lavoro.