Autore: Priya Sharma – Architetto API e Consulente per l’Integrazione dell’AI
La capacità di creare sistemi intelligenti in grado di comprendere istruzioni, ragionare e agire autonomamente sta trasformando il nostro modo di interagire con la tecnologia. Al centro di questa trasformazione ci sono gli agenti AI – entità software progettate per svolgere compiti utilizzando il potere dei Modelli di Linguaggio di Grandi Dimensioni (LLM) e strumenti esterni. Sebbene il concetto possa sembrare complesso, framework come LangChain hanno semplificato notevolmente il processo di sviluppo, rendendo la creazione di agenti accessibile a un pubblico più vasto.
Come architetto API e consulente per l’integrazione dell’AI, ho visto da vicino il potenziale incredibile degli agenti AI ben progettati. Possono automatizzare flussi di lavoro complessi, fornire assistenza personalizzata e sbloccare nuove capacità per aziende e singoli. Questa guida pratica ti condurrà attraverso il processo di costruzione di agenti AI solidi utilizzando l’API di LangChain, dalla comprensione dei componenti fondamentali all’implementazione di esempi pratici e nel mondo reale. Alla fine, avrai una base solida per progettare e distribuire i tuoi agenti intelligenti, pronti ad affrontare una moltitudine di sfide.
Comprendere gli Agenti AI e il Ruolo di LangChain
Prima di esplorare il codice, chiariremo cos’è un agente AI e perché LangChain è uno strumento indispensabile per la loro costruzione. Un agente AI è un sistema che utilizza un LLM come “cervello” per decidere quali azioni intraprendere. A differenza di una semplice chiamata a un LLM che genera una singola 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.
- Apprendere (opzionale ma potente): Incorporare feedback per migliorare le prestazioni future.
LangChain fornisce la struttura necessaria per costruire questi agenti sofisticati. Offre un modo strutturato per connettere gli LLM con varie fonti di dati e strumenti computazionali, permettendo loro di andare oltre la semplice generazione di testo. Considera LangChain come il sistema operativo per il tuo agente AI, 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, lavorerai principalmente con questi componenti fondamentali:
- Modello di Linguaggio di Grandi Dimensioni (LLM): Il nucleo dell’intelligenza. Questo potrebbe essere i modelli GPT di OpenAI, Claude di Anthropic o alternative open-source. L’LLM elabora input, ragiona e fornisce decisioni.
- Strumenti: Funzioni che l’agente può chiamare per interagire con sistemi esterni o eseguire calcoli specifici. Esempi includono cercare sul web, interrogare un database, chiamare una calcolatrice o interagire con un’API personalizzata.
- Toolkit: Collezioni di strumenti correlati progettati per casi d’uso specifici (ad es., un “toolkit di Wikipedia” o un “toolkit per agenti CSV”).
- Esecutore dell’Agente: Il runtime che orchestra le azioni dell’agente. Prende le decisioni dell’LLM, esegue gli strumenti scelti e restituisce i risultati all’LLM per ulteriori ragionamenti.
- Memoria: Consente all’agente di mantenere informazioni da interazioni precedenti, abilitando conversazioni coerenti a più turni e decisioni contestualmente consapevoli.
- Modelli di Prompt: Definiscono come l’input dell’utente e altre informazioni sono formattati per l’LLM, guidando il suo processo di ragionamento.
Impostare il Tuo Ambiente e Primi Passi
Prima di scrivere qualsiasi codice di agente, assicurati che il tuo ambiente Python sia pronto. Avrai bisogno di Python 3.8+ e della libreria LangChain, insieme a qualsiasi fornitore di LLM che intendi utilizzare.
Installazione
Installa LangChain e un fornitore di LLM (ad es., OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Per gestire le chiavi API in modo sicuroGestisci in modo sicuro le tue chiavi API. Crea un file .env nella radice del tuo progetto:
OPENAI_API_KEY="your_openai_api_key_here"Quindi, 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 LLM
Per confermare la tua configurazione, facciamo una semplice chiamata a LLM:
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
llm = ChatOpenAI(model="gpt-4o", temperature=0) # Utilizzando un modello potente con output deterministico
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 sta funzionando. Ora, abilitiamo il nostro LLM con gli strumenti.
Crea Strumenti per il Tuo Agente AI
Gli strumenti sono le mani e i piedi dell’agente, consentendogli di interagire con il mondo esterno. LangChain rende la definizione degli strumenti semplice. Ogni strumento dovrebbe avere un nome chiaro, una descrizione e una funzione che esegue l’azione.
Esempio: Uno Strumento Calcolatore Semplice
Creiamo uno strumento che possa eseguire operazioni aritmetiche di base. Sebbene gli LLM possano fare semplici calcoli, 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 dovrebbe 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 nella valutazione dell'espressione: {e}"
# Puoi testare direttamente lo strumento
print(calculator.invoke("10 * 5 + 3"))Nota il decoratore @tool. Questo converte automaticamente la tua funzione in uno strumento LangChain. La docstring è cruciale in quanto funge da descrizione dello strumento, che l’LLM utilizza per capire 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 casi d’uso RAG (Generazione Aumentata da Recupero) e agenti.
Innanzitutto, installa Tavily e imposta la tua chiave API nel tuo file .env:
pip install tavily-pythonTAVILY_API_KEY="your_tavily_api_key_here"Quindi, caricala:
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) # Ottieni i primi 3 risultati
# Puoi anche personalizzare il nome e la descrizione se necessario
# search.name = "web_search"
# search.description = "Cerca sul web informazioni."
# Testa lo strumento di ricerca
print(search.invoke("tutorial agente LangChain"))Definendo questi strumenti, stiamo dando al nostro agente le capacità necessarie per estendere la propria conoscenza oltre i dati di addestramento e svolgere calcoli accurati.
Costruire il Tuo Primo Agente LangChain
Con il nostro LLM e gli strumenti pronti, possiamo ora assemblare il nostro primo agente LangChain. Utilizzeremo il metodo “create_openai_functions_agent”, che è un modo conveniente per costruire agenti che utilizzano le capacità di chiamata delle funzioni di OpenAI.
Passi per la Costruzione dell’Agente
- Definisci il tuo LLM: Il cervello del tuo agente.
- Definisci i tuoi Strumenti: Le capacità in possesso del tuo agente.
- Crea un Modello di Prompt: Guida l’LLM su come comportarsi.
- Crea l’Agente: Combina LLM, strumenti e prompt.
- Crea l’Esecutore dell’Agente: Il runtime 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 ambientali
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# 1. Definisci LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0)
# 2. Definisci 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 nella valutazione dell'espressione: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Cerca sul web informazioni attuali su una determinata query."
tools = [calculator, search]
# 3. Crea 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. Crea l'Agente
agent = create_openai_functions_agent(llm, tools, prompt)
# 5. Crea l'Esecutore dell'Agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# Esegui l'agente
# print("--- Esecuzione Agente 1 (Calcolo Semplice) ---")
# result1 = agent_executor.invoke({"input": "Qual è 12345 * 6789?", "chat_history": []})
# print(result1["output"])
# print("\n--- Esecuzione 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 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, vedrai il processo di pensiero dell’agente: quali strumenti considera, quali seleziona, l’input che fornisce allo strumento e l’output dello strumento. Questo è estremamente utile per il debug e per comprendere come ragiona il tuo agente.
Comprendere il Modello di Prompt
system: Imposta la personalità generale e le istruzioni per l’agente.MessagesPlaceholder(variable_name="chat_history"): Qui verranno inseriti i turni di conversazione precedenti, abilitando la memoria.human: L’input attuale dell’utente.MessagesPlaceholder(variable_name="agent_scratchpad"): Qui vengono memorizzati il processo di pensiero interno 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 veramente intelligente ha bisogno di memoria per mantenere il contesto attraverso più turni di una conversazione. LangChain fornisce vari tipi di memoria, consentendo al tuo agente di ricordare interazioni passate.
Perché la Memoria è Importante
- Coerenza: Gli agenti possono fare riferimento a dichiarazioni e domande precedenti.
- Personalizzazione: Gli agenti possono ricordare le preferenze degli utenti o le interazioni passate.
- Efficienza: Evita la ripetizione di informazioni o di chiedere chiarimenti su dettagli già forniti.
Implementare ConversationBufferMemory
ConversationBufferMemory è un tipo di memoria semplice ma efficace che memorizza direttamente tutti i messaggi precedenti.
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 # Importa la memoria
# Carica le variabili ambientali
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 (stessi di 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 nella valutazione dell'espressione: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Cerca sul web informazioni attuali su una determinata query."
tools = [calculator, search]
# Crea un Modello di Prompt (nota il segnaposto `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 verrà iniettata la memoria
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# Inizializza la memoria
memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
# Crea l'Agente
agent = create_openai_functions_agent(llm, tools, prompt)
# Crea l'Esecutore dell'Agente, passando la memoria
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, memory=memory)
# Esegui l'agente con memoria
print("--- Esecuzione 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 riguardo alla popolazione della capitale della Francia?")
result3 = agent_executor.invoke({"input": "E riguardo alla 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 necessità di ripetere esplicitamente il paese. Il memory_key="chat_history" assicura che il contenuto della memoria venga mappato correttamente al MessagesPlaceholder(variable_name="chat_history") nel nostro prompt.
Altri Tipi di Memoria
Articoli Correlati
- Comprendere a fondo i modelli di design API efficaci
- API di streaming per agenti AI
- Qdrant vs FAISS: quale per le startup
🕒 Published: