L’osservabilità degli agenti IA deve aiutare un operatore a spiegare cosa è successo a un’attività aziendale. Un grafico della latenza del modello o dell’uso di token non indica quale record cliente sia cambiato, perché una richiesta sia stata rifiutata o chi sia responsabile di un’operazione ancora incerta.
Osservate l’intera attività attraverso l’agente, i suoi strumenti e i sistemi di destinazione. Conservate identificatori con ambito definito, transizioni di stato significative e prove indipendenti del risultato senza raccogliere liberamente contenuti sensibili. Segnalate il lavoro che richiede intervento e assegnate a ogni avviso un responsabile chiaro dell’indagine.
Immaginate un agente che crea un’attività di follow-up nel CRM dopo aver controllato un ordine. Dice all’utente che il lavoro è completo, ma il team commerciale non lo trova. L’indagine deve collegare la richiesta originale all’account selezionato, alla chiamata dello strumento, al riferimento di destinazione e al risultato osservato. Il solo registro delle risposte del modello non basta.
Questa guida riguarda le operazioni in produzione. La nostra guida alla valutazione degli agenti IA tratta l’accettazione prima del rilascio. I due ambiti devono condividere le definizioni dei risultati mantenendo i propri scopi distinti.
Definire l’osservabilità degli agenti IA intorno all’attività
Identificate un’unità di lavoro che un collega riconosca. Può essere una richiesta, una domanda su un ordine o l’approvazione di una bozza. Assegnatele un riferimento stabile e definite gli stati accettati, compresi attesa, rifiuto, completamento e mancata risoluzione.
Separate il successo dell’esecuzione da quello aziendale. Uno strumento può restituire una risposta tecnicamente accettata mentre la destinazione mette il lavoro in coda per revisione. Il progetto di osservabilità deve rendere visibile questa distinzione anziché classificare come concluso ogni risultato senza errore.
| Stato | Significato operativo da definire | Prove necessarie all’operatore |
|---|---|---|
| Ricevuto | L’attività è entrata nel flusso supportato | Riferimento originale e ambito |
| In attesa | Una dipendenza o decisione umana è pendente | Motivo dell’attesa e responsabile |
| Rifiutato | Il flusso autorizzato non può proseguire | Regola o confine che lo ha impedito |
| Completato | Il risultato aziendale concordato è confermato | Riferimento di destinazione e stato osservato |
| Incerto | Un’operazione potrebbe avere avuto effetto | Riferimento operativo e percorso di riconciliazione |
Usate queste definizioni in modo coerente nell’interfaccia, nella telemetria e nelle procedure di assistenza. Se l’utente vede completato mentre la dashboard operativa mostra in coda, il sistema deve spiegare la differenza. Altrimenti l’apparente osservabilità crea resoconti contraddittori della stessa attività.
Collegare richiesta, strumenti e destinazione
I concetti di tracing di OpenTelemetry descrivono span e contesto propagato per correlare operazioni. Questi meccanismi collegano l’attività tecnica tra servizi. Non definiscono la vostra regola aziendale di completamento: l’applicazione deve aggiungere le prove adeguate del risultato.
Preservate il rapporto tra attività, tentativi di esecuzione e operazioni esterne. Un’attività può coinvolgere più chiamate al modello e tentativi. Un’esecuzione può anche creare lavoro che continua in modo asincrono. Evitate di equiparare il numero di richieste al modello a quello delle attività aziendali concluse.
Trasmettete il contesto attraverso code e passaggi umani quando opportuno. L’operatore deve poter passare dal riferimento dell’attività allo strumento e al risultato di destinazione pertinenti senza confrontare manualmente orari tra dashboard indipendenti.
Registrate la versione che ha determinato il comportamento: distribuzione dell’applicazione, definizioni pertinenti degli strumenti e configurazione delle istruzioni. Controllate i contenuti sensibili delle istruzioni. L’obiettivo è identificare cosa è stato eseguito, non esporre ogni valore di configurazione interno a ogni utente della dashboard.
Raccogliere prove utili senza registrare tutto
Partite dalle domande dell’indagine. Quale account è stato scelto? Quale operazione è stata richiesta? Quale autorità è stata applicata? Quale risposta è stata osservata? Molte risposte si ricavano da riferimenti, stati e codici di motivazione anziché dal contenuto integrale di messaggi o documenti.
Le indicazioni OWASP sul logging affrontano i dati sensibili da escludere o trattare con cautela. Applicate questo principio prima di esportare prompt, risposte o argomenti degli strumenti a un fornitore di telemetria. La comodità del debug non giustifica conservare indefinitamente i record dei clienti.
| Prova | Perché può aiutare | Domanda sulla gestione |
|---|---|---|
| Riferimenti di attività e operazione | Collegare tentativi ed effetti di destinazione | L’identificatore può rivelare un contesto sensibile? |
| Ambito utente e tenant | Indagare decisioni sui permessi | Chi può consultare le informazioni di identità? |
| Nome dello strumento e stato del risultato | Identificare il confine difettoso | Si raccolgono troppi argomenti o risultati? |
| Riferimenti di versione | Riprodurre il comportamento pertinente | Dove si conserva la configurazione controllata? |
| Riferimento di approvazione umana | Spiegare l’autorità di un’azione | È recuperabile la versione approvata? |
Definite la conservazione secondo scopo e conseguenze. Un payload diagnostico temporaneo e un’approvazione commerciale duratura possono richiedere trattamenti diversi. Documentate chi può recuperare contenuti e come si revisionano gli accessi anziché mettere ogni record in un unico archivio generale di log.
Distinguere problemi del modello e dell’integrazione
Un’attività fallita può derivare da un’interpretazione errata, un permesso mancante, dati originali obsoleti, una destinazione indisponibile o una regola aziendale che nessun componente ha codificato. Conservate contesto sufficiente per distinguere questi percorsi prima di cambiare il modello o il prompt.
Per esempio, una selezione corretta dello strumento può fallire perché le credenziali della destinazione sono scadute. Viceversa, una risposta API sana può accompagnare un abbinamento cliente sbagliato. Metriche di disponibilità tecnica e verifiche del risultato rispondono a domande diverse, ed entrambe possono servire.
Mantenere visibili i risultati incerti
Quando una scrittura supera il tempo massimo, registrate l’incertezza e il riferimento per l’ispezione. Non classificate il tentativo come fallimento certo solo perché la risposta non è arrivata. L’operatore successivo deve sapere se una ripetizione può produrre un altro effetto aziendale.
La nostra guida allo sviluppo di server MCP spiega questo confine per un’integrazione di protocollo. Lo stesso principio vale con API dirette o altri meccanismi: ispezionate la destinazione prima di affermare se la scrittura sia avvenuta.
Segnalare condizioni operative che richiedono azione
Un avviso deve identificare lavoro su cui qualcuno deve intervenire. Esempi sono una scrittura incerta senza responsabile, una coda di revisione oltre l’attesa concordata o un insieme crescente di attività accettate che non raggiungono mai la conferma della destinazione. Scegliete soglie dai bisogni operativi del flusso.
Evitate avvisi per ogni rifiuto ordinario. Una richiesta correttamente respinta può non richiedere intervento. Distinguete il comportamento previsto delle regole da uno schema che suggerisce permessi difettosi, input ostili o un nuovo caso cliente non supportato.
Specificate il primo passo dell’indagine e il responsabile dell’escalation. Un avviso «errore dell’agente» senza riferimento dell’attività o contesto di destinazione induce a ripetere congetture. Una procedura operativa assegnata deve spiegare cosa si può riprovare, cosa va ispezionato e quali azioni richiedono approvazione.
Testate il percorso di allerta con un incidente controllato. Verificate la ricezione nella coda o presso l’operatore previsto e confermate che i riferimenti portino a prove utilizzabili. Una regola visibile in una console di monitoraggio non dimostra che il collega reperibile sappia risolvere il guasto.
Fare riflettere i risultati accettati nelle dashboard
Riportate separatamente le famiglie di attività supportate. Le consultazioni ordinarie possono dominare un aggregato e nascondere prestazioni scarse in un gruppo più piccolo di scritture importanti. Mostrate lavoro in attesa e incerto accanto alle attività concluse e rifiutate.
Misurate la durata dai confini aziendali pertinenti. Il tempo di risposta del modello può escludere l’attesa in revisione o un processo ritardato nella destinazione. Decidete se all’utente interessa la prima conferma, la bozza approvata o l’operazione esterna completata, poi nominate la metrica di conseguenza.
Osservate il lavoro di correzione e le attività riaperte. Un agente rapido che produce record da riparare può apparire efficiente in una dashboard delle richieste. Collegate queste riparazioni all’attività originale quando possibile, perché la visione operativa includa le conseguenze.
Esplicitate i limiti della copertura telemetrica. Campionamento, confini dei fornitori e record storici mancanti possono limitare l’indagine. Indicate quali prove si conservano per operazioni critiche ed evitate di suggerire che ogni attività passata sia ricostruibile quando i dati non sono disponibili.
Scegliere deliberatamente convenzioni e fornitori
Preferite contratti dati documentati e percorsi di esportazione a una dashboard comprensibile solo al suo autore. Controllate lo stato attuale delle convenzioni telemetriche specifiche per agenti prima di adottarle. Questa guida non presume che una convenzione semantica in evoluzione sia uno schema stabile per sempre.
L’avviso di OpenTelemetry sulle convenzioni di IA generativa rimanda al repository attualmente mantenuto. Seguite quel punto di manutenzione nell’implementazione. Documentate i significati di attività e risultati propri dell’applicazione anche quando cambiano i nomi degli attributi delle librerie.
Confrontate fornitori per capacità d’indagine, gestione dei dati, conservazione, controllo degli accessi e costo operativo. Un visualizzatore di tracce impressionante serve solo se riceve le prove necessarie al flusso e l’operatore autorizzato sa interpretarle.
Includete i guasti della telemetria nel progetto. Decidete quali record aziendali devono restare disponibili se la destinazione del monitoraggio non funziona. Perdere una traccia diagnostica non deve cancellare silenziosamente l’unico record di un’azione esterna approvata.
Definire costi e un primo risultato utile
Richiedete un preventivo in GBP che separi progettazione degli stati, strumentazione, correlazione della destinazione, allerta e passaggio operativo. Includete costi ricorrenti di archiviazione, acquisizione e revisione. Registrare ogni token e payload degli strumenti può creare spese senza un valore d’indagine proporzionato.
| Pacchetto di lavoro | Risultato | Fattore di ambito |
|---|---|---|
| Mappatura dei risultati | Stati di attività e prove accettate | Numero di operazioni aziendali distinte |
| Strumentazione | Riferimenti tecnici e aziendali collegati | Servizi, code e confini esterni |
| Controlli dei dati | Politica di conservazione e accesso | Sensibilità del contenuto raccolto |
| Allerta | Condizioni assegnate e procedure testate | Risposta richiesta e copertura dell’assistenza |
| Passaggio | Esempi d’indagine e responsabilità di manutenzione | Responsabilità di team e fornitore |
Il nostro pilota di integrazione IA circoscritto può iniziare da un’attività che il team fatica a spiegare. Inviateci il risultato mancante e le prove disponibili oggi per discutere una strumentazione che sostenga una decisione operativa concreta.
Domande frequenti
Che cos’è l’osservabilità degli agenti IA? È la capacità di indagare comportamento e risultati aziendali di un agente attraverso prove tecniche e operative collegate. La copertura utile include stato dell’attività, azioni degli strumenti, autorità, effetti di destinazione e passaggi umani.
Basta un registro dei prompt? No. Può mostrare ciò che il modello ha ricevuto e restituito, ma non stabilire se un’operazione esterna sia conclusa o quale account sia interessato. Conservate prove di destinazione e riferimenti stabili.
Dobbiamo registrare ogni argomento e risposta degli strumenti? Non come impostazione predefinita. Partite dalle domande d’indagine e raccogliete le prove meno sensibili che rispondono. Ogni contenuto conservato richiede uno scopo esplicito, una politica di accesso e un accordo di conservazione.
Come si distingue dalla valutazione? La valutazione controlla casi concordati per sostenere una decisione di rilascio. L’osservabilità aiuta a indagare il lavoro in produzione. Devono condividere le definizioni dei risultati, ma test superati non sostituiscono le prove operative.
Cosa deve attivare un avviso? Condizioni che richiedono intervento, come scritture incerte senza responsabile o attività oltre l’attesa concordata. Non ogni rifiuto previsto deve chiamare un operatore. Verificate che gli avvisi contengano un riferimento utilizzabile e un percorso d’indagine.
Possiamo diagnosticare ogni attività storica? Solo nella misura in cui le prove necessarie sono state conservate e si possono collegare. Campionamento, conservazione e visibilità dei fornitori esterni creano limiti. Documentateli e preservate deliberatamente i record richiesti dalle azioni aziendali importanti.
Qual è un primo progetto utile? Scegliete un problema d’indagine ricorrente. Mappate gli stati dell’attività, aggiungete riferimenti mancanti, verificate le prove di destinazione ed esercitate il percorso di allerta o assistenza. Ampliate quando il team sa usare con successo le prove.