AgentOps: monitorare e governare gli agenti AI con IBM Telemetry utilizzando watsonx Orchestrate

Con il crescente livello di sofisticazione e autonomia degli agenti AI, comprendere il loro comportamento, le loro prestazioni e i processi decisionali è fondamentale per garantirne l'affidabilità e la governance. AgentOps, la pratica di monitoraggio, osservazione e gestione degli agenti AI in produzione, fornisce la visibilità necessaria per costruire sistemi di agentic AI affidabili.

Questo tutorial offre una guida dettagliata alla configurazione e all'utilizzo di IBM Telemetry con watsonx Orchestrate Developer Edition per monitorare e governare gli agenti AI. Imparerai come abilitare l'observability degli agenti AI e analizzarne il comportamento in modo approfondito, dalle singole chiamate agli LLM fino ai workflow multifase completi.

Al termine di questo tutorial, sarai in grado di:

• Installare e configurare watsonx Developer Edition localmente
• Abilitare IBM Telemetry per un'observability completa degli agenti
• Importare e testare un agente AI preconfigurato con integrazione di strumenti esterni
• Analizzare il comportamento degli agenti attraverso tracce, attività, span e workflow dettagliati
• Risolvere i problemi e ottimizzare le prestazioni degli agenti utilizzando l'analytics avanzata

IBM Telemetry è il framework nativo di observability di watsonx Orchestrate che raccoglie informazioni dettagliate su come i tuoi agenti AI eseguono le richieste. Registra ogni fase del ciclo di vita dell'agente, dalle decisioni di routing e creazione dei prompt alle invocazioni LLM e le chiamate agli strumenti, fornendo una visibilità completa sul comportamento dell'agente.

Con IBM Telemetry puoi monitorare le metriche delle prestazioni, tenere sotto controllo i costi degli LLM, identificare gli errori e verificare che i tuoi agenti operino come previsto. IBM Telemetry fornisce un'observability di livello aziendale progettata per ambienti di produzione e sistemi AI su larga scala.

Prima di iniziare, assicurati che i seguenti prerequisiti siano installati e configurati sul tuo sistema:

• Python 3.8+ (Verifica con python --version )
• minimo 16 GB di RAM
• watsonx Orchestrate Developer Edition tramite watsonx Orchestrate ADK

Questa guida include le fasi di installazione dell'ADK.

• Account watsonx Orchestrate: prova gratuita di 30 giorni disponibile se non hai un account.
• Chiave API watsonx Orchestrate, generata dalla tua dashboard IBM Cloud

I passaggi per l'autorizzazione sono descritti più avanti in questa guida.

Per iniziare, clona il repository GitHub utilizzando https://github.com/IBM/ibmdotcom-tutorials.git come URL HTTPS. Per istruzioni dettagliate su come clonare un repository, consulta la documentazione di GitHub.

Apri il repository nel tuo ambiente di sviluppo integrato (IDE) preferito (ad esempio, Visual Studio Code) e individua la cartella del progetto di questo tutorial: wxo-agentops . Questa è la directory in cui lavorerai mentre segui questo tutorial.

L'IBM watsonx Orchestrate Agent Development Kit (ADK) è uno strumento CLI che semplifica l'installazione, la configurazione e la gestione di watsonx Orchestrate Developer Edition.

Per utilizzare l'ADK, devi collegarlo a un ambiente watsonx Orchestrate esistente. Se non hai ancora un account watsonx Orchestrate, puoi richiedere una prova gratuita di 30 giorni. Se hai già un account, puoi utilizzarlo per fornire all'ADK le credenziali dell'ambiente necessarie.

Questi passaggi ti guideranno durante l'installazione utilizzando un ambiente virtuale Python, che è l'approccio consigliato per mantenere isolate le dipendenze. Per metodi di installazione alternativi e istruzioni dettagliate, consulta la documentazione introduttiva dell'ADK.

Crea un nuovo ambiente virtuale Python nella directory del tuo progetto:

Questo passaggio crea una cartella .venv contenente un ambiente Python isolato.

Il comando di attivazione varia a seconda del sistema operativo.

macOS e Linux

Windows

Una volta attivato, il prompt del terminale dovrebbe cambiare per indicare che stai lavorando all'interno dell'ambiente virtuale (in genere mostrando (.venv ) all'inizio del prompt).

Con l'ambiente virtuale attivato, installa l'ADK utilizzando pip:

Questo comando scarica e installa l'ADK insieme a tutte le sue dipendenze. Il completamento dell'installazione può richiedere alcuni minuti.

Nota: Se hai installato una versione precedente dell'ADK (>2.0 ), esegui pip install --upgrade ibm-watsonx-orchestrate . Potrebbe anche essere necessario eseguire le azioni di risoluzione dei problemi descritte nel passaggio 4b.

L'ADK utilizza un file .env per autenticare le tue credenziali utente e configurare la watsonx Orchestrate Developer Edition. Le variabili di ambiente di cui hai bisogno dipendono dal metodo di autenticazione scelto. Questo tutorial utilizza il metodo dell'account watsonx Orchestrate, che è l'approccio più semplice per iniziare.

Per metodi di autenticazione alternativi e istruzioni dettagliate sulla configurazione, consulta la documentazione sulla configurazione del file dell'ambiente.

All'interno della directory wxo-agentops, crea un file .env  copiando il modello fornito:

Apri il file .env nel tuo editor di testo e configura i seguenti due campi essenziali:

• WO_INSTANCE : questo URL è la tua istanza di watsonx Orchestrate. Puoi trovare queste informazioni accedendo al tuo account watsonx Orchestrate e passando ai dettagli della tua istanza. Clicca sull'icona del profilo > Settings, quindi seleziona la scheda API details. Per istruzioni dettagliate su come iniziare con l'API, consulta la documentazione di watsonx Orchestrate.

L'URL segue questo formato:

Copia e incolla l'URL della tua istanza di servizio per sostituire il valore del modello nel file .env . La regione (ad esempio, us-south dipende dalla tua posizione geografica).

• WO_API_KEY : Questa è la tua chiave API (Application Programming Interface) di watsonx Orchestrate, che autentica la tua connessione ai servizi IBM Cloud. Puoi generare o recuperare questa chiave dalla dashboard del tuo account IBM Cloud. Sostituisci <your-api-key> con la tua chiave API effettiva. Per istruzioni dettagliate sulla generazione di una chiave API, consulta la documentazione introduttiva.

Conserva la tua chiave API in modo sicuro e non inserirla mai in un sistema di controllo delle versioni. Il file .env dovrebbe già essere incluso nel tuo .gitignore per prevenire esposizioni accidentali. 

Ora puoi installare la watsonx Orchestrate Developer Edition, che eseguirà un'istanza locale del server watsonx Orchestrate sulla tua macchina. Questo passaggio abilita anche IBM Telemetry, con accesso immediato alle funzionalità di observability.

Comprendere il comando di installazione

L'ADK fornisce un unico comando che gestisce l'intero processo di installazione:

Analizziamo cosa fa questo comando:

• orchestrate server start : inizializza e avvia il server watsonx Orchestrate Developer Edition
• -e <path-.env-file> : indica il file di configurazione contenente le credenziali
• --with-ibm-telemetry : abilita il framework di observability nativo di IBM Telemetry

Esegui il comando dalla directory wxo-agentops:

Il seguente comando avvia il server watsonx Orchestrate Developer Edition inizializzando l'ambiente server: orchestrate server start -e <path-.env-file> . L'aggiunta del flag --with-ibm-telemetry  abilita IBM Telemetry, il suo framework di observability nativo.

Esegui questo comando per installare il server watsonx Orchestrate con IBM Telemetry:

Questo comando crea container interni gestiti dall'ADK per:

• Il server watsonx Orchestrate
• Database PostgresSQL e Redis
• Servizi IBM Telemetry
• Supporto delle dipendenze

L'ADK configura automaticamente una rete virtuale che permette a questi container di comunicare tra loro tramite http://localhost:3000 .

Il processo di installazione può richiedere diversi minuti, soprattutto alla prima esecuzione, poiché vengono scaricate le immagini necessarie. Un'installazione riuscita produce un output simile a questo esempio:

Se vedi questo messaggio, congratulazioni! Il tuo ambiente locale watsonx Orchestrate con IBM Telemetry è ora in esecuzione.

Se l'installazione fallisce o si blocca, prova a eseguire i seguenti passaggi:

1.    Resetta il server:

Questo comando arresta e rimuove tutti i container creati per watsonx Orchestrate, consentendoti di ripartire da un ambiente pulito.

2.    Riavvia l'installazione:

Dopo il ripristino, esegui nuovamente il comando start:

3.    Controlla i log e lo stato del container del server:

Puoi visualizzare i log di servizio del server Orchestrate per verificare la presenza di avvisi o errori:

non funzionano, reimposta il server rimuovendo completamente l'ambiente del server: orchestrate server purge , quindi reinstallalo.

Con il server watsonx Orchestrate installato correttamente, è ora necessario attivare l'ambiente locale e avviare l'interfaccia di chat da cui interagirai con i tuoi agenti AI.

Il watsonx Orchestrate ADK supporta più ambienti (locale, sviluppo, produzione e così via). Devi attivare esplicitamente l'ambiente locale che hai creato:

Dovresti ricevere conferma che l'ambiente è attivo:

Questo imposta l'ambiente locale come contesto predefinito per tutti i comandi ADK successivi. Tutti gli agenti, gli strumenti o le configurazioni con cui lavorerai ora faranno riferimento a questa istanza locale.

Avvia il servizio di interfaccia utente della chat di watsonx Orchestrate con il seguente comando:

Questo comando avvia l'interfaccia di chat web e la apre automaticamente nel browser predefinito. Dovresti vedere un output simile a:

L'interfaccia di chat offre un modo semplice per interagire con i tuoi agenti AI. Se il browser non si apre automaticamente, puoi accedere manualmente a http://localhost:3000/chat-lite.

Una volta caricata l'interfaccia di chat, dovresti visualizzare una finestra di chat pulita, pronta per l'interazione. A questo punto, non hai ancora importato agenti, quindi l'interfaccia sarà per lo più vuota. Questo risultato è previsto, nel prossimo passaggio aggiungerai il tuo primo agente.

Ora che il tuo ambiente è configurato, è il momento di importare un Agente AI preconfigurato che dimostri le funzionalità di monitoraggio di IBM Telemetry. Questo agente meteo utilizza uno strumento API esterno per recuperare dati meteorologici in tempo reale, offrendoti un esempio pratico da osservare e analizzare.

L'agente meteo è un punto di partenza ideale perché:

• Dimostra l'utilizzo degli strumenti: mostra come gli agenti chiamano le API esterne
• Fornisce un comportamento chiaro e osservabile: ogni richiesta segue un pattern prevedibile
• Genera dati telemetrici significativi: produce tracce ricche che puoi analizzare in IBM Telemetry
• Include scenari di errore: ti aiuta a comprendere come la telemetria gestisce gli errori
• Illustra l'automazione: elimina la ricerca manuale dei dati tramite azioni dell'agente

Dalla directory principale del progetto (wxo-agentops ), vai alla cartella Weather Agent:

Questa directory contiene due file di configurazione YAML:

• get_weather.yaml : definisce lo strumento API meteo
• weather_agent.yaml : definisce l'agente che utilizza questo strumento

Gli strumenti sono funzionalità riutilizzabili che gli agenti possono invocare per eseguire azioni specifiche. Importa prima gli strumenti get_weather :

Il flag --kind openapi indica che questo strumento utilizza una specifica OpenAPI per definire la propria interfaccia. Dovresti vedere la conferma che lo strumento è stato importato correttamente.

Ora importa l'agente che userà questo strumento:

Questo comando registra il Weather Agent nel tuo ambiente watonsx Orchestrate locale. L'agente è preconfigurato con:

• Istruzioni su come interpretare i dati meteorologici
• Autorizzazione a chiamare lo strumento get_weather
• Comportamento di fallback in caso di località non valide

Torna al browser dove è in esecuzione l'interfaccia della chat. Potresti dover aggiornare la pagina per vedere l'agente appena importato.

Clicca sul menu a discesa dell'agente (situato solitamente in alto nell'interfaccia della chat) e seleziona Weather_Agent dalla lista

Con il Weather Agent selezionato, prova a fare alcune domande per generare dati di telemetria:

Esempi di query:

• "Com'è il tempo a New York?"
• "Puoi dirmi la temperatura attuale a Londra?"
• "Che tempo fa a Tokyo?"
• "Sta piovendo a Seattle in questo momento?"

L'agente elaborerà ogni richiesta attraverso:

1. Comprensione della tua richiesta
2. Estrazione della località
3. Chiamando lo strumento get_weather con le coordinate giuste
4. Interpretazione dei dati meteorologici
5. Risposta in linguaggio naturale

Ogni interazione che hai con il Weather Agent viene acquisita da IBM Telemetry. Il sistema sta registrando:

• Il contesto completo della conversazione
• Ogni invocazione LLM e i token utilizzati
• Chiamate di strumenti con i loro input e output
• Decisioni di routing e passaggi del workflow
• Tempi di esecuzione e metriche di prestazione
• Eventuali errori o eccezioni che si verificano
• Interazioni con provider esterni e loro tempi di risposta

Nella fase successiva, esplorerai in dettaglio questi dati di telemetria per capire esattamente come si comporta il tuo agente.

Ora arriva la parte più importante di questo tutorial: utilizzare IBM Telemetry per ottenere una visibilità approfondita sul comportamento del tuo agente. IBM Telemetry offre molteplici visualizzazioni e strumenti di analytics che ti permettono di comprendere ogni aspetto del modo in cui il tuo agente elabora le richieste.

Apri il browser e accedi a https://localhost:8765/?serviceName=wxo-server. L'interfaccia offre la funzionalità di replay delle sessioni, che ti consente di riesaminare le interazioni passate con gli agenti per analizzarle.

Nota: l'URL utilizza https ma poiché questo spazio è un ambiente di sviluppo locale, il browser potrebbe visualizzare un avviso di sicurezza relativo a un certificato autofirmato. Questo messaggio è previsto ed è possibile ignorarlo in sicurezza nel tuo ambiente locale.

Quando viene visualizzata la schermata di accesso, inserisci un nome qualsiasi (per identificare la tua sessione locale) e fai clic su Login.

Verrai indirizzato alla dashboard principale di IBM Telemetry.

La dashboard mostra un elenco di tracce recenti, ognuna delle quali rappresenta una singola interazione dell'utente con un agente. Nel pannello Trace and Group Selection, fai clic sulla prima traccia per visualizzare analisi dettagliate relative alla tua più recente conversazione con il Weather Agent.

Questo passaggio ti porta alla schermata Agent Analytics, che funge da punto di riferimento per comprendere il comportamento degli agenti.

La schermata Agent Analytics fornisce una panoramica della traccia selezionata, tra cui:

• Statistiche di riepilogo: tempo totale di esecuzione, utilizzo dei token, stime dei costi e dati di benchmarking
• Informazioni sull'agente: quale agente ha gestito la richiesta
• Query dell'utente: la domanda posta in origine
• Anteprima della risposta: la risposta finale dell'agente
• Indicatori di stato: successo, avvisi o errori

Questa vista avanzata offre insight immediati per verificare se l'agente ha operato come previsto e con quale livello di efficienza.

La sezione Tasks è dove trascorrerai la maggior parte del tempo per analizzare il comportamento degli agenti. Fornisce una sequenza temporale visiva, passo dopo passo, di tutte le operazioni eseguite dall'agente durante una richiesta (ogni chiamata LLM, invocazione degli strumenti, decisione di routing e generazione di output).

Le attività sono organizzate in modo gerarchico per riflettere il modo in cui l'agente ha effettivamente eseguito il workflow, rendendo più semplice comprendere la sequenza delle operazioni e le relazioni tra di esse.

Esaminiamo il percorso di esecuzione standard di una richiesta a un agente watsonx Orchestrate. La traccia del tuo Weather Agent dovrebbe mostrare una struttura simile a questo esempio:

Questo workflow mostra l'intero ciclo di vita di una query di un singolo utente. Ecco cosa rappresenta ciascuna attività:

• 0:_ROOT : lo span di livello superiore che contiene tutte le attività figlie. Puoi immaginare questa cartella come quella che contiene l'intera esecuzione dell'agente. Definisce l'ora di inizio e di fine dell'intera traccia, dal momento in cui la richiesta entra nel sistema fino alla consegna della risposta finale.

Questo approccio è importante perché la durata dell'attività principale indica la latenza complessiva percepita dall'utente. Se questo valore è troppo elevato, puoi analizzare le attività figlie per individuare i colli di bottiglia.

• 0.0:agent_style_router : l'attività di routing determina quale agente deve gestire il messaggio e classifica la richiesta in una modalità di gestione. Il router analizza la richiesta in ingresso e stabilisce se richiede una gestione conversazionale, un'esecuzione basata su strumenti, la retrieval-augmented generation (RAG) oppure un'orchestrazione multi-agente.

Il router garantisce che venga richiamata la logica a valle appropriata. Se le richieste vengono indirizzate in modo errato, è qui che puoi individuare il problema.

• 0.1:agent : il contesto principale di esecuzione dell'agente che orchestra l'intera richiesta. Questa attività assembla il prompt a partire dalle istruzioni di sistema, dalla cronologia della conversazione e dalle risposte degli strumenti. Applica le regole e le policy di orchestrazione e prepara gli input per l'LLM. Questa attività determina il tipo di chiamata LLM da effettuare.

Questo passaggio è il punto in cui avviene la vera "intelligenza" dell'orchestrazione. L'attività dell'agente garantisce che l'LLM riceva tutto il contesto necessario per prendere decisioni informate.

• 0.1.0:WatsonxChatModel.chat : la chiamata effettiva all'LLM, durante la quale riceve il prompt completo e decide se richiamare uno strumento, chiedere chiarimenti oppure fornire una risposta diretta. Genera la risposta, in formato testuale o tramite chiamate a strumenti strutturati.

Questo è il passaggio di "ragionamento", in cui il modello elabora le informazioni e prende decisioni. L'uso dei token, la latenza e i problemi di qualità derivano tutti da questa attività. Se il tuo agente è lento o costoso, questo passaggio è solitamente il problema principale.

• 0.2:answer : l'L'ultimo passaggio della catena prende l'output dell'LLM e lo formatta per la consegna. Questo compito converte l'output grezzo dell'LLM nel formato della risposta finale e applica eventuali regole di post-elaborazione o formattazione. Infine, restituisce la risposta all'interfaccia di chat.

Questa attività garantisce che l'utente riceva una risposta formattata correttamente. Se le risposte vengono troncate o formattate in modo non corretto, è in questo passaggio che dovresti iniziare l'analisi.

Riepilogo del workflow dell'attività

Per riassumere il workflow completo:

1. Il router decide come gestire la richiesta
2. L'agente prepara il contesto e la logica di orchestrazione
3. L'LLM genera la risposta o le chiamate agli strumenti
4. Formatta la risposta e restituisce l'output finale

L'intero workflow è racchiuso nel container della richiesta  ROOT e offre una visione completa dell'esecuzione dell'agente dall'inizio alla fine. Questo livello di observability è essenziale per i team MLOps e DevOps che gestiscono le operazioni degli agenti e pipeline complesse su larga scala.

Ogni attività della gerarchia contiene tre categorie di attributi che forniscono metadati dettagliati su ciò che l'attività ha utilizzato e prodotto:

1.    Attributi di input: mostrano tutto ciò che l'attività ha ricevuto prima dell'esecuzione (messaggi, risposte degli strumenti, istruzioni di sistema e stato interno).

Esempio: Per l'attività WatsonxChatModel.chat , gli attributi di input includono il prompt completamente assemblato con le istruzioni di sistema, la cronologia della conversazione ed eventuali risultati degli strumenti che devono essere interpretati.

2.    Attributi di output: mostrano ciò che l'attività ha prodotto, incluse le risposte generate dall'LLM, le chiamate agli strumenti e le decisioni prese.

Esempio: La stessa attività WatsonxChatModel.chat potrebbe produrre in output una risposta in linguaggio naturale oppure una chiamata strutturata a uno strumento come get_weather(latitude=40, longitude=-74) .

3.    Attributi generali: forniscono i metadati della telemetria, tra cui l'utilizzo dei token, le informazioni sui tempi di esecuzione, identificatori come gli ID univoci e le informazioni sul modello.

Esempio: potresti vedere che un'attività ha utilizzato 450 token di input e 120 token di output, ha impiegato 1,2 secondi per essere eseguita e ha utilizzato ibm/granite-3.1-8b-instruct model .

Come utilizzare gli attributi delle attività

Nel loro insieme, questi attributi consentono di comprendere appieno cosa ha visto il modello, quali decisioni ha preso e come ha risposto.

Questo livello di dettaglio è prezioso per il debug, l'ottimizzazione e la validazione.

Ogni attività include metriche relative alle prestazioni e ai costi che riassumono la modalità di esecuzione dell'attività. Queste metriche forniscono dati quantitativi sulle prestazioni degli agenti.

Le metriche chiave includono:

• Tempo totale di esecuzione: quanto tempo ha richiesto l'attività dall'inizio alla fine
• Conteggio delle chiamate LLM: quante volte è stato invocato il modello linguistico
• Numero di chiamate agli strumenti: quante volte sono stati chiamati strumenti esterni
• Utilizzo dei token: token di input, token di output e token totali consumati
• Stime dei costi: costi approssimativi basati sull'utilizzo dei token (quando sono disponibili i dati sui prezzi)
• Distribuzione delle attività secondarie: come il lavoro è stato distribuito tra le attività figlie

Queste metriche aiutano a ottimizzare le prestazioni e il comportamento dell'agente di debug. Possono anche aiutare a identificare attività lente che potrebbero essere parallelizzate o memorizzate nella cache. Questa vista è fondamentale per la pianificazione della capacità perché permette di comprendere i requisiti di risorse per la scalabilità e monitorare l'uso dei token per controllare le spese.

Ad esempio, se noti che una traccia ha impiegato 8 secondi ma solo 0,5 secondi sono stati spesi per le chiamate LLM, sai che il collo di bottiglia è altrove (probabilmente nell'esecuzione dello strumento o nella latenza di rete).

Mentre le attività mostrano il workflow logico del tuo agente, gli span rappresentano le operazioni sottostanti a livello di sistema che si verificano durante l'esecuzione. Facendo clic sulla scheda Spans è possibile visualizzare le operazioni interne eseguite dalla piattaforma per elaborare ciascuna richiesta.

Gli span offrono visibilità sulle operazioni di basso livello registrate dal framework di orchestrazione (in questo caso, LangGraph, un framework open source in esecuzione all'interno del wxo-server). Ogni intervallo rappresenta un'operazione discreta come:

• Routing della richiesta all'agente corretto (agent_style_router )
• Invocazione dell'agente e inizializzazione del suo contesto (agent.task )
• Creazione dei prompt e del contesto a partire dai template (ChatPromptTemplate.task )
• Chiamata al modello LLM con il prompt assemblato (WatsonxChatModel.chat )
• Restituzione dei risultati all'utente (answer.task )

Mentre le attività mostrano i passaggi logici dell'esecuzione dell'agente (ciò che l'agente sta cercando di realizzare), gli span mostrano i passaggi tecnici (come il sistema lo realizza). Questa doppia prospettiva offre sia una comprensione di alto livello sia la possibilità di eseguire il debug a basso livello.

Esempio: una singola attività come 0.1:agent può contenere più span che rappresentano query al database, ricerche nella cache e caricamento della configurazione. Queste operazioni avvengono dietro le quinte per supportare l'esecuzione dell'agente.

Ogni span include tag che forniscono metadati e contesto aggiuntivi. Questi tag sono essenziali per filtrare, eseguire il debug e analizzare le prestazioni dell'agente.

I tag degli span più comuni includono:

• Identificazione dell'agente: agent_id , agent_name
• Tracciamento della sessione: thread_id , session_id , conversation_id
• Contesto del workflow: step_number , workflow_path , parent_span_id
• Dati sulle prestazioni: token_count , duration_ms , model_name
• Dettagli della richiesta: tool_calls , input_preview , output_preview

Gli span sono utili per individuare le cause della latenza, comprendere gli errori identificando quale componente interno ha avuto un malfunzionamento, analizzare i modelli ricorrenti filtrando gli span in base ai tag per individuare le tendenze e correlare gli span tra più tracce utilizzando gli ID di sessione.

Ad esempio, se il tuo agente occasionalmente si blocca, puoi filtrare gli span in base alla durata per individuare quali operazioni interne richiedono un tempo insolitamente lungo, ad esempio una query al database o una chiamata di rete a un servizio esterno.

La scheda Workflows fornisce una vista gerarchica chiamata Runnables Tree che mostra la struttura completa di esecuzione del workflow dell'agente. Questa vista è particolarmente utile per comprendere sistemi multi-agente complessi e modelli di esecuzione annidati.

Nel framework watsonx Orchestrate, un runnable è un'unità di lavoro o attività che può essere eseguita. I runnable possono essere:

• Operazioni semplici: una singola chiamata LLM o invocazione dello strumento
• Workflow compositi: più runnable concatenati insieme
• Rami condizionali: diversi percorsi di esecuzione in base alle condizioni
• Esecuzioni parallele: più runnable in esecuzione simultaneamente

Il Runnable Tree mostra le relazioni padre-figlio, rendendo facile vedere:

• Quali attività ne innescano altre: seguendo la catena di esecuzione
• Esecuzione parallela o sequenziale: comprendere la concorrenza dei workflow
• Logica di ramificazione: come le decisioni portano a percorsi di esecuzione differenti
• Profondità del workflow: quanto è profondamente annidata la logica dell'agente

Per agenti semplici come il Weather Agent, la vista del workflow rispecchia molto da vicino la vista delle attività. Tuttavia, i workflow diventano preziosi quando si lavora con:

• Sistemi multi-agente: più agenti specializzati collaborano per svolgere un'attività
• Orchestrazione complessa: agenti che scelgono dinamicamente tra diversi strumenti o subagenti
• Perfezionamento iterativo: agenti che ripetono una sequenza di passaggi finché non viene soddisfatta una determinata condizione
• Routing condizionale: workflow che si diramano in base a risultati intermedi
• Architetture scalabili: progettare workflow che gestiscono carichi reali in modo efficiente

Ad esempio, immagina un agente che verifica innanzitutto se una richiesta richiede una ricerca sul web, quindi decide se utilizzare uno strumento di calcolo o uno strumento per interrogare un database e, infine, convalida il risultato prima di rispondere. Il Runnables Tree mostrerebbe chiaramente l'intera struttura ramificata.

Puoi interagire con l'albero nei seguenti modi:

• Espansione/compressione dei nodi: consente di concentrarsi su sezioni specifiche del workflow
• Facendo clic sui nodi: puoi passare direttamente alle informazioni dettagliate sull'attività
• Seguendo i percorsi di esecuzione: traccia il flusso dei dati attraverso la finestra
• Identificando i colli di bottiglia: Individua dove i workflow diventano inefficienti

La visualizzazione rende il debug dei workflow di debug molto più semplice rispetto al tentativo di seguire esclusivamente i log di testo o i dati delle tracce.

La scheda Eval (valutazione) offre una vista dedicata al monitoraggio e al controllo della qualità, che consente di misurare la correttezza e l'affidabilità dell'esecuzione del tuo agente. In questo passaggio si passa dall'osservazione di ciò che è accaduto alla valutazione di quanto bene è stato eseguito.

La scheda Eval mostra i risultati della valutazione che misurano la qualità attraverso i guardrail:

• Successo dell'attività: quali attività sono state completate e quali no
• Qualità dell'output: se gli output corrispondevano ai risultati attesi o ai criteri di qualità
• Punteggi delle prestazioni: metriche quantitative che indicano il livello di successo
• Analisi degli errori: categorizzazione e gravità degli errori
• Convalida dei casi d'uso: verifica se il comportamento dell'agente corrisponde ai casi d'uso previsti

Le valutazioni ti aiutano a monitorare l'affidabilità verificando con quale coerenza il tuo agente produce risultati corretti, a individuare quando le modifiche compromettono le prestazioni dell'agente, a stabilire le priorità degli interventi di miglioramento e ad aumentare la fiducia nel suo funzionamento convalidando che operi correttamente prima della distribuzione in produzione.

Puoi utilizzare le metriche di valutazione per configurare avvisi, monitorare i miglioramenti, individuare schemi ricorrenti e utilizzare il feedback per orientare lo sviluppo e migliorare i prompt o gli strumenti.

Se noti che il 15% delle richieste relative al meteo non supera la valutazione, puoi analizzare le tracce corrispondenti per capire se il problema è dovuto a una gestione non corretta degli input, a errori delle API o a una formattazione non corretta delle risposte.

La scheda Issues fornisce una visione centralizzata di tutto ciò che è andato storto durante l'esecuzione del workflow. Questa scheda è la prima tappa quando devi eseguire il debug di errori dell'agente o analizzare comportamenti imprevisti.

La scheda Issues elenca problemi quali:

• Chiamate API fallite: servizi esterni che restituiscono errori
• Fallimenti nell'esecuzione degli strumenti: strumenti che si bloccavano o avevano un timeout
• Input mancanti: dati richiesti non disponibili quando necessario
• Eccezioni dei modelli: errori LLM come limiti di token o input non validi
• Errori di convalida: dati che non soddisfano i formati previsti
• Errori di timeout: operazioni che hanno superato i limiti di tempo
• Errori di runtime non gestiti: eccezioni impreviste nel codice dell'agente

Nella schermata precedente puoi vedere un Tool Error verificatosi quando l'API meteo ha restituito un errore 424 (Failed Dependency) o 404 (Not Found). La scheda Issues mostra:

1. Il tipo di errore: "Tool Error"
2. Lo strumento specifico: get_weather
3. La risposta di errore: la risposta completa dell'API che mostra l'errore
4. Un collegamento diretto: fai clic per passare direttamente all'attività in cui si è verificato l'errore

Questo approccio consente di capire facilmente cosa è andato storto senza dover analizzare i log o i dati delle tracce.

La scheda Issues è particolarmente utile perché aggrega gli errori, evitando di doverli cercare all'interno delle singole attività. Fornisce un contesto completo includendo tutti i dettagli degli errori e i dati correlati, mentre i livelli di gravità consentono di effettuare rapidamente il triage, così da stabilire quali problemi affrontare per primi. I collegamenti diretti alle attività di origine consentono di raggiungere con un solo clic l'esatto punto di esecuzione in cui si è verificato il problema.

La scheda Trajectory offre una vista cronologica, in stile conversazione, dell'interazione tra l'utente e gli eventuali strumenti invocati dall'agente. Questa vista è estremamente utile per comprendere il contesto completo e il flusso di esecuzione del comportamento dell'agente.

La vista Trajectory è utile perché consente di vedere esattamente come l'agente elabora le richieste dall'inizio alla fine, offrendo una visibilità completa sul suo comportamento. Puoi convalidare l'integrazione degli strumenti verificando che vengano richiamati con i parametri corretti e che ricevano risposte appropriate. Quando esegui il debug di risposte inattese, la vista Trajectory ti aiuta a individuare il punto in cui la logica si è discostata dal comportamento previsto. Puoi inoltre analizzare come il contesto si costruisce nel corso di più turni della conversazione, osservando come il workflow si evolve in modo naturale. Oltre a essere utile per il debug, la vista Trajectory funge anche da documentazione, consentendoti di acquisire esempi di comportamenti corretti da condividere con i membri del team o da utilizzare come casi di riferimento per gli sviluppi futuri. Questa vista è particolarmente utile per i team che sviluppano soluzioni basate sull'AI generativa e hanno la necessità di convalidare l'adattabilità dell'agente in scenari diversi.

Esaminiamo la traiettoria di Weather Agent mostrata nella schermata:

1.    La query dell'utente

La conversazione inizia con una richiesta chiara e specifica sul tempo a New York.

2.    L'agente effettua una chiamata a uno strumento

L'agente riconosce di avere bisogno di dati esterni e richiama lo strumento meteo:

Questo esempio mostra che l'agente ha identificato correttamente le coordinate approssimative di New York City (NYC), ha strutturato correttamente la richiesta per l'API e ha impostato il parametro appropriato per ottenere le condizioni meteo attuali.

IBM Telemetry visualizza questo risultato sia in formato JSON grezzo sia come una struttura ad albero, ben formattata ed espandibile.

3.    Lo strumento restituisce dati

L'API meteo risponde con dati meteorologici strutturati:

Questo esempio mostra che lo strumento ha recuperato correttamente i dati e che la risposta rispetta lo schema previsto, con tutti i campi obbligatori presenti. La possibilità di ispezionare la risposta grezza dello strumento è fondamentale per individuare e risolvere i problemi in cui l'agente interpreta in modo errato gli output dello strumento.

4.    L'agente riassume il risultato

Per finire, l'agente elabora i dati strutturati e risponde in modo naturale:

L'agente ha estratto correttamente la temperatura e il codice meteorologico, convertendo i dati strutturati in un linguaggio naturale. La risposta è concisa e risponde alla domanda dell'utente.

La scheda Trajectory supporta anche il filtraggio per ruolo, consentendo di visualizzare solo i messaggi dell'utente, quelli dell'agente oppure le interazioni con gli strumenti. È inoltre possibile espandere o comprimere le diverse sezioni delle conversazioni più lunghe, così da concentrarsi sui dettagli di maggiore interesse. Per un'analisi più approfondita o per il debug, è possibile esportare i dati in formato JSON e accedere alle attività collegate direttamente dai passaggi della traiettoria, così da visualizzarne i dettagli corrispondenti.

Congratulazioni! Hai configurato con successo IBM Telemetry con watsonx Orchestrate e hai imparato a monitorare e analizzare in modo approfondito il comportamento degli agenti AI. IBM Telemetry offre diversi livelli di visibilità, garantendo un'osservabilità completa del modo in cui gli agenti AI ragionano, prendono decisioni e agiscono. Le funzionalità illustrate sono fondamentali per una gestione efficace dell'intero ciclo di vita delle operazioni degli agenti in ambiente di produzione e per l'integrazione con altri framework di agenti presenti nel proprio ambiente.

In caso di problemi o domande, consulta la documentazione. I problemi più comuni sono trattati nella guida alla risoluzione dei problemi. Puoi anche consultare le issues di GitHub per vedere se altri hanno riscontrato problemi simili.

Il monitoraggio degli agenti tramite piattaforme come IBM Telemetry ha dato vita a un solido ecosistema per l'AgentOps, diventato essenziale man mano che gli agenti autonomi assumono compiti sempre più complessi, che prevedono l'integrazione di SDK, strumenti e API esterne. La visibilità acquisita sul comportamento degli agenti consente di creare sistemi di AI più affidabili, efficienti e degni di fiducia.