Autore: Priya Sharma – Architetto API e Consulente per l’Integrazione dell’IA
La capacità di creare sistemi intelligenti in grado di comprendere istruzioni, ragionare e agire in modo autonomo trasforma la nostra interazione con la tecnologia. Al cuore di questa trasformazione ci sono gli agenti IA – entità software progettate per eseguire compiti utilizzando la potenza dei Large Language Models (LLMs) e strumenti esterni. Anche se il concetto può sembrare complesso, framework come LangChain hanno notevolmente semplificato il processo di sviluppo, rendendo la creazione di agenti accessibile a un pubblico più ampio.
In qualità di architetto API e consulente per l’integrazione dell’IA, ho visto con i miei occhi l’incredibile potenziale degli agenti IA ben progettati. Possono automatizzare flussi di lavoro complessi, fornire assistenza personalizzata e sbloccare nuove capacità per aziende e privati. Questa guida pratica vi guiderà attraverso il processo di costruzione di agenti IA solidi utilizzando l’API LangChain, dalla comprensione dei componenti principali all’implementazione di esempi pratici e concreti. Alla fine, avrete una base solida per progettare e distribuire i vostri agenti intelligenti, pronti ad affrontare una moltitudine di sfide.
Comprendere gli Agenti IA e il Ruolo di LangChain
Prima di esplorare il codice, chiarifichiamo cosa sia un agente IA e perché LangChain sia uno strumento indispensabile per la loro costruzione. Un agente IA è un sistema che utilizza un LLM come il suo “cervello” per decidere quali azioni intraprendere. A differenza di una semplice chiamata LLM che genera una sola risposta, un agente può impegnarsi in un processo di ragionamento a più fasi:
- Percepire: Comprendere l’input dell’utente o lo stato attuale.
- Ragionare: Determinare il miglior corso d’azione in base alla propria comprensione e agli strumenti disponibili.
- Agire: Eseguire una o più azioni utilizzando strumenti esterni.
- Imparare (facoltativo ma potente): Incorporare feedback per migliorare le prestazioni future.
LangChain fornisce il framework necessario per costruire questi agenti sofisticati. Offre un metodo strutturato per collegare i LLM a varie fonti di dati e strumenti informatici, permettendo loro di andare oltre la semplice generazione di testo. Pensate a LangChain come al sistema operativo del vostro agente IA, fornendo il framework per la sua intelligenza, memoria e capacità di interagire con il mondo.
Componenti Chiave di un Agente LangChain
Per costruire un agente con LangChain, lavorerete principalmente con questi componenti essenziali:
- Large Language Model (LLM): Il nucleo dell’intelligenza. Questo potrebbe essere i modelli GPT di OpenAI, Claude di Anthropic, o alternative open-source. Il LLM elabora gli input, ragiona e produce decisioni.
- Strumenti: Funzioni che l’agente può chiamare per interagire con sistemi esterni o eseguire calcoli specifici. Gli esempi includono la ricerca su Internet, l’interrogazione di un database, la chiamata di una calcolatrice o l’interazione con un’API personalizzata.
- Kit di strumenti: Collezioni di strumenti correlati progettati per casi d’uso specifici (es: un “kit di strumenti Wikipedia” o un “kit di strumenti agente CSV”).
- Esecutore dell’Agente: L’ambiente di esecuzione che orchestra le azioni dell’agente. Prende le decisioni del LLM, esegue gli strumenti scelti e restituisce i risultati al LLM per un ragionamento successivo.
- Memoria: Permette all’agente di conservare informazioni dalle interazioni precedenti, consentendo conversazioni coerenti a più turni e una presa di decisione contestuale.
- Modelli di Invito: Definiscono come l’input dell’utente e altre informazioni sono formattate per il LLM, guidando il suo processo di ragionamento.
Configurare il Vostro Ambiente e Primi Passi
Prima di scrivere il codice dell’agente, assicuratevi che il vostro ambiente Python sia pronto. Avrete bisogno di Python 3.8+ e della libreria LangChain, oltre a qualsiasi fornitore di LLM che intendete utilizzare.
Installazione
Installate LangChain e un fornitore di LLM (es: OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Per gestire le chiavi API in sicurezzaGestite le vostre chiavi API in sicurezza. Create un file .env nella radice del vostro progetto:
OPENAI_API_KEY="your_openai_api_key_here"Successivamente, caricatelo nel vostro script Python:
import os
from dotenv import load_dotenv
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")Interazione di Base con il LLM
Per confermare la vostra configurazione, facciamo una semplice chiamata al LLM:
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
llm = ChatOpenAI(model="gpt-4o", temperature=0) # Utilizzando un modello potente con un'uscita deterministica
messages = [
HumanMessage(content="Qual è la capitale della Francia?")
]
response = llm.invoke(messages)
print(response.content)Questa interazione di base conferma che la vostra connessione LLM funziona. Ora, equipaggiamo il nostro LLM con strumenti.
Creare Strumenti per il Vostro Agente IA
Gli strumenti sono le mani e i piedi dell’agente, consentendogli di interagire con il mondo esterno. LangChain rende semplice la definizione degli strumenti. Ogni strumento deve avere un nome chiaro, una descrizione e una funzione che esegue l’azione.
Esempio: Uno Strumento Calcolatrice Semplice
Creiamo uno strumento che possa eseguire aritmetica di base. Sebbene i LLM possano fare matematica semplice, gli strumenti esterni sono più affidabili per calcoli complessi.
from langchain.tools import tool
@tool
def calculator(expression: str) -> str:
"""Valuta un'espressione matematica e restituisce il risultato.
L'input deve essere una stringa contenente un'espressione matematica valida, es. '2 + 2' o '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Errore durante la valutazione dell'espressione: {e}"
# Potete testare lo strumento direttamente
print(calculator.invoke("10 * 5 + 3"))Notate il decoratore @tool. Questo converte automaticamente la vostra funzione in uno strumento LangChain. La docstring è cruciale poiché funge da descrizione dello strumento, che il LLM utilizza per capire quando e come usarlo.
Esempio: Uno Strumento di Ricerca Web (Utilizzando Tavily)
La maggior parte degli agenti potenti ha bisogno di accesso a informazioni aggiornate. Uno strumento di ricerca web è fondamentale. Utilizzeremo Tavily, un’API di ricerca specificamente progettata per RAG (Retrieval Augmented Generation) e i casi d’uso degli agenti.
Prima di tutto, installate Tavily e configurate la vostra chiave API nel vostro file .env:
pip install tavily-pythonTAVILY_API_KEY="your_tavily_api_key_here"In seguito, caricatelo:
import os
from dotenv import load_dotenv
from langchain_community.tools.tavily_search import TavilySearchResults
load_dotenv()
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# Create the Tavily search tool
search = TavilySearchResults(max_results=3) # Ottenere i 3 migliori risultati
# Potete anche personalizzare il nome e la descrizione se necessario
# search.name = "web_search"
# search.description = "Ricerca sul web per informazioni."
# Testate lo strumento di ricerca
print(search.invoke("tutorial su l'agente LangChain"))Definendo questi strumenti, diamo al nostro agente le capacità necessarie per estendere le sue conoscenze oltre i suoi dati di addestramento ed eseguire calcoli con precisione.
Costruire il Vostro Primo Agente LangChain
Con il nostro LLM e i nostri strumenti pronti, ora possiamo assemblare il nostro primo agente LangChain. Utilizzeremo il metodo “create_openai_functions_agent”, che è un modo pratico per costruire agenti utilizzando le capacità di chiamata di funzione di OpenAI.
Fasi di Costruzione dell’Agente
- Definite il vostro LLM: Il cervello del vostro agente.
- Definite i vostri Strumenti: Le capacità che possiede il vostro agente.
- Creare un Modello di Invito: Guidare il LLM sul suo comportamento.
- Creare l’Agente: Combinare LLM, strumenti e invito.
- Creare l’Esecutore dell’Agente: L’ambiente di esecuzione che esegue le decisioni dell’agente.
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
# Carica le variabili d'ambiente
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# 1. Definire LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0)
# 2. Definire gli strumenti
@tool
def calculator(expression: str) -> str:
"""Valuta un'espressione matematica e restituisce il risultato.
L'input deve essere una stringa contenente un'espressione matematica valida, ad es., '2 + 2' o '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Errore durante la valutazione dell'espressione: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Cerca su web informazioni attuali su una richiesta data."
tools = [calculator, search]
# 3. Creare un modello di prompt
prompt = ChatPromptTemplate.from_messages(
[
("system", "Sei un assistente AI utile. Rispondi alle domande nel modo più preciso possibile."),
MessagesPlaceholder(variable_name="chat_history"),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# 4. Creare l'agente
agent = create_openai_functions_agent(llm, tools, prompt)
# 5. Creare l'esecutore dell'agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# Eseguire l'agente
# print("--- Esecuzione dell'agente 1 (Calcolo semplice) ---")
# result1 = agent_executor.invoke({"input": "Qual è 12345 * 6789 ?", "chat_history": []})
# print(result1["output"])
# print("\n--- Esecuzione dell'agente 2 (Ricerca web) ---")
# result2 = agent_executor.invoke({"input": "Qual è la capitale del Portogallo e qual è la sua popolazione attuale ?", "chat_history": []})
# print(result2["output"])
# print("\n--- Esecuzione dell'agente 3 (Combinato) ---")
# result3 = agent_executor.invoke({"input": "Qual è la radice quadrata di 81 e chi ha inventato il World Wide Web ?", "chat_history": []})
# print(result3["output"])Quando si imposta verbose=True nell’AgentExecutor, puoi osservare il processo di riflessione dell’agente: quali strumenti considera, quale seleziona, l’input che fornisce allo strumento e l’output dello strumento. Questo è estremamente utile per il debugging e per comprendere come il tuo agente ragiona.
Comprendere il modello di prompt
system: Definisce la personalità generale e le istruzioni per l’agente.MessagesPlaceholder(variable_name="chat_history"): Qui saranno inseriti i turni di conversazione precedenti, permettendo la memoria.human: L’input attuale dell’utente.MessagesPlaceholder(variable_name="agent_scratchpad"): Qui viene memorizzato il processo di riflessione interno dell’agente e le uscite degli strumenti durante una singola invocazione, consentendo al LLM di ragionare passo dopo passo.
Aggiungere memoria e stato al tuo agente AI
Un agente veramente intelligente necessita di memoria per mantenere il contesto durante diversi turni di conversazione. LangChain offre vari tipi di memoria, consentendo al tuo agente di ricordare le interazioni passate.
Perché la memoria è importante
- Cohesione: Gli agenti possono fare riferimento a dichiarazioni e domande precedenti.
- Personalizzazione: Gli agenti possono ricordare le preferenze dell’utente o le interazioni passate.
- Efficienza: Evita di ripetere informazioni o di richiedere chiarimenti su dettagli già forniti.
Implementazione di ConversationBufferMemory
ConversationBufferMemory è un tipo di memoria semplice ma efficace che memorizza tutti i messaggi precedenti direttamente.
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.memory import ConversationBufferMemory # Importare la memoria
# Carica le variabili d'ambiente
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# LLM e strumenti (identici a prima)
llm = ChatOpenAI(model="gpt-4o", temperature=0)
@tool
def calculator(expression: str) -> str:
"""Valuta un'espressione matematica e restituisce il risultato.
L'input deve essere una stringa contenente un'espressione matematica valida, ad es., '2 + 2' o '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Errore durante la valutazione dell'espressione: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Cerca su web informazioni attuali su una richiesta data."
tools = [calculator, search]
# Creare un modello di prompt (nota lo spazio riservato `chat_history`)
prompt = ChatPromptTemplate.from_messages(
[
("system", "Sei un assistente AI utile. Ricorda le interazioni precedenti e rispondi alle domande nel modo più preciso possibile."),
MessagesPlaceholder(variable_name="chat_history"), # Qui sarà iniettata la memoria
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# Inizializzare la memoria
memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
# Creare l'agente
agent = create_openai_functions_agent(llm, tools, prompt)
# Creare l'esecutore dell'agente, passando la memoria
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, memory=memory)
# Eseguire l'agente con memoria
print("--- Esecuzione dell'agente con memoria ---")
print("\nUtente: Qual è la capitale della Spagna?")
result1 = agent_executor.invoke({"input": "Qual è la capitale della Spagna?"})
print("Agente:", result1["output"])
print("\nUtente: Qual è la sua popolazione?")
result2 = agent_executor.invoke({"input": "Qual è la sua popolazione?"})
print("Agente:", result2["output"])
print("\nUtente: E qual è la popolazione della capitale della Francia?")
result3 = agent_executor.invoke({"input": "E qual è la popolazione della capitale della Francia?"})
print("Agente:", result3["output"])In questo esempio, l’agente ricorda « Spagna » dal primo turno, e « capitale della Francia » dal terzo, consentendogli di fornire risposte pertinenti senza dover riformulare esplicitamente il paese. Il memory_key="chat_history" garantisce che il contenuto della memoria sia correttamente mappato al MessagesPlaceholder(variable_name="chat_history") nel nostro modello di prompt.
Altri tipi di memoria
Articoli correlati
- Alla scoperta dei modelli di progettazione API efficaci
- API di streaming per agenti AI
- Qdrant vs FAISS: Quale scegliere per le startup
🕒 Published: