Implementa un agente LangGraph ReAct di supporto IT con IBM Granite su watsonx.ai

In questo tutorial creiamo un agente AI ReACT (Reasoning and Action) con il framework open source LangGraph utilizzando un modello IBM Granite con IBM® watsonx.ai API in Python. Il caso d'uso sarà la gestione delle richieste di assistenza IT esistenti e la creazione di nuove.

Un agente di intelligenza artificiale (AI) è un sistema o programma in grado di eseguire autonomamente attività per conto di un utente o di un altro sistema, progettandone il workflow e utilizzando gli strumenti disponibili. Gli agenti di AI generativa utilizzano le tecniche avanzate di elaborazione del linguaggio naturale (NLP) dei modelli linguistici di grandi dimensioni (LLM) per comprendere e rispondere passo dopo passo agli input degli utenti e determinare quando ricorrere a strumenti esterni. Una componente chiave degli agenti AI è il ragionamento. Dopo avere acquisito nuove informazioni tramite il tool calling, l'intervento umano o altri agenti, il paradigma del ragionamento guida i passi successivi dell'agente.

Con ogni azione e risposta di ogni strumento, il paradigma ReACT (Reasoning and Action) indica agli agenti di "pensare" e pianificare i passi successivi. Questo ragionamento lento e graduale ci offre insight su come l'agente utilizza il contesto aggiornato per formulare conclusioni. Poiché questo processo di riflessione è continuo, viene spesso definito ciclo think-act-observe ed è un tipo di prompt chain-of-thought.

Questo tutorial utilizza il framework LangGraph, un framework di agenti AI open source progettato per creare, implementare e gestire complessi workflow di agenti di AI generativa. La funzione predefinita create_react_agent fornita da LangGraph consente di creare facilmente un agente semplice e personalizzato. Gli agenti ReACT semplici, come quello di questo tutorial illustrato nella Figura 1, sono composti da due nodi. Un nodo è responsabile della chiamata del modello e l'altro nodo è responsabile dell'utilizzo degli strumenti. Gli strumenti comuni includono lo strumento predefinito LangChain Wikipedia, lo strumento DuckDuckGoSearchRun e persino la retrieval-augmented-generation (RAG). In caso di input di azioni complesse, è possibile aggiungere un altro nodo, come mostrato nella Figura 2. Questo nodo aggiuntivo avrebbe lo scopo di contribuire a garantire che l'agente restituisca un output strutturato.

All'interno di LangGraph, la funzione "state" funge da banca di memoria che registra e tiene traccia di tutte le informazioni preziose elaborate da ogni iterazione del sistema di AI. Questi grafici stateful consentono agli agenti di ricordare informazioni passate e un contesto prezioso. La struttura ciclica del grafico ReAct viene utilizzata quando il risultato di una fase dipende dai passaggi precedenti del ciclo. I nodi, o "attori", nel grafico codificano la logica degli agenti e sono collegati da edge. Gli edge sono essenzialmente funzioni Python che determinano il nodo successivo da eseguire in base allo stato corrente.

Per creare un progetto  watsonx.ai è necessario un account IBM Cloud.

Per utilizzare l'application programming interface (API) watsonx, è necessario completare i seguenti passaggi. Nota: puoi accedere a questo tutorial anche su GitHub. 

1. Accedi a watsonx.ai usando il tuo account IBM Cloud.

2. Crea un'istanza di servizio watsonx.ai Runtime (seleziona l'area geografica appropriata e scegli il piano Lite, che è un'istanza gratuita).

3. Genera una chiave API (application programming interface).

Per iniziare a implementare agenti su watsonx.ai facilmente, clona questo repository GitHub e accedi al progetto dell'agente ReAct di assistenza IT. Per farlo, puoi eseguire il seguente comando nel tuo terminale.

Installa quindi poetry se non lo hai già installato. Poetry è uno strumento per la gestione delle dipendenze e del packaging di Python.

Quindi, attiva il tuo ambiente virtuale.

Anziché usare il comando pip install il pacchetto poetry ci permette di aggiungere dipendenze eseguendo il seguente comando nel terminale. Questo passaggio installa le dipendenze del repository riflesse nel file pyproject.toml nel tuo ambiente virtuale separato.

L'aggiunta di una directory di lavoro a PYTHONPATH è necessaria per i passaggi successivi. Nel tuo terminale esegui:  

Per configurare il tuo ambiente, segui le istruzioni nel file README.md su Github. Questa configurazione richiede l'esecuzione di diversi comandi sull'IDE o sulla riga di comando.

Nel file config.toml troverai le seguenti credenziali vuote che devono essere compilate prima di tentare di implementare il tuo agente. I tuoi watsonx_apikey e watsonx_url sono stati inizializzati nella Fase 1 di questo tutorial. Segui quindi il semplice modulo che si trova nella pagina Developer Access per selezionare il tuo spazio di implementazione o crearne uno nuovo. Lì puoi recuperare lo space_id necessario per connettere il nostro agente all'implementazione watsonx.ai. Per finire, il tuo model_id è impostato sul modello IBM Granite 3.2.

Il nostro agente richiede una fonte di dati per fornire informazioni aggiornate e aggiungere nuovi dati. Memorizziamo il nostro file di dati in IBM Cloud Object Storage.

1. Per prima cosa, accedi a IBM Cloud. Quindi, crea un nuovo progetto.
2. Nel menu a sinistra, seleziona Elenco risorse. Utilizzando il pulsante Crea risorsa, crea una nuova istanza di Cloud Object Storage oppure usa semplicemente questo link.
3. Apri l'istanza IBM Cloud Storage appena creata e crea un nuovo bucket. Per questo tutorial puoi selezionare il livello Smart, ovvero il livello gratuito. Quando richiesto, carica il tuo file. Per il file di esempio, fai riferimento al file tickets.csv nel repository GitHub collegato nella Fase 2.

Per fornire all'agente ReACT la funzionalità di gestione dei ticket IT, dobbiamo connetterci alla nostra fonte di dati in IBM Cloud Object Storage. Per questo passaggio, possiamo utilizzare il comando ibm_boto3 library.

In tools.py il COS_ENDPOINT , COS_INSTANCE_CRN , BUCKET_NAME e CSV_FILE_NAME deve essere compilato con le informazioni corrette utilizzando i dettagli del bucket che si trovano nella tua istanza di Cloud Object Storage nella scheda Configuration. 

Il nostro agente sarà in grado di leggere e scrivere i dati nel file. Per prima cosa, creiamo insieme lo strumento per leggere i dati utilizzando il LangChain@tool decorator. 

Abbiamo aggiunto questo strumentofind_tickets altools.py file. Questo strumento recupera l'oggetto dati da Cloud Object Storage e lo restituisce come dataframe Pandas. In caso contrario, viene generata un'eccezione. 

Successivamente abbiamo aggiunto lo strumento create_ticket . 

Questo strumento prende in considerazione come argomenti la descrizione del problema da parte dell'utente e l'urgenza del problema. Una nuova riga viene aggiunta al nostro file in COS con queste informazioni, quindi viene creato un nuovo ticket. In caso contrario, viene generata un'eccezione. 

Un ultimo strumento che dobbiamo aggiungere al nostro tools.py il file è lo strumento get_todays_date che utilizza il modulo datetime per restituire la data di oggi nel formato MM-DD-YYYY. Questo strumento sarà utile per accedere alla data corrente, che l'agente non ha altro modo di recuperare perché l'LLM non è stato addestrato su questi dati. 

Per garantire al nostro agente l'accesso a questi strumenti, li abbiamo aggiunti alla lista TOOLS nel file init.py del modulo . Questo elenco dovrebbe corrispondere ai contenuti del tuo modulo file nella directory src/langgraph_react_agent .

Questi strumenti vengono importati file agent.py e vengono passati alla funzione predefinita LangGraph create_react_agent che funge da esecutore dell'agente. Altri parametri includono il modello linguistico di grandi dimensioni inizializzato utilizzando la classe ChatWatsonx che consente di eseguire il tool calling su watsonx.ai, il memory saver e il prompt di sistema. Nota: alcuni prompt si comporteranno meglio di altri e quindi potrebbe essere richiesto un certo livello di prompt engineering a seconda dell'LLM scelto. 

Prima di distribuire il tuo agente, ricordati di completare tutte le informazioni necessarie nel file config.toml . 

Ci sono tre modi per chattare con il tuo agente.

Opzione 1. Interroga l'agente a livello locale

Esegui lo script per l'esecuzione del servizio di AI locale.

Opzione 2. Implementare l'agente sull'interfaccia di chat integrata in watsonx.ai

L'opzione finale consiste nell'accedere all'agente nello spazio di implementazione su watsonx.ai. Per fare questo, seleziona "Deployments" nel menu a sinistra. Quindi, seleziona il tuo spazio di implementazione, seleziona la scheda "Assets", seleziona il tuo assetonline ai_service e seleziona ancora una volta l'asset con il tag "wx-agent", quindi apri la scheda "Preview". Ora può chattare con l'agente nell'interfaccia di chat interattiva. Ognuna di queste tre opzioni dovrebbe produrre un output simile.

Opzione 3. Implementa e chatta con l'agente nel tuo IDE

Per eseguire lo script di implementazione, inizializza la variabile deployment_id  nel query_existing_deployment.py .zip

Il deployment_id della tua implementazione può essere ottenuto eseguendo il file script/deploy.py

Esegui quindi lo script di implementazione. 

Esegui ora lo script per interrogare l'implementazione.

Ai fini di questo tutorial, scegliamo l'opzione 2 e interroghiamo il nostro agente distribuito su watsonx.ai sotto forma di chatbot agentico. Forniamo all'agente alcuni prompt che richiederebbero l'uso di strumenti. Dopo avere seguito i passaggi elencati nell'opzione 3, dovresti vedere un'interfaccia di chat su watsonx.ai. Lì possiamo digitare il nostro prompt. 

Innanzitutto, verifichiamo se lo strumento create_ticket verrà richiamato correttamente. Chiediamo all'agente di creare un nuovo ticket.

Come si può vedere nella risposta finale dell'agente, il sistema AI ha utilizzato con successo la risoluzione dei problemi per creare un nuovo ticket con lo strumento create_ticket . Avere la visibilità nel tool calling è utile ai fini del debug. Ora controlliamo se il ticket è stato aggiunto con successo al nostro file di dati che funge da knowledge base dell'agente. 

Fantastico! L'agente ha aggiunto correttamente il ticket al file.

In questo tutorial, hai creato un agente con il framework ReAct che utilizza il processo decisionale per risolvere attività complesse come il recupero e la creazione di richieste di assistenza. Esistono diversi modelli AI che consentono la chiamata di strumenti agentici come Gemini di Google, Granite di IBM e GPT-4 di OpenAI. Nel nostro progetto, abbiamo utilizzato un modello AI IBM Granite tramite l'API watsonx.ai. Il modello si è comportato come previsto sia a livello locale che quando è stato implementato su watsonx.ai. Come prossimo passo, controlla i modelli LlamaIndex e crewAI multiagente, disponibili nel repository watsonx-developer-hub GitHub per la creazione di agenti AI.