LangChain per agenti IA: Tutorial completo
Gli agenti IA sono entità software autonome che possono percepire il loro ambiente, prendere decisioni e agire per raggiungere obiettivi specifici. Rappresentano un avanzamento significativo nel modo in cui interagiamo e costruiamo sistemi intelligenti. Se desideri comprendere i componenti essenziali e l’implementazione pratica degli agenti IA, inizia con Il guida completo degli agenti IA nel 2026. LangChain si distingue come un framework potente per costruire questi agenti, fornendo le astrazioni necessarie e gli strumenti per integrare grandi modelli di linguaggio (LLMs) con fonti di dati esterne e capacità di calcolo. Questo tutorial ti guiderà nella creazione di agenti IA utilizzando LangChain, concentrandosi sugli aspetti pratici e sui meccanismi sottostanti.
Comprendere i fondamenti degli agenti LangChain
Al centro di LangChain, un agente orchestra l’interazione tra un LLM e un insieme di strumenti. Il LLM funge da “cervello” dell’agente, decidendo quale strumento utilizzare e con quale input, in base all’obiettivo attuale e allo stato osservato. Gli strumenti sono funzioni che eseguono compiti specifici, come cercare sul web, interrogare un database o eseguire del codice.
I principali componenti di un agente LangChain sono:
- LLM: Il modello di linguaggio responsabile del ragionamento e della presa di decisione.
- Strumenti: Funzioni che l’agente può chiamare per interagire con il mondo esterno.
- Prompt: Istruzioni date al LLM, orientando il suo comportamento e l’uso degli strumenti.
- Esecutore di agente: L’ambiente di esecuzione che gestisce il ciclo dell’agente, passando le osservazioni e le azioni tra il LLM e gli strumenti.
Consideriamo un agente progettato per rispondere a domande sulle notizie. Potrebbe avere uno strumento per eseguire ricerche sul web e un altro per articoli. Il LLM, di fronte a una richiesta, deciderebbe se cercare sul web, eseguire la ricerca, osservare i risultati e poi eventualmente riassumerli prima di formulare una risposta finale.
Configurare il tuo ambiente LangChain
Prima di costruire un agente, assicurati di avere LangChain installato e di avere accesso a un LLM. Useremo i modelli di OpenAI per questo tutorial, ma LangChain supporta molti altri.
pip install langchain langchain-openai
Dovrai definire la tua chiave API OpenAI come variabile d’ambiente:
import os
os.environ["OPENAI_API_KEY"] = "LA_TUA_CHIAVE_API_OPENAI"
Per esempi più semplici, puoi istanziare direttamente il LLM:
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(temperature=0)
Il parametro `temperature` controlla il livello di randomizzazione dell’output del LLM. Un valore di 0 rende l’output più deterministico e fattuale, il che è adatto per la presa di decisione degli agenti.
Costruire il tuo primo agente LangChain: Un agente di ricerca semplice
Costruiamo un agente in grado di rispondere a domande utilizzando la ricerca sul web. Questo richiede uno strumento di ricerca web. LangChain fornisce integrazioni per vari fornitori di ricerca. Useremo lo strumento `TavilySearchResults`, che è spesso un buon scelta predefinita.
Per cominciare, installa il pacchetto necessario e configura la tua chiave API Tavily:
pip install langchain-community tavily-python
import os
os.environ["TAVILY_API_KEY"] = "LA_TUA_CHIAVE_API_TAVILY"
Ora, definiamo gli strumenti e istanziamo l’agente.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_community.tools.tavily_search import TavilySearchResults
# 1. Inizializzare il LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definire gli strumenti
search_tool = TavilySearchResults(max_results=3) # Limitare a 3 risultati di ricerca
tools = [search_tool]
# 3. Recuperare il prompt dell'agente ReAct dal LangChain Hub
# Il modello ReAct (Ragionamento e Azione) è un approccio comune per gli agenti.
# Incoraggia il LLM a generare un processo di riflessione prima di intraprendere un'azione.
prompt = hub.pull("hwchase17/react")
# 4. Creare l'agente
# create_react_agent costruisce un agente che utilizza il prompt ReAct.
agent = create_react_agent(llm, tools, prompt)
# 5. Creare l'esecutore dell'agente
# L'AgentExecutor è responsabile dell'esecuzione del ciclo decisionale dell'agente.
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Eseguire l'agente
response = agent_executor.invoke({"input": "Qual è la capitale della Francia e qual è la sua popolazione attuale?"})
print(response["output"])
In questo esempio:
- Inizializziamo `ChatOpenAI` come nostro LLM.
- Creiamo uno strumento `TavilySearchResults`.
- Recuperiamo un prompt ReAct standard da `langchain_hub`. Questo prompt guida il LLM a pensare passo dopo passo (Pensiero) e poi a decidere un’Azione e un’Entrata d’Azione.
- `create_react_agent` combina il LLM, gli strumenti e il prompt in un agente.
- `AgentExecutor` esegue l’agente, gestendo la sequenza delle osservazioni e delle azioni. Il flag `verbose=True` è cruciale per il debug, in quanto mostra il processo di riflessione interno dell’agente.
L’uscita con `verbose=True` mostrerà il “Pensiero”, “Azione”, “Entrata d’Azione” e “Osservazione” dell’agente a ogni fase, illustrando il suo ragionamento.
Aggiungere strumenti e capacità più complesse
Gli agenti diventano davvero potenti quando possono interagire con vari sistemi. Espandiamo il nostro agente con uno strumento per eseguire calcoli.
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_openai import ChatOpenAI
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.tools import tool # Decoratore per una creazione di filtro semplice
# 1. Inizializzare il LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definire gli strumenti
search_tool = TavilySearchResults(max_results=3)
@tool
def calculator(expression: str) -> str:
"""Valuta un'espressione matematica e restituisce il risultato."""
try:
return str(eval(expression))
except Exception as e:
return f"Errore durante la valutazione dell'espressione: {e}"
tools = [search_tool, calculator]
# 3. Recuperare il prompt dell'agente ReAct
prompt = hub.pull("hwchase17/react")
# 4. Creare l'agente
agent = create_react_agent(llm, tools, prompt)
# 5. Creare l'esecutore dell'agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Eseguire l'agente con una nuova richiesta
response = agent_executor.invoke({"input": "Qual è 12345 moltiplicato per 67890? Inoltre, trova chi ha vinto l'ultimo Coppa del Mondo."})
print(response["output"])
Qui, abbiamo usato il decoratore `@tool` per definire rapidamente uno strumento `calculator`. Questo decoratore deduce automaticamente la descrizione e lo schema di argomenti dello strumento, che il LLM utilizza per capire come chiamarlo. L’agente deciderà ora se utilizzare il `calculator` o i `TavilySearchResults` a seconda della richiesta di input. Questa modularità è essenziale per costruire agenti IA sofisticati. Per una coordinazione multi-agenti più avanzata, framework come CrewAI Multi-Agent Systems Guide offrono astrazioni potenti.
Tipi di agenti e i loro casi d’uso
LangChain offre diversi tipi di agenti, ciascuno con punti di forza e meccanismi decisionali differenti:
- `create_react_agent` (Agente ReAct): Utilizza il modello ReAct (Ragionamento e Azione). Il LLM genera un “Pensiero” (monologo interno) e poi un'”Azione” (chiamata dello strumento) e un'”Entrata d’Azione”. Questa è un’approccio molto efficace e ampiamente utilizzata per agenti a uso generale.
- `create_json_agent`: Progettato per agenti che interagiscono con API che si aspettano input e output JSON. Il LLM è incoraggiato a generare chiamate allo strumento in formato JSON.
- `create_openai_functions_agent`: utilizza le capacità di chiamata di funzione di OpenAI. Il LLM produce direttamente un oggetto strutturato che indica lo strumento da chiamare e i suoi argomenti, il che può essere più affidabile dell’analisi del testo. Spesso è la scelta preferita quando si utilizzano i modelli OpenAI.
La scelta del tipo di agente dipende dal tuo caso d’uso specifico e dal LLM che stai utilizzando. Per la maggior parte delle attività generali con i modelli OpenAI, `create_openai_functions_agent` è un eccellente punto di partenza grazie alla sua solidità. Esaminiamo un esempio utilizzandolo.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.messages import SystemMessage, HumanMessage
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
# 1. Inizializzare LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definire gli strumenti
search_tool = TavilySearchResults(max_results=3)
@tool
def current_time(format_str: str = "%Y-%m-%d %H:%M:%S") -> str:
"""Restituisce la data e l'ora correnti nel formato specificato."""
import datetime
return datetime.datetime.now().strftime(format_str)
tools = [search_tool, current_time]
# 3. Definire il prompt dell'agente (utilizzando messaggi specifici per l'agente OpenAI)
system_message = SystemMessage(
content="Sei un assistente IA utile. Utilizza gli strumenti disponibili per rispondere alle domande."
)
prompt = [system_message, HumanMessage(content="{input}"), MessagesPlaceholder(variable_name="agent_scratchpad")]
# 4. Creare l'agente utilizzando create_openai_functions_agent
agent = create_openai_functions_agent(llm, tools, prompt)
# 5. Creare l'esecutore dell'agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Eseguire l'agente
response = agent_executor.invoke({"input": "Che ore sono attualmente e quali erano i principali titoli di ieri?"})
print(response["output"])
Nota il `MessagesPlaceholder(variable_name=”agent_scratchpad”)` nel prompt. Qui vengono iniettati i pensieri, le azioni e le osservazioni intermedie dell’agente nella cronologia della conversazione, permettendo al LLM di mantenere il contesto.
Gestione dello stato e della memoria dell’agente
Affinché gli agenti possano realizzare interazioni complesse e multi-turno, hanno bisogno di memoria. LangChain fornisce vari componenti di memoria per memorizzare e recuperare la cronologia delle conversazioni. L’AgentExecutor può essere configurato con memoria.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.messages import SystemMessage, HumanMessage, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.memory import ConversationBufferWindowMemory # Importare la memoria
# 1. Inizializzare LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definire gli strumenti
search_tool = TavilySearchResults(max_results=3)
tools = [search_tool]
# 3. Definire il prompt dell'agente
system_message = SystemMessage(
content="Sei un assistente IA utile. Utilizza gli strumenti disponibili per rispondere alle domande. Sii conciso nelle tue risposte."
)
prompt = [
system_message,
MessagesPlaceholder(variable_name="chat_history"), # Segnaposto per la cronologia delle chat
HumanMessage(content="{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad")
]
# 4. Creare la memoria
# ConversationBufferWindowMemory mantiene una finestra delle ultime 'k' interazioni.
memory = ConversationBufferWindowMemory(memory_key="chat_history", return_messages=True, k=3)
# 5. Creare l'agente
agent = create_openai_functions_agent(llm, tools, prompt)
# 6. Creare l'esecutore dell'agente con memoria
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True,
memory=memory # Aggiungere la memoria qui
)
# 7. Eseguire una conversazione multi-turno
print("--- Primo turno ---")
response1 = agent_executor.invoke({"input": "Qual è la capitale del Giappone?"})
print(response1["output"])
print("\n--- Secondo turno ---")
response2 = agent_executor.invoke({"input": "Qual è la sua popolazione?"}) # Riferendosi a "sua" (la capitale del Giappone)
print(response2["output"])
print("\n--- Terzo turno ---")
response3 = agent_executor.invoke({"input": "E riguardo alla capitale del Brasile?"})
print(response3["output"])
Introducendo ConversationBufferWindowMemory e includendo MessagesPlaceholder(variable_name=”chat_history”) nel prompt, l’agente può ora mantenere il contesto attraverso più turni. Il LLM vede i messaggi precedenti, permettendogli di capire riferimenti come “la sua popolazione” nel secondo turno. Questo è essenziale per costruire agenti IA coinvolgenti e funzionali, in particolare per casi d’uso come la Creazione di un agente IA per il servizio clienti.
Personalizzazione avanzata dell’agente e sviluppo di strumenti
Sebbene LangChain offra molti strumenti integrati, avrai spesso bisogno di creare strumenti personalizzati per interagire con applicazioni specifiche, basi di dati o API interne.
Gli strumenti personalizzati possono essere semplici funzioni decorate con @tool, come mostrato con calculator e current_time. Per scenari più complessi, potresti definire una classe che estende BaseTool o utilizzare StructuredTool per una definizione precisa degli argomenti.
from langchain.tools import BaseTool
from pydantic import BaseModel, Field
from typing import Type
# Definire lo schema di input per lo strumento personalizzato
class GetDatabaseRecordInput(BaseModel):
table_name: str = Field(description="Nome della tabella del database")
record_id: int = Field(description="ID del record da recuperare")
class GetDatabaseRecordTool(BaseTool):
name = "get_database_record"
description = "Utile per recuperare un record specifico da una tabella del database per il suo ID."
args_schema: Type[BaseModel] = GetDatabaseRecordInput
def _run(self, table_name: str, record_id: int) -> str:
"""Simula il recupero di un record da un database."""
print(f"DEBUG: Recupero del record {record_id} dalla tabella {table_name}")
if table_name == "users" and record_id == 1:
return "Record utente: {'id': 1, 'name': 'Alice', 'email': '[email protected]'}"
elif table_name == "products" and record_id == 101:
return "Record prodotto: {'id': 101, 'name': 'Laptop', 'price': 1200}"
return f"Record non trovato per la tabella '{table_name}' con l'ID '{record_id}'"
async def _arun(self, table_name: str, record_id: int) -> str:
"""Versione asincrona dello strumento (opzionale)."""
# Implementare la logica asincrona qui
raise NotImplementedError("Chiamata asincrona non implementata per questo strumento.")
# Aggiungere questo strumento alla lista di strumenti del tuo agente
# tools.append(GetDatabaseRecordTool())
Questo GetDatabaseRecordTool dimostra come definire uno strumento con uno schema di input specifico utilizzando Pydantic, fornendo al LLM istruzioni chiare su come utilizzarlo. Questo livello di controllo è essenziale per integrare agenti in sistemi aziendali. Quando confronti framework, considera come ciascuno gestisce queste integrazioni degli strumenti personalizzati; vedere Confronta i 5 migliori framework di agenti IA 2026 per maggiori dettagli.
Punti chiave da ricordare
- Gli agenti LangChain utilizzano un LLM per orchestrare l’uso degli strumenti, consentendo loro di interagire con il mondo esterno oltre i loro dati di addestramento.
- I componenti principali sono il LLM, gli strumenti, un prompt e l’esecutore dell’agente.
- Il modello ReAct (Ragionare e Agire) è un approccio solido, spesso facilitato dai prompt di LangChain Hub.
create_openai_functions_agentè generalmente raccomandato per i modelli OpenAI a causa della sua uscita strutturata affidabile.- I componenti di memoria (ad esempio,
ConversationBufferWindowMemory) sono cruciali per conversazioni multi-turno e consapevolezza del contesto. - Gli strumenti personalizzati sono facili da creare utilizzando il decoratore
@toolo estendendoBaseToolper interazioni più complesse, consentendo agli agenti di integrarsi in sistemi proprietari. - Utilizza sempre
verbose=Truedurante lo sviluppo per ispezionare il processo di pensiero interno dell’agente e fare debug in modo efficace.
Conclusione
LangChain fornisce un framework completo e flessibile per costruire agenti IA. Comprendendo i suoi componenti principali—LLM, strumenti, prompt e esecutori—puoi costruire agenti capaci di ragionamento complesso e interazione. Dagli agenti di ricerca semplici ai sistemi sofisticati con memoria e integrazioni personalizzate, LangChain offre gli elementi necessari per realizzare le tue idee di agenti IA. Man mano che il campo degli agenti IA continua a evolversi, padroneggiare framework come LangChain diventerà sempre più prezioso per sviluppare applicazioni intelligenti e autonome.
🕒 Published: