Man mano che aumenta il numero di agenti AI creati ogni giorno, le aziende stanno esplorando sistemi autonomi per supportare il processo decisionale e i workflow operativi. Allo stesso tempo, le organizzazioni esprimono spesso preoccupazioni riguardo a spiegabilità, governance e preparazione alla produzione, soprattutto nei sistemi multi-agente che si affidano a modelli linguistici di grandi dimensioni (LLM) per il ragionamento. È una sfida utilizzare agenti in contesti aziendali che forniscono risposte senza una spiegazione chiara o che mostrano comportamenti incoerenti.
Queste sfide possono essere affrontate utilizzando IBM watsonx Orchestrate, che offre una piattaforma strutturata in grado di supportare il self-hosting, il ragionamento basato sugli strumenti, le chiamate API e il controllo di livello aziendale senza richiedere codice di orchestrazione personalizzato.
Dynamiq ha creato un assistente multi-agente per la ricerca legale per un importante cliente assicurativo, indirizzando le query attraverso un classificatore IBM Granite a basso costo prima di passarle a un agente di ricerca più complesso. Rendere possibile questo workflow ad alta criticità ha richiesto una visibilità approfondita su ogni passaggio del ragionamento e su ogni chiamata agli strumenti. Integrando IBM watsonx Orchestrate, Dynamiq ha garantito che ogni decisione rimanesse completamente tracciabile, verificabile e corredata da citazioni, riducendo il tempo di revisione dei contratti da 90 a 45 minuti senza compromettere la governance.
In questo tutorial imparerai a creare un agente AI in watsonx Orchestrate utilizzando il watsonx Orchestrate Agent Development Kit (ADK). Nei sistemi AI basati su LangChain o LangGraph, gli sviluppatori devono spesso gestire manualmente i tentativi, la gestione dello stato e l'esecuzione asincrona. watsonx Orchestrate ADK semplifica questo processo grazie alla gestione integrata del ciclo di vita, che consente distribuzioni di agenti coerenti e pronte per l'ambiente enterprise.
Userai Python per creare la logica di valutazione del rischio, definire il comportamento dell'agente e integrare Langfuse per monitorare e migliorare il comportamento dell'agente con tracce di esecuzione reali. Puoi trovare questo tutorial anche su GitHub.
Langfuse è una piattaforma open source di observability LLM basata su OpenTelemetry per il monitoraggio di applicazioni e agenti LLM. Utilizza la telemetria (tracce, metriche e log) per monitorare le esecuzioni degli agenti, incluse le chiamate LLM, le chiamate agli strumenti, l'utilizzo dei token, i metadati e la latenza a livello di richiesta e sessione.
Consente agli sviluppatori di ottenere insight approfonditi sul modo in cui gli agenti operano in scenari reali, individuare la causa principale degli output errati e ottimizzare sistematicamente il comportamento degli agenti per una maggiore affidabilità ed efficienza.
L'obiettivo di questo tutorial è creare un agente AI per la governance aziendale che valuti il rischio dei fornitori attraverso un'analisi deterministica basata su regole. Abbiamo creato un set di dati sintetico di fornitori contenente valutazioni finanziarie, certificazioni di sicurezza e cronologia degli incidenti. L'agente elabora questi dati e classifica i fornitori in specifici livelli di rischio (basso, medio o alto), fornendo motivazioni a supporto delle proprie decisioni.
Supporta inoltre interazioni successive, consentendo agli utenti di confrontare i fornitori o simulare in che modo la modifica di determinati dati influirebbe sul punteggio di rischio, garantendo l'elevato livello di verificabilità richiesto per la conformità aziendale.
Di seguito è riportata una demo interattiva dell'agente per la valutazione del rischio dei fornitori completato e creato in questo tutorial. Esplora come l'agente classifica i fornitori, risponde alle domande e traccia il proprio processo di ragionamento tramite Langfuse, così da avere un quadro chiaro di ciò che stai creando prima di iniziare.
Per completare questo tutorial, sono necessari:
Python 3.11 o versioni successive installato sul sistema.
Un account watsonx Orchestrate. Per questo tutorial, un account di prova è sufficiente. Se non possiedi un account, puoi utilizzare IBM Cloud per creare una versione di prova gratuita di 30 giorni.
Una chiave API watsonx Orchestrate dall'interfaccia utente (UI) di Orchestrate.
Un watsonx Orchestrate ADK installato sul tuo sistema.
Accedi a watsonx Orchestrate tramite IBM Cloud e apri l'interfaccia utente di watsonx Orchestrate. Vai alla sezione API details dopo avere aperto Settings dal menu del profilo. Crea una nuova chiave API, copiala e salvala in modo sicuro. Durante lo sviluppo locale, il watsonx Orchestrate ADK viene autenticato con questa chiave API. watsonx Orchestrate funziona come un SDK (Software Development Kit) locale per costruire e testare la logica degli agenti.
In questo passaggio, crea un ambiente di sviluppo locale. Durante questo tutorial, eseguirai un server di sviluppo locale, importerai strumenti, configurerai gli ambienti e creerai agenti tramite l'interfaccia a riga di comando (CLI) orchestrata fornita dall'ADK in PowerShell. Inizia spostandoti nella directory in cui desideri creare il tuo progetto. Successivamente, crea un nuovo ambiente virtuale Python:
Un ambiente Python isolato viene creato in una cartella .venv. L'uso di un ambiente virtuale garantisce che tutte le dipendenze di questo tutorial siano separate dall'installazione di Python in tutto il sistema.
Attiva quindi l'ambiente virtuale. Il tuo sistema operativo determina quale comando di attivazione utilizzare.
Su Windows:
macOS e Linux:
Una volta attivato, il prompt del tuo terminale mostrerà .venv all'inizio per indicare che stai lavorando in un ambiente virtuale.
Con l'ambiente virtuale attivo, installa il watsonx Orchestrate ADK sulla tua macchina locale. Per usare l'ADK, collegalo al tuo attuale ambiente watsonx Orchestrate. Esegui il seguente comando in PowerShell:
Puoi completare i passaggi successivi dell'installazione di ADK seguendo le istruzioni riportate nel documento ufficiale di installazione.
Nota: questo tutorial esegue il runtime di watsonx Orchestrate Developer Edition in locale e lo collega all'istanza SaaS di watsonx Orchestrate utilizzando le credenziali.
Per eseguire questo metodo, crea un file chiamato .env nella cartella principale del progetto e aggiungi i seguenti valori:
Questo file .env è necessario per eseguire il server. Nei prossimi passaggi, inizierai con il comando orchestrate server start -e .env -l.
Successivamente, devi configurare il tuo ADK con una chiave API watsonx Orchestrate valida per connettere il tuo ambiente locale a watsonx Orchestrate.
Nota: Il watsonx Orchestrate ADK è compatibile con diversi tipi di ambienti, inclusi IBM Cloud, AWS e implementazioni on-premise. In questo tutorial utilizziamo l'ambiente on-premise e ci autentichiamo tramite una chiave API utilizzando l'ADK CLI. L'ADK gestisce le credenziali in modo sicuro internamente, pertanto per questa configurazione non è necessario impostare manualmente le variabili d'ambiente.
Dalla directory del tuo progetto (con l'ambiente virtuale attivato), esegui il seguente comando per aggiungere il tuo ambiente watsonx Orchestrate:
Qui, service-instance-url è il tuo URL di istanza watsonx Orchestrate. Puoi trovare queste informazioni nella stessa scheda API details all'interno di Settings nell'interfaccia utente di watsonx Orchestrate.
Successivamente, attiva l'ambiente che hai aggiunto:
Ora, quando richiesto, inserisci la chiave di watsonx Orchestrate ottenuta al passaggio 1. Una volta attivato l'ambiente, tutti i comandi successivi relativi all'ADK, come l'importazione di agenti e strumenti o l'avvio del server, verranno eseguiti nell'ambiente di watsonx Orchestrate.
Nota: se vuoi eseguire tutto localmente con la Developer Edition, puoi attivare l'ambiente locale predefinito nel seguente modo:
Questo comando imposta l'ADK per utilizzare l'ambiente Orchestrate locale integrato, utile per eseguire test in locale.
In questo passaggio creiamo il modello di framework dell'agente, che contiene la definizione, gli strumenti e il codice sorgente del Vendor Risk Intelligence Agent. Successivamente, andremo a creare la struttura di cartelle necessaria per lo sviluppo locale basato su ADK:
Puoi aggiungere il comando fornito qui per creare la struttura dell'agente:
Ogni cartella ha uno scopo specifico:
La cartella agents contiene il file YAML con le istruzioni, le regole di ragionamento e la configurazione del modello dell'agente. Determina il modo in cui il sistema risponde alle domande degli utenti. La cartella tools contiene un file YAML che descrive lo strumento fornito all'agente. La cartella src contiene l'implementazione Python per strumenti personalizzati e logica aziendale.
Avvia il server di watsonx Orchestrate in modo che possa ricevere e memorizzare le importazioni prima di importare strumenti e agenti. Esegui questo comando dalla cartella principale del progetto:
Il passaggio successivo riguarda l'observability dell'agente, in cui analizzerai il comportamento dell'agente durante l'esecuzione, ad esempio quali strumenti vengono chiamati, la latenza e i punti in cui si verificano eventuali errori. Per questo scopo, attiva l'observability Langfuse nell'ambiente watsonx Orchestrate ADK.
In questo tutorial viene utilizzata la versione SaaS di Langfuse, che consente di acquisire tracce senza eseguire Langfuse in locale.
Assicurati che il server watsonx Orchestrate sia in esecuzione (passaggio 6) prima di configurare Langfuse.
Successivamente, crea un account Langfuse su https://cloud.langfuse.com. Dopo avere effettuato l'accesso, crea una nuova organizzazione e un nuovo progetto. Dalle impostazioni del progetto, copia l'ID del progetto, la chiave pubblica, la chiave segreta e l'URL dell'host.
Ora configura Langfuse in watsonx Orchestrate ADK con il comando mostrato dopo questa sezione e sostituisci i segnaposto con i valori che hai copiato:
Una volta completato con successo questo comando, il modulo Langfuse sarà completamente integrato nell'ambiente watsonx Orchestrate. A questo punto, tutte le interazioni con gli agenti vengono automaticamente registrate nel modulo Langfuse.
Ora che il server è in funzione, puoi testare l'agente.
Il prossimo passo è definire il Vendor Risk Intelligence Agent. Gli agenti in watsonx Orchestrate ADK sono definiti tramite file YAML che descrivono l'obiettivo dell'agente, i limiti del suo ragionamento, la configurazione del modello e gli strumenti che è autorizzato a utilizzare.
All'interno della directory agent, crea un file chiamato vendor-risk-agent.yaml. Questo file rappresenta il livello di gestione dei prompt dell'agente e garantisce che tutte le risposte siano basate su un ragionamento deterministico, anziché su un'inferenza libera.
La definizione dell'agente utilizzata in questo tutorial è mostrata di seguito. Copia e incolla la seguente definizione dell'agente nel file agents/vendor-risk-agent.yaml . Salva il file in seguito.
Questa configurazione garantisce che l'agente si comporti in modo prevedibile nelle risposte a domande di tipo "che cosa", "perché", "come" e di confronto. l sistema previene le allucinazioni impedendo di formulare supposizioni sulle valutazioni finanziarie o sul significato dei livelli di rischio, a meno che tali informazioni non siano esplicitamente definite nell'output dello strumento.
In questo passaggio, implementa lo strumento Python che esegue la valutazione del rischio del fornitore. In watsonx Orchestrate ADK, la logica di business personalizzata viene implementata tramite strumenti Python che gli agenti utilizzano per ottenere i risultati. Anziché affidarsi al fine-tuning del modello per ottenere un comportamento specifico del dominio, questo tutorial mostra come implementare un ragionamento deterministico basato su regole tramite strumenti Python, garantendo risultati coerenti.
All'interno della cartella src, crea un file chiamato main.py. Questo file contiene il set di dati del fornitore che abbiamo creato, le regole di valutazione del rischio e uno strumento Python chiamato evaluate_all_vendor_risks che fornisce la logica all'agente.
La logica del rischio si basa su regole. In termini di segnali di rischio elevato, un'azienda può ricevere un punteggio di rischio elevato a causa delle sue scarse prestazioni finanziarie, di incidenti di sicurezza verificatisi in passato o di indagini da parte delle autorità di regolamentazione. Un'azienda può ricevere un punteggio di rischio medio a causa dell'assenza di certificazioni, di singoli incidenti operativi o di interruzioni causate dalle condizioni meteorologiche.
La funzione evaluate_all_vendor_risks è creata come uno strumento di watsonx Orchestrate, rendendola richiamabile dall'agente durante l'esecuzione. Lo strumento restituisce un output strutturato che include il livello di rischio finale insieme alle motivazioni esatte che hanno determinato la classificazione.
Nota: il file main.py incluso in questo tutorial è la versione finale aggiornata della logica di valutazione del rischio del fornitore. Le prime versioni del codice hanno causato comportamenti errati degli agenti, che sono stati analizzati tramite le tracce di Langfuse. Puoi trovare le tracce di Langfuse nelle schermate fornite nei passaggi successivi di questo tutorial.
L'implementazione completa del file main.py utilizzato in questo tutorial è riportata di seguito. Copiala e incollala in src/main.py. Successivamente, salva il file.
In questo passaggio, lo strumento e l'agente devono essere messi a disposizione di watsonx Orchestrate. Questo processo viene eseguito importando questi componenti nell'ambiente ADK attivato. Prima di eseguire i comandi di importazione, assicurati di essere nella cartella principale del progetto (la stessa che contiene le directory agents, src e tools).
Innanzitutto, importa lo strumento Python in modo che watsonx Orchestrate possa registrarlo come funzionalità eseguibile. Dalla cartella principale del progetto, esegui il seguente comando:
Questo comando crea un pacchetto del codice Python sotto forma di modulo, registra lo strumento evaluate_all_vendor_risks e lo rende richiamabile dagli agenti.
Il Vendor Risk Intelligence Agent è quindi completamente integrato con lo strumento Python nell'ambiente watsonx Orchestrate.
Con il server locale di watsonx Orchestrate in esecuzione e l'observability dell'agente abilitata, puoi ora testare l'agente e analizzarne il comportamento in tempo reale.
Avvia l'interfaccia di chat eseguendo il seguente comando:
Ora apri l'interfaccia utente di watsonx Orchestrate nel tuo browser. Dal selettore degli agenti, scegli Vendor_Risk_Intelligence_Agent e inizia a porre domande relative al rischio del fornitore.
Per verificare che l'agente stia rispondendo correttamente (e chiamando lo strumento Python in modo deterministico), ecco alcune domande di esempio che puoi usare per i test:
Mentre interagisci con l'agente, apri la dashboard di Langfuse nel browser. Ogni query utente crea una nuova traccia, include un session_id e un ID utente. Queste tracce registrano il percorso completo di esecuzione dell'agente. Selezionando una traccia, è possibile analizzare:
L'input e l'output completi dell'agente
L'invocazione dello strumento Python
I dati strutturati restituiti dallo strumento
Il processo di ragionamento seguito per giungere alla risposta finale
Latenza per ogni fase del processo
Flusso di conversazione basato su sessioni per domande multiple
Questa observability aiuta ad analizzare le metriche delle prestazioni che evidenziano colli di bottiglia come errori nelle ipotesi, regole incomplete o comportamenti imprevisti degli agenti.
Dopo avere testato l'agente, usa le tracce di Langfuse per identificare le risposte errate. Langfuse mostra l'invocazione, la fase di ragionamento e la latenza di risposta di ogni strumento, facilitando la comprensione del motivo per cui è stata prodotta una risposta.
In questo caso d'uso, l'analisi delle tracce ha rivelato che alcune risposte errate si verificavano quando l'agente inferiva il significato dei dati finanziari o rispondeva senza citare esplicitamente le evidenze basate sulle regole. Per correggere questo comportamento, le istruzioni dell'agente e il relativo codice Python sono stati modificati, imponendo un ragionamento rigorosamente basato su regole attraverso l'uso dello strumento appropriato.
Dopo avere reimportato i file aggiornati, l'agente è stato nuovamente testato. Le nuove tracce garantiscono che le risposte siano saldamente basate sull'output strutturato dello strumento, che le spiegazioni siano deterministiche e che le risposte a tutte le domande descrittive siano corrette.
Questo processo di osservazione e perfezionamento dimostra come Langfuse supporti lo sviluppo sicuro e affidabile degli agenti sulla base del feedback degli utenti.
Esplora la demo interattiva riportata di seguito per vedere in azione l'agente per la valutazione del rischio dei fornitori e il tracciamento con Langfuse.
Questo tutorial ti ha guidato nella creazione di un agente AI strutturato e affidabile con watsonx Orchestrate, progettato per lo sviluppo di agenti di livello aziendale. Grazie all'integrazione di una semplice logica Python basata su regole, di istruzioni chiare per l'agente e di strumenti riutilizzabili, hai implementato un caso d'uso per la valutazione del rischio dei fornitori con una quantità minima di codice e la massima trasparenza.
L'aggiunta di Langfuse ha reso semplice monitorare il comportamento dell'agente e rilevare i problemi nel processo di ragionamento, consentendo di migliorare continuamente l'accuratezza senza ricorrere a tentativi o supposizioni. Questo approccio consente alle aziende di ottimizzare i sistemi di agenti end-to-end, automatizzare workflow complessi e implementare sistemi AI con la massima trasparenza.
Ancora più importante, watsonx Orchestrate ADK e Langfuse, utilizzati insieme, consentono alle aziende di progettare, eseguire il debug e scalare più rapidamente workflow agentici complessi e applicazioni di AI, garantendo una governance più solida, un processo di ragionamento più trasparente e una riduzione dei tempi di sviluppo.
Crea, implementa e gestisci assistenti e agenti AI potenti che automatizzano workflow e processi con l'AI generativa.
Costruisci il futuro della tua azienda con soluzioni AI di cui puoi fidarti.
I servizi di AI di IBM Consulting aiutano a reinventare il modo in cui le aziende lavorano con l'AI per la trasformazione.