Autore: Priya Sharma – Architetto API e consulente per l’integrazione 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 la potenza dei Modelli di Linguaggio di Grandi Dimensioni (LLM) e strumenti esterni. Anche se il concetto può sembrare complesso, framework come LangChain hanno semplificato notevolmente 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 AI, ho visto da vicino il potenziale straordinario di agenti AI ben progettati. Possono automatizzare flussi di lavoro complessi, fornire assistenza personalizzata e sbloccare nuove capacità per aziende e individui. Questa guida pratica ti guiderà attraverso il processo di costruzione di solidi agenti AI utilizzando l’API di LangChain, dalla comprensione dei componenti chiave all’implementazione di esempi pratici e reali. Alla fine, avrai una base solida per progettare e implementare 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, chiarifichiamo cos’è un agente AI e perché LangChain è uno strumento indispensabile per la loro costruzione. Un agente AI è un sistema che utilizza un LLM come suo “cervello” per decidere quali azioni intraprendere. A differenza di una semplice chiamata 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 basato sulla sua comprensione e sugli 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, consentendo loro di andare oltre la semplice generazione di testo. Pensa a LangChain come al sistema operativo per il tuo agente AI, che fornisce 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 chiave:
- Modello di Linguaggio di Grandi Dimensioni (LLM): Il nucleo dell’intelligenza. Questo potrebbe essere un modello GPT di OpenAI, Claude di Anthropic o alternative open-source. L’LLM elabora input, ragiona ed emette decisioni.
- Strumenti: Funzioni che l’agente può chiamare per interagire con sistemi esterni o eseguire calcoli specifici. Esempi includono la ricerca sul web, le interrogazioni a un database, la chiamata a una calcolatrice o l’interazione con un’API personalizzata.
- Toolkit: Collezioni di strumenti correlati progettati per casi d’uso specifici (ad es., un “toolkit Wikipedia” o un “toolkit agenzia CSV”).
- Esecutore dell’Agente: Il runtime che orchestra le azioni dell’agente. Prende le decisioni dell’LLM, esegue gli strumenti scelti e riporta 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 per l’agente, assicurati che il tuo ambiente Python sia pronto. Avrai bisogno di Python 3.8+ e della libreria LangChain, insieme a eventuali fornitori di LLM che intendi utilizzare.
Installazione
Installa LangChain e un fornitore LLM (ad es., OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Per gestire le chiavi API in modo sicuroGestisci le tue chiavi API in modo sicuro. 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 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 è funzionante. Ora, abilitiamo il nostro LLM con strumenti.
Creare Strumenti per il Tuo Agente AI
Gli strumenti sono le mani e i piedi dell’agente, permettendogli 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: Un Semplice Strumento Calcolatore
Creiamo uno strumento che possa eseguire operazioni aritmetiche di base. Anche se gli LLM possono 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 lo strumento direttamente
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 serve come 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 progettata specificamente per RAG (Generazione Aumentata da Recupero) e casi d’uso di agenti.
Per prima cosa, installa Tavily e imposta 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) # Ottieni i primi 3 risultati
# Puoi anche personalizzare il nome e la descrizione se necessario
# search.name = "web_search"
# search.description = "Cerca informazioni sul web."
# Testa lo strumento di ricerca
print(search.invoke("tutorial agente LangChain"))Definendo questi strumenti, stiamo dando al nostro agente le capacità di estendere la propria conoscenza oltre i dati di addestramento e di eseguire calcoli con precisione.
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 di funzione di OpenAI.
Passi per la Costruzione dell’Agente
- Definisci il tuo LLM: Il cervello del tuo agente.
- Definisci i tuoi Strumenti: Le capacità 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 di 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 nella valutazione dell'espressione: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Cerca sul web informazioni attuali su una query fornita."
tools = [calculator, search]
# 3. Creare un Modello di Prompt
prompt = ChatPromptTemplate.from_messages(
[
("system", "Sei un assistente AI utile. Rispondi alle domande con la massima accuratezza 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 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, quale seleziona, l’input fornito allo strumento e l’output dello strumento. Questo è estremamente utile per il debug e per capire come ragiona il tuo agente.
Comprendere il Modello di Prompt
system: Imposta la persona generale e le istruzioni per l’agente.MessagesPlaceholder(variable_name="chat_history"): Qui verranno inseriti i turni di conversazione precedenti, consentendo 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 conversazione. LangChain fornisce vari tipi di memoria, consentendo al tuo agente di ricordare le 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 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 # Importa memoria
# Carica le variabili di 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 (come 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 query fornita."
tools = [calculator, search]
# Creare 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 con la massima accuratezza possibile."),
MessagesPlaceholder(variable_name="chat_history"), # Qui verrà 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)
# 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 la popolazione della capitale della Francia?")
result3 = agent_executor.invoke({"input": "E riguardo 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 ripetere esplicitamente il nome del paese. Il memory_key="chat_history" assicura che il contenuto della memoria sia correttamente mappato al MessagesPlaceholder(variable_name="chat_history") nel nostro prompt.
Altri Tipi di Memoria
Articoli Correlati
- Arrivare al Cuore dei Modelli di Progettazione API Efficaci
- API di Streaming per Agenti AI
- Qdrant vs FAISS: Quale per le Startup
🕒 Published: