In questo tutorial, utilizzeremo gli strumenti LangChain precostituiti per un agente ReAct agentico per dimostrare la sua capacità di distinguere i casi d'uso appropriati per ogni strumento. Utilizzeremo principalmente il pacchetto Python LangChain open source.
La chiamata di strumenti, altrimenti nota come chiamata di funzioni, è l'interfaccia che consente agli agenti di intelligenza artificiale (AI) di lavorare su attività specifiche che richiedono informazioni aggiornate, altrimenti non disponibili per i modelli linguistici di grandi dimensioni (LLM) addestrati. Gli LLM come i modelli BM Granite o i modelli GPT (generative pre-training transformer) di OpenAI hanno accesso solo alle informazioni utilizzate nell'addestramento. Esistono molti strumenti predefiniti accessibili tramite LangChain, incluso uno strumento per lavorare con le query del SQL database, accedere alle informazioni su Wikipedia e molto altro. Ti invitiamo a leggere la documentazione di LangChain per un elenco completo degli strumenti precostituiti.
Gli strumenti personalizzati possono essere definiti utilizzando vari metodi, tra cui l'uso di @tool decorator o LangChain Runnables che tratteremo in questo tutorial. Gli strumenti asincroni possono essere creati usando le classi StructuredTool o BaseTool. Per le differenze tra i vari approcci, ti invitiamo a fare riferimento alla documentazione ufficiale di LangChain. Fai riferimento al tutorial sulla chiamata di funzioni IBM per degli esempi di strumenti personalizzati.
Ti invitiamo a consultare la nostra articolo esplicativo sugli agenti AI per una panoramica approfondita dei vari tipi di agenti AI e delle differenze tra questi ultimi e i chatbot LLM tradizionali.
Ti serve un account IBM Cloud.
Passaggio 1. Configura il tuo ambiente
Sebbene sia possibile scegliere tra diversi strumenti, questo tutorial illustra come configurare un account IBM per l'utilizzo di un Jupyter Notebook.
Accedi a watsonx.ai usando il tuo account IBM Cloud.
Crea un progetto watsonx.ai.
Puoi ottenere l'ID del tuo progetto dall'interno del tuo progetto. Clicca sulla scheda Gestisci. Quindi, copia l'ID del progetto dalla sezione Dettagli della pagina Generali. Per questo tutorial ti serve questo ID.
Creare un Jupyter Notebook.
Questo passaggio aprirà un ambiente Jupyter Notebook in cui puoi copiare il codice ottenuto con questo tutorial. In alternativa, puoi scaricare questo notebook sul tuo sistema locale e caricarlo nel tuo progetto watsonx.ai come asset. Per visualizzare altri tutorial su Granite, visita l'IBM Granite Community. Questo tutorial è disponibile anche su Github.
Passaggio 2. Configura un'istanza di watsonx.ai Runtime e una chiave API
Crea un'istanza di servizio watsonx.ai Runtime (seleziona l'area geografica appropriata e scegli il piano Lite, che è un'istanza gratuita).
Genera una chiave API.
Associa l'istanza del servizio watsonx.ai Runtime al progetto che hai creato in watsonx.ai.
Passaggio 3. Installa e importa le librerie pertinenti e configura le tue credenziali
Per questo tutorial abbiamo bisogno di alcune librerie e moduli. Assicurati di importare i seguenti e, se non sono installati, puoi risolvere il problema con una rapida installazione pip. LangChain e LangGraph saranno i framework e i toolkit per sviluppatori utilizzati.
Nota: questo tutorial è stato creato utilizzando Python 3.11.9 ed è anche compatibile con Google Colab che utilizza Python 3.10.12. Per controllare la tua versione di Python, puoi eseguire il comando !python --version in una cella di codice.
!pip install -q langchain \
"langchain_community<0.3.0" \
langgraph \
youtube_search \
pyowm \
ionic-langchain \
python-dotenv
!pip install -qU langchain-ibm
import os
from langchain_ibm import ChatWatsonx
from langgraph.prebuilt import create_react_agent
from langchain_core.tools import Tool
from langchain_core.messages import HumanMessage
from langchain_community.tools import YouTubeSearchTool
from langchain_community.utilities import OpenWeatherMapAPIWrapper
from ionic_langchain.tool import IonicTool
from dotenv import load_dotenv
load_dotenv(os.getcwd()+"/.env", override=True)
Per impostare le nostre credenziali, abbiamo bisogno della WATSONX_APIKEY e della WATSONX_PROJECT_ID che hai generato nel passaggio 1. Puoi memorizzarle in un file .env nella directory oppure sostituire il testo segnaposto. Configureremo anche l'URL che fungerà da endpoint API.
WATSONX_PROJECT_ID = os.getenv('WATSONX_PROJECT_ID', "<WATSONX_PROJECT_ID_HERE>")
URL = "https://us-south.ml.cloud.ibm.com"
Lo strumento meteo utilizzato in questo tutorial richiede una chiave API OpenWeather. Per generarne una, crea un account OpenWeather. Dopo aver creato un account, seleziona la scheda "Chiavi API" per visualizzare la tua chiave gratuita.
Passaggio 4. Inizializza l'LLM
Per questo tutorial, utilizzeremo il wrapper ChatWatsonx per impostare il nostro modello di chat. Questo wrapper semplifica l'integrazione della chiamata e del concatenamento degli strumenti. Utilizzeremo il modello granite-3-8b-instruct. Per ulteriori informazioni, ti invitiamo a utilizzare i riferimenti alle API nella documentazione di ChatWatsonx .
Per inizializzare l'LLM, dobbiamo impostare i parametri del modello. È importante configurare la temperatura del modello in questa fase per limitare le allucinazioni dell'agente.
model_id="ibm/granite-3-8b-instruct",
url = URL,
apikey = WATSONX_APIKEY,
project_id = WATSONX_PROJECT_ID,
params = {
"decoding_method": "greedy",
"temperature": 0,
"min_new_tokens": 5,
"max_new_tokens": 2000
}
)
Passaggio 5. Stabilisci gli strumenti integrati
Possiamo utilizzare la classe Tool per rendere i nostri strumenti richiamabili. Anche una descrizione chiara e semplice dello strumento è importante. Inoltre, l'attributo booleano return_direct determina se la risposta dello strumento deve essere restituita direttamente all'utente. Infine, l'attributo args_schema opzionale del tipo pydantic.BaseModel viene utilizzato per fornire informazioni aggiuntive o la convalida al modello.
Immaginiamo che tu stia pianificando la tua prossima vacanza in Grecia e che voglia avere maggiori informazioni e prepararti per il viaggio. Innanzitutto, impostiamo lo strumento meteo integrato LangChain. Lo strumento utilizza OpenWeatherMapAPIWrapper che utilizza la OPENWEATHERMAP_API_KEY generata in precedenza.
weather_search = Tool(
name="weather_search",
description="Get weather for a city and country code, e.g. Athens, GR",
func=weather.run,
)
Quindi, configuriamo lo strumento YouTube precostituito utilizzando il pacchetto YouTube Search disponibile tramite LangChain. Questo passaggio ti sarà utile per trovare video sulla tua destinazione di viaggio.
youtube_search = Tool(
name="youtube_search",
description="Search YouTube for video links.",
func=youtube.run,
)
Infine, configuriamo uno strumento di shopping online utilizzando Ionic. Questo strumento restituisce gli articoli pertinenti alla query dell'utente che sono in vendita sul marketplace e-commerce.
Definiamo l'elenco dei diversi strumenti che mettiamo a disposizione dell'LLM. Possiamo anche stampare l'elenco per vedere come è stato caricato. Per un elenco completo degli strumenti LangChain disponibili, consulta la documentazione di LangChain.
tools
Output:
[Tool(name='weather_search', description='Get weather for a city and country code, e.g. Athens, GR', func=<bound method OpenWeatherMapAPIWrapper.run of OpenWeatherMapAPIWrapper(owm=<pyowm.owm.OWM - API key=************************611450cc, subscription type=free, PyOWM version=(3, 3, 0)>, openweathermap_api_key='******************')>),
Tool(name='youtube_search', description='Search YouTube for video links.', func=<bound method BaseTool.run of YouTubeSearchTool()>),
Tool(name='ionic_commerce_shopping_tool', description='\nIonic is an e-commerce shopping tool...[abbreviated]', verbose=True, func=<bound method Ionic.query of <ionic_langchain.tool.Ionic object at 0x17f6e5510>>)]
Passaggio 6. Chiamata di strumenti
Il termine chiamata di strumenti si riferisce in genere a un LLM che restituisce il nome dello strumento da chiamare e i relativi argomenti. Possiamo utilizzare le informazioni estratte per altri scopi oppure possiamo chiamare lo strumento con questi argomenti. Per altri esempi, fai riferimento il nostro tutorial sulla chiamata di funzioni.
In realtà, l'esecuzione dello strumento e il recupero del suo output non sono sempre impliciti. In questo tutorial esploreremo entrambi gli approcci.
Restituzione dello strumento e degli argomenti pertinenti
Per eseguire la chiamata di strumenti tradizionale, possiamo semplicemente fornire una query utente e utilizzare il metodo bind_tools precostituito per passare l'elenco degli strumenti all'LLM ad ogni iterazione.
response = llm_with_tools.invoke([("human", "What are some youtube videos about greece")])
response
Output:
AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'chatcmpl-tool-7a15abba7d3c4419970d807ac0c8d353', 'type': 'function', 'function': {'name': 'youtube_search', 'arguments': '{"query": "greece"}'}}]}, response_metadata={'token_usage': {'completion_tokens': 21, 'prompt_tokens': 578, 'total_tokens': 599}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'tool_calls'}, id='chat-5fe7a26b8f954c179c4995e873bff91e', tool_calls=[{'name': 'youtube_search', 'args': {'query': 'greece'}, 'id': 'chatcmpl-tool-7a15abba7d3c4419970d807ac0c8d353', 'type': 'tool_call'}], usage_metadata={'input_tokens': 578, 'output_tokens': 21, 'total_tokens': 599})
Output:
{'tool_calls': [{'id': 'chatcmpl-tool-7a15abba7d3c4419970d807ac0c8d353',
'type': 'function',
'function': {'name': 'youtube_search',
'arguments': '{"query": "greece"}'}}]}
Come si vede nell'output tool_calls, l'LLM identifica correttamente la chiamata dello strumento e gli argomenti appropriati. L'LLM non esegue lo strumento autonomamente. Lo faremo nel passaggio successivo.
Esegui la chiamata dello strumento e recupera l'output
Per eseguire le chiamate di strumenti, dobbiamo prima creare un agente ReAct utilizzando il metodo helper LangGraph create_react_agent precostituito. Questa funzione crea un grafo che funge da ponte tra il modello di chat e gli strumenti disponibili, abilitando così la chiamata degli strumenti agentici. Questo grafo è rappresentato nel diagramma seguente.
Ora possiamo porre all'agente domande che richiedono la chiamata di strumenti. Innanzitutto, possiamo chiedere al modello di restituire gli URL ai video di YouTube sulla Grecia. Possiamo utilizzare la classe HumanMessage per passare la query dell'utente all'LLM.
response = agent_executor.invoke({"messages": user_query})
response["messages"]
Output:
[HumanMessage(content='What are some YouTube videos about Greece', additional_kwargs={}, response_metadata={}, id='1adba6c0-32e6-4bbd-92a6-7d21b0177439'),
AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'chatcmpl-tool-b4b5bf452404424ba4d6d9c26e53c6ce', 'type': 'function', 'function': {'name': 'youtube_search', 'arguments': '{"query": "Greece"}'}}]}, response_metadata={'token_usage': {'completion_tokens': 22, 'prompt_tokens': 578, 'total_tokens': 600}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'tool_calls'}, id='chat-5f41aee6736842749285aa7fbff50f65', tool_calls=[{'name': 'youtube_search', 'args': {'query': 'Greece'}, 'id': 'chatcmpl-tool-b4b5bf452404424ba4d6d9c26e53c6ce', 'type': 'tool_call'}], usage_metadata={'input_tokens': 578, 'output_tokens': 22, 'total_tokens': 600}),
ToolMessage(content="['https://www.youtube.com/watch?v=waQY2Ucpbd0&pp=ygUGR3JlZWNl', 'https://www.youtube.com/watch?v=NMlBB2pK5qo&pp=ygUGR3JlZWNl']", name='youtube_search', id='1ccf3137-2c10-495e-86ad-a548a3434243', tool_call_id='chatcmpl-tool-b4b5bf452404424ba4d6d9c26e53c6ce'),
AIMessage(content='Here are some YouTube videos about Greece:\n\n1. [Greece Travel Guide | Top 10 Tourist Attractions](https://www.youtube.com/watch?v=waQY2Ucpbd0&pp=ygUGR3JlZWNl)\n2. [Greece Travel Guide | Top 10 Tourist Attractions](https://www.youtube.com/watch?v=NMlBB2pK5qo&pp=ygUGR3JlZWNl)', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 117, 'prompt_tokens': 677, 'total_tokens': 794}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'stop'}, id='chat-801e3b596a174ac88246b507c93e5869', usage_metadata={'input_tokens': 677, 'output_tokens': 117, 'total_tokens': 794})]
Ottimo! Come si può osservare nel messaggio AIMessage, il modello ha identificato correttamente lo strumento appropriato da chiamare. Nel ToolMessage, possiamo osservare che il modello ha restituito correttamente l'output utilizzando lo strumento YouTube integrato in LangChain. Infine, AIMessage mostra che l'LLM ha sintetizzato la risposta dello strumento.
Successivamente, chiediamo al modello delle informazioni sul meteo in Grecia per determinare se richiama lo strumento weather_search come previsto.
response = agent_executor.invoke({"messages": user_query})
response["messages"]
Output:
[HumanMessage(content='What is the weather in Athens, GR', additional_kwargs={}, response_metadata={}, id='a0c4b69c-988a-4f7d-9b8a-4780305f8e2a'),
AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'chatcmpl-tool-9a0c07a3b35f4c69a351c5540ab663f8', 'type': 'function', 'function': {'name': 'weather_search', 'arguments': '{"__arg1": "Athens, GR"}'}}]}, response_metadata={'token_usage': {'completion_tokens': 26, 'prompt_tokens': 579, 'total_tokens': 605}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'tool_calls'}, id='chat-eeed087050e049f0ad715f3615c7fdda', tool_calls=[{'name': 'weather_search', 'args': {'__arg1': 'Athens, GR'}, 'id': 'chatcmpl-tool-9a0c07a3b35f4c69a351c5540ab663f8', 'type': 'tool_call'}], usage_metadata={'input_tokens': 579, 'output_tokens': 26, 'total_tokens': 605}),
ToolMessage(content='In Athens, GR, the current weather is as follows:\nDetailed status: few clouds\nWind speed: 4.47 m/s, direction: 23°\nHumidity: 58%\nTemperature: \n - Current: 15.15°C\n - High: 15.74°C\n - Low: 14.1°C\n - Feels like: 14.24°C\nRain: {}\nHeat index: None\nCloud cover: 20%', name='weather_search', id='587b0230-b667-41de-97b9-3779554d2559', tool_call_id='chatcmpl-tool-9a0c07a3b35f4c69a351c5540ab663f8'),
AIMessage(content='The current weather in Athens, GR is:\n- Detailed status: few clouds\n- Wind speed: 4.47 m/s, direction: 23°\n- Humidity: 58%\n- Temperature:\n - Current: 15.15°C\n - High: 15.74°C\n - Low: 14.1°C\n - Feels like: 14.24°C\n- Rain: None\n- Heat index: None\n- Cloud cover: 20%', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 125, 'prompt_tokens': 733, 'total_tokens': 858}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'stop'}, id='chat-6719a5ca266a439bb10ed410db25c5ef', usage_metadata={'input_tokens': 733, 'output_tokens': 125, 'total_tokens': 858})]
Il modello è stato in grado di individuare lo strumento appropriato da chiamare, nonché di eseguire lo strumento con gli argomenti estratti e sintetizzare l'output dello strumento. Ora, chiediamo all'LLM di suggerirci alcune valigie di prezzo inferiore a 100 USD per il tuo viaggio imminente. Nota: lo strumento è progettato per cercare i prezzi in centesimi. Quindi, in questo scenario, chiediamo valigie con prezzo inferiore a 10.000 centesimi, equivalenti a 100 USD.
response = agent_executor.invoke({"messages": user_query})
response["messages"]
Output:
[HumanMessage(content='Find some suitcases for less than 10000', additional_kwargs={}, response_metadata={}, id='8b207035-150a-4390-aff3-8b09ef85a592'),
AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'chatcmpl-tool-b011e718b18e41dcbcae2f7786af263d', 'type': 'function', 'function': {'name': 'ionic_commerce_shopping_tool', 'arguments': '{"__arg1": "suitcases, 10, 0, 10000"}'}}]}, response_metadata={'token_usage': {'completion_tokens': 41, 'prompt_tokens': 582, 'total_tokens': 623}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'tool_calls'}, id='chat-e38c8568d1754636a6a92082561180bd', tool_calls=[{'name': 'ionic_commerce_shopping_tool', 'args': {'__arg1': 'suitcases, 10, 0, 10000'}, 'id': 'chatcmpl-tool-b011e718b18e41dcbcae2f7786af263d', 'type': 'tool_call'}], usage_metadata={'input_tokens': 582, 'output_tokens': 41, 'total_tokens': 623}),
ToolMessage(content='[{"products": [{"links": [{"text": "Details", "type": "pdp", "url": "https://go.ionic.click/Ch4CKd"}], "merchant_name": "Walmart", "merchant_product_id": "811277349", "name": "Zimtown Hardside Lightweight Spinner Orange 3 Piece Luggage Set with TSA Lock", "price": "$69.99", "status": "available", "thumbnail": "https://i5.walmartimages.com/asr/b809a274-ccc7-4ca4-b4f1-e848b4412fe6.314144bcd13e5467a33cb99e8dd5237c.jpeg?odnHeight=100&odnWidth=100&odnBg=ffffff", "brand_name": "Zimtown", "upc": "273109526768"}, {"links": [{"text": "Details", "type": "pdp", "url": "https://www.amazon.com/dp/B071HHX6VF?tag=ioniccommer00-20&linkCode=osi&th=1&psc=1"}], "merchant_name": "Amazon", "merchant_product_id": "B071HHX6VF", "name": "Amazon Basics Expandable Hardside Luggage, Suitcase with Wheels, 30-Inch Spinner with Four Spinner Wheels and Scratch-Resistant Surface, Black", "price": "$74.49", "status": "available", "thumbnail": "https://m.media-amazon.com/images/I/41jJcuMYSdL._SL160_.jpg", "brand_name": "Amazon Basics", "upc": "841710177190"}, .....[abbreviated],
AIMessage(content='Here are some suitcases that are less than 10000:\n\n1. [Zimtown Hardside Lightweight Spinner Orange 3 Piece Luggage Set with TSA Lock](https://go.ionic.click/Ch4CKd) - $69.99\n2. [Amazon Basics Expandable Hardside Luggage, Suitcase with Wheels, 30-Inch Spinner](https://www.amazon.com/dp/B071HHX6VF) - $74.49\n3. [SwissGear Sion Softside Expandable Luggage, Blue, Carry-On 21-Inch](https://www.amazon.com/dp/B01MFBVKDF) - $80.73\n4. [Travelers Club Midtown Hardside Luggage Travel, Rose Gold, 4-Piece Set](https://www.amazon.com/dp/B07RS4PK3J) - $95.19\n5. [American Tourister Stratum 2.0 Expandable Hardside Luggage with Spinner Wheels, 28" SPINNER, Slate Blue](https://www.amazon.com/dp/B0B2X1BDFH) - $89.97\n6. [Wrangler Smart Luggage Set with Cup Holder and USB Port, Navy Blue, 20-Inch Carry-On](https://www.amazon.com/dp/B07SLG6WZ2) - $39.99\n7. [Wrangler Hardside Carry-On Spinner Luggage, Lilac, 20-Inch](https://www.amazon.com/dp/B0C7YWMBGP) - $40.00\n8. [Protege 20 inch Hard Side Carry-On Spinner Luggage, Black Matte Finish (Walmart.com Exclusive)](https://go.ionic.click/qJqBRA) - $29.87\n9. [Wrangler Wesley Rolling Duffel Bag, Tannin, Large 30-Inch](https://www.amazon.com/dp/B07XKWMLJ5) - $44.00\n10. [U.S. Traveler Boren Polycarbonate Hardside Rugged Travel Suitcase Luggage with 8 Spinner Wheels, Aluminum Handle, Lavender, Checked-Large 30-Inch](https://www.amazon.com/dp/B085B4D852) - $79.99', additional_kwargs={}, response_metadata={'token_usage': {'completion_tokens': 612, 'prompt_tokens': 2794, 'total_tokens': 3406}, 'model_name': 'ibm/granite-3-8b-instruct', 'system_fingerprint': '', 'finish_reason': 'stop'}, id='chat-d08201ff6ef84c428e7ae44372396926', usage_metadata={'input_tokens': 2794, 'output_tokens': 612, 'total_tokens': 3406})]
Come vede dalla risposta dell'LLM, il modello ha utilizzato correttamente lo strumento di shopping per restituire diverse valigie che si possono acquistare online a meno di 100 USD.
In questo tutorial, hai utilizzato gli strumenti LangChain precostituiti per creare un agente ReAct in Python con watsonx utilizzando il modello granite-3-8b-instruct . Hai usato gli strumenti youtube_search , weather_search e ionic_search . Il tutorial ha illustrato come implementare la chiamata di strumenti tradizionale e un approccio che esegue gli strumenti. L'output di esempio è importante in quanto mostra i passaggi compiuti dall'agente per creare il suo workflow agentico utilizzando le funzioni disponibili. Gli strumenti concessi all'agente erano fondamentali per rispondere alle query dell'utente.
Risorse
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.