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 il nostro modo di interagire con la tecnologia. Al cuore di questa trasformazione ci sono gli agenti IA – entità software progettate per svolgere compiti utilizzando la potenza dei Large Language Models (LLMs) e strumenti esterni. Sebbene il concetto possa apparire complesso, framework come LangChain hanno notevolmente semplificato il processo di sviluppo, rendendo la creazione di agenti accessibile a un pubblico più vasto.
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 le aziende e gli individui. Questa guida pratica ti accompagnerà attraverso il processo di costruzione di agenti IA solidi usando l’API LangChain, dalla comprensione dei componenti principali all’implementazione di esempi pratici e concreti. Alla fine, avrai una base solida per progettare e distribuire i tuoi agenti intelligenti, pronti ad affrontare una molteplicità 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 imprescindibile per la loro costruzione. Un agente IA è un sistema che utilizza un LLM come “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 in 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 connettere i LLM a diverse fonti di dati e strumenti informatici, consentendo loro di andare oltre la semplice generazione di testo. Pensa a LangChain come al sistema operativo del tuo agente IA, fornendo la struttura per la sua intelligenza, la sua memoria e la sua capacità di interagire con il mondo.
Componenti Chiave di un Agente LangChain
Per costruire un agente con LangChain, lavorerai principalmente con questi componenti essenziali:
- Large Language Model (LLM): Il nucleo dell’intelligenza. Potrebbe trattarsi dei 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 a 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 coordina le azioni dell’agente. Prende le decisioni dal LLM, esegue gli strumenti scelti e restituisce i risultati al LLM per un ragionamento successivo.
- Memoria: Consente all’agente di mantenere informazioni delle interazioni precedenti, permettendo conversazioni coerenti in 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 Tuo Ambiente e Primi Passi
Prima di scrivere il codice dell’agente, assicurati che il tuo ambiente Python sia pronto. Avrai bisogno di Python 3.8+ e della libreria LangChain, oltre a qualsiasi fornitore di LLM che intendi utilizzare.
Installazione
Installa LangChain e un fornitore di LLM (es: OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Per gestire le chiavi API in modo sicuroGestisci le tue chiavi API in sicurezza. Crea un file .env nella radice del tuo progetto:
OPENAI_API_KEY="your_openai_api_key_here"Successivamente, caricalo nel tuo 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 tua 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 tua connessione LLM funziona. Ora, equipaggiamo il nostro LLM con strumenti.
Creare Strumenti per il Tuo Agente IA
Gli strumenti sono le mani e i piedi dell’agente, permettendo di interagire con il mondo esterno. LangChain rende la definizione degli strumenti semplice. 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 può eseguire aritmetiche di base. Anche se i LLM possono fare semplici operazioni matematiche, 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'ingresso 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}"
# Puoi testare lo strumento direttamente
print(calculator.invoke("10 * 5 + 3"))Notare il decoratore @tool. Questo converte automaticamente la tua funzione in uno strumento LangChain. La docstring è cruciale in quanto serve come descrizione dello strumento, che il LLM utilizza per comprendere quando e come utilizzarlo.
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.
Per prima cosa, installa Tavily e configura la tua chiave API nel tuo file .env:
pip install tavily-pythonTAVILY_API_KEY="your_tavily_api_key_here"Quindi, caricalo:
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")
# Crea lo strumento di ricerca Tavily
search = TavilySearchResults(max_results=3) # Ottenere i 3 migliori risultati
# Puoi anche personalizzare il nome e la descrizione se necessario
# search.name = "web_search"
# search.description = "Ricerca sul web per informazioni."
# Testa lo strumento di ricerca
print(search.invoke("tutorial sull'agente LangChain"))Definendo questi strumenti, diamo al nostro agente le capacità necessarie per estendere le sue conoscenze oltre i suoi dati di addestramento e per eseguire calcoli con precisione.
Costruire il Tuo Primo Agente LangChain
Con il nostro LLM e i nostri strumenti pronti, possiamo ora 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 a funzione di OpenAI.
Passaggi per la Costruzione dell’Agente
- Definisci il tuo LLM: Il cervello del tuo agente.
- Definisci i tuoi Strumenti: Le capacità che possiede il tuo agente.
- Crea un Modello di Invito: Guida il LLM sul suo comportamento.
- Crea l’Agente: Combina LLM, strumenti e invito.
- Crea 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
# Caricare 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 esempio, '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 = "Ricerca sul web di informazioni attuali su una determinata query."
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)
# Esegui 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 imposti verbose=True nell’AgentExecutor, puoi vedere il processo di riflessione dell’agente: quali strumenti considera, quale seleziona, l’input che fornisce allo strumento e l’output dello strumento. È estremamente utile per il debug e per comprendere come ragiona il tuo agente.
Comprendere il modello di prompt
system: Definisce la personalità generale e le istruzioni per l’agente.MessagesPlaceholder(variable_name="chat_history"): Qui vengono inseriti i turni di conversazione precedenti, consentendo la memoria.human: L’input attuale dell’utente.MessagesPlaceholder(variable_name="agent_scratchpad"): Qui viene memorizzato il processo di riflessione interna dell’agente e gli output degli strumenti durante una singola invocazione, consentendo al LLM di ragionare passo dopo passo.
Aggiungere memoria e stato al tuo agente AI
Un agente realmente intelligente ha bisogno di memoria per mantenere il contesto durante più turni di conversazione. LangChain offre diversi tipi di memoria, consentendo al tuo agente di ricordare le interazioni passate.
Perché la memoria è importante
- Coherenza: Gli agenti possono riferirsi 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 chiedere 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
# Caricare 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 esempio, '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 = "Ricerca sul web di informazioni attuali su una determinata query."
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, permettendogli 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
- Al cuore dei modelli di progettazione API efficaci
- API di streaming per agenti AI
- Qdrant vs FAISS: Quale per le startup
🕒 Published: