LangChain per Agenti AI: Guida Completa

LangChain per Agenti AI: Guida Completa

Gli agenti AI sono entità software autonome che possono percepire il loro ambiente, prendere decisioni e compiere azioni per raggiungere obiettivi specifici. Rappresentano un significativo avanzamento nel modo in cui interagiamo e costruiamo sistemi intelligenti. Se stai cercando di comprendere i componenti fondamentali e l’implementazione pratica degli agenti AI, inizia con La Guida Completa agli Agenti AI nel 2026. LangChain si distingue come un potente framework per costruire questi agenti, fornendo le astrazioni e gli strumenti necessari per integrare modelli linguistici di grandi dimensioni (LLM) con fonti di dati esterne e capacità computazionali. Questo tutorial ti guiderà nella costruzione di agenti AI utilizzando LangChain, concentrandosi sugli aspetti pratici e sui meccanismi sottostanti.

Comprendere i Fondamenti degli Agenti LangChain

In sostanza, un agente LangChain orchestra l’interazione tra un LLM e un insieme di strumenti. L’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 codice.

I componenti principali di un agente LangChain sono:

• LLM: Il modello linguistico responsabile del ragionamento e della presa di decisioni.
• Strumenti: Funzioni che l’agente può richiamare per interagire con il mondo esterno.
• Prompt: Istruzioni date all’LLM, che guidano il suo comportamento e l’uso degli strumenti.
• Esecutore dell’agente: Il runtime che gestisce il ciclo dell’agente, passando le osservazioni e le azioni tra l’LLM e gli strumenti.

Considera un agente progettato per rispondere a domande sugli eventi correnti. Potrebbe avere uno strumento per effettuare ricerche sul web e un altro per gli articoli. L’LLM, data una query, deciderebbe se cercare sul web, eseguire la ricerca, osservare i risultati e poi potenzialmente riassumerli prima di formulare una risposta finale.

Impostare il Tuo Ambiente LangChain

Prima di costruire un agente, assicurati di avere LangChain installato e accesso a un LLM. Useremo i modelli di OpenAI per questo tutorial, ma LangChain supporta molti altri.

pip install langchain langchain-openai

Dovrai impostare la tua chiave API di OpenAI come variabile d’ambiente:

import os
os.environ["OPENAI_API_KEY"] = "LA_TUA_CHIAVE_API_OPENAI"

Per esempi più semplici, puoi istanziare direttamente l’LLM:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(temperature=0)

Il parametro `temperature` controlla la casualità dell’output dell’LLM. Un valore di 0 rende l’output più deterministico e fattuale, adatto per la presa di decisioni da parte dell’agente.

Costruire il Tuo Primo Agente LangChain: Un Semplice Agente di Ricerca

Costruiamo un agente che può rispondere a domande utilizzando la ricerca sul web. Questo richiede uno strumento di ricerca sul web. LangChain fornisce integrazioni per vari fornitori di ricerca. Useremo lo strumento `TavilySearchResults`, che è spesso un buon default.

Prima, installa il pacchetto necessario e imposta la tua chiave API di 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. Inizializza LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definisci Strumenti
search_tool = TavilySearchResults(max_results=3) # Limita a 3 risultati di ricerca
tools = [search_tool]

# 3. Richiedi il Prompt dell'Agente ReAct da LangChain Hub
# Il pattern ReAct (Ragionare e Agire) è un approccio comune per gli agenti.
# Invita l'LLM a generare un processo di pensiero prima di prendere un'azione.
prompt = hub.pull("hwchase17/react")

# 4. Crea l'Agente
# create_react_agent costruisce un agente che utilizza il prompt ReAct.
agent = create_react_agent(llm, tools, prompt)

# 5. Crea l'Esecutore dell'Agente
# L'AgentExecutor è responsabile dell'esecuzione del ciclo decisionale dell'agente.
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 6. Esegui 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`.
• Richiediamo un prompt standard ReAct da `langchain_hub`. Questo prompt guida l’LLM a pensare passo dopo passo (Pensiero) e poi decidere un’Azione e un’Input dell’Azione.
• `create_react_agent` combina l’LLM, gli strumenti e il prompt in un agente.
• `AgentExecutor` esegue l’agente, gestendo la sequenza di osservazioni e azioni. Il flag `verbose=True` è cruciale per il debug, poiché mostra il processo di pensiero interno dell’agente.

L’output con `verbose=True` mostrerà il “Pensiero,” l’“Azione,” l’“Input dell’Azione,” e “Osservazione” ad ogni passo, dimostrando il suo ragionamento.

Aggiungere Strumenti e Capacità più Complessi

Gli agenti diventano davvero potenti quando possono interagire con vari sistemi. Estendiamo 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 la creazione di strumenti semplici

# 1. Inizializza LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definisci 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 nella valutazione dell'espressione: {e}"

tools = [search_tool, calculator]

# 3. Richiedi il Prompt dell'Agente ReAct
prompt = hub.pull("hwchase17/react")

# 4. Crea l'Agente
agent = create_react_agent(llm, tools, prompt)

# 5. Crea l'Esecutore dell'Agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 6. Esegui l'Agente con una nuova query
response = agent_executor.invoke({"input": "Qual è 12345 per 67890? Inoltre, scopri chi ha vinto l'ultimo Mondiale."})
print(response["output"])

Qui, abbiamo utilizzato il decoratore `@tool` per definire rapidamente uno strumento `calculator`. Questo decoratore inferisce automaticamente la descrizione dello strumento e lo schema degli argomenti, che l’LLM utilizza per capire come richiamarlo. L’agente deciderà ora se utilizzare il `calculator` o `TavilySearchResults` in base alla query di input. Questa modularità è fondamentale per costruire agenti AI sofisticati. Per una coordinazione multi-agente 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 diversi e meccanismi decisionali sottostanti:

• `create_react_agent` (Agente ReAct): Utilizza il pattern ReAct (Ragionare e Agire). L’LLM genera un “Pensiero” (monologo interno) e poi un’“Azione” (richiamata strumento) e “Input dell’Azione.” Questo è un approccio altamente efficace e ampiamente utilizzato per agenti di uso generale.
• `create_json_agent`: Progettato per agenti che interagiscono con API che si aspettano input e output in formato JSON. L’LLM viene invitato a generare chiamate a strumenti in formato JSON.
• `create_openai_functions_agent`: utilizza le capacità di chiamata alle funzioni di OpenAI. L’LLM restituisce direttamente un oggetto strutturato che indica lo strumento da richiamare e i suoi argomenti, il che può essere più affidabile rispetto all’analisi del testo. Questo è spesso la scelta preferita quando si utilizzano modelli OpenAI.

La scelta del tipo di agente giusto dipende dal tuo caso d’uso specifico e dall’LLM che stai utilizzando. Per la maggior parte dei compiti generali con i modelli OpenAI, `create_openai_functions_agent` è un ottimo punto di partenza grazie alla sua solidità. Vediamo un esempio che lo utilizza.

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. Inizializza LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definisci 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 attuali nel formato specificato."""
 import datetime
 return datetime.datetime.now().strftime(format_str)

tools = [search_tool, current_time]

# 3. Definisci il Prompt dell'Agente (utilizzando messaggi specifici per l'agente OpenAI functions)
system_message = SystemMessage(
 content="Sei un assistente AI utile. Usa gli strumenti disponibili per rispondere alle domande."
)
prompt = [system_message, HumanMessage(content="{input}"), MessagesPlaceholder(variable_name="agent_scratchpad")]

# 4. Crea l'Agente utilizzando create_openai_functions_agent
agent = create_openai_functions_agent(llm, tools, prompt)

# 5. Crea l'Esecutore dell'Agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 6. Esegui l'Agente
response = agent_executor.invoke({"input": "Qual è l'ora attuale e quali erano i titoli principali 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, consentendo al LLM di mantenere il contesto.

Gestione dello Stato e della Memoria dell’Agente

Per permettere agli agenti di eseguire 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 # Importa memoria

# 1. Inizializza LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definisci gli Strumenti
search_tool = TavilySearchResults(max_results=3)
tools = [search_tool]

# 3. Definisci il Prompt dell'Agente
system_message = SystemMessage(
 content="Sei un assistente AI utile. Usa gli strumenti disponibili per rispondere alle domande. Mantieni le tue risposte concise."
)
prompt = [
 system_message,
 MessagesPlaceholder(variable_name="chat_history"), # Segnaposto per la cronologia della chat
 HumanMessage(content="{input}"),
 MessagesPlaceholder(variable_name="agent_scratchpad")
]

# 4. Crea Memoria
# ConversationBufferWindowMemory mantiene una finestra delle ultime 'k' interazioni.
memory = ConversationBufferWindowMemory(memory_key="chat_history", return_messages=True, k=3)

# 5. Crea l'Agente
agent = create_openai_functions_agent(llm, tools, prompt)

# 6. Crea l'Esecutore dell'Agente con memoria
agent_executor = AgentExecutor(
 agent=agent,
 tools=tools,
 verbose=True,
 memory=memory # Aggiungi memoria qui
)

# 7. Esegui 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" (capitale del Giappone)
print(response2["output"])

print("\n--- Terzo Turno ---")
response3 = agent_executor.invoke({"input": "E per quanto riguarda la capitale del Brasile?"})
print(response3["output"])

Introdurre `ConversationBufferWindowMemory` e includere `MessagesPlaceholder(variable_name=”chat_history”)` nel prompt consente ora all’agente di mantenere il contesto attraverso più turni. Il LLM vede i messaggi precedenti, permettendogli di comprendere riferimenti come “la sua popolazione” nel secondo turno. Questo è fondamentale per costruire agenti AI coinvolgenti e funzionali, specialmente per casi d’uso come Creare un Agente AI per il Servizio Clienti.

Personalizzazione Avanzata dell’Agente e Sviluppo di Strumenti

Seppur LangChain fornisca molti strumenti integrati, sarà spesso necessario creare strumenti personalizzati per interagire con applicazioni specifiche, database 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 eredita da `BaseTool` o utilizzare `StructuredTool` per una definizione precisa degli argomenti.

from langchain.tools import BaseTool
from pydantic import BaseModel, Field
from typing import Type

# Definisci 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 in base al 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: Recuperando 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 ID '{record_id}'"

 async def _arun(self, table_name: str, record_id: int) -> str:
 """Versione asincrona dello strumento (opzionale)."""
 # Implementa qui la logica asincrona
 raise NotImplementedError("Chiamata asincrona non implementata per questo strumento.")

# Aggiungi questo strumento alla lista degli 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 gli agenti nei sistemi aziendali. Quando si confrontano framework, considera come ciascuno gestisce queste integrazioni di strumenti personalizzati; consulta Confronto dei principali Framework per Agenti AI 2026 per ulteriori dettagli.

Principali Risultati

• Gli agenti LangChain utilizzano un LLM per orchestrare l’uso degli strumenti, consentendo loro di interagire con il mondo esterno oltre i dati di addestramento.
• I componenti principali sono LLM, Strumenti, un Prompt e l’Esecutore dell’Agente.
• Il modello ReAct (Ragionamento e Azione) è un approccio solido, spesso facilitato da prompt del LangChain Hub.
• `create_openai_functions_agent` è generalmente consigliato per i modelli OpenAI grazie alla sua uscita strutturata affidabile.
• I componenti di memoria (es. `ConversationBufferWindowMemory`) sono cruciali per conversazioni multi-turno e consapevolezza contestuale.
• Gli strumenti personalizzati sono facili da creare utilizzando il decoratore `@tool` o ereditando da `BaseTool` per interazioni più complesse, permettendo agli agenti di integrarsi con i sistemi proprietari.
• Usa sempre `verbose=True` durante lo sviluppo per ispezionare il processo di pensiero interno dell’agente e debugare efficacemente.

Conclusione

LangChain offre un framework completo e flessibile per costruire agenti AI. Comprendendo i suoi componenti principali—LLM, strumenti, prompt ed esecutori—puoi costruire agenti capaci di ragionamento e interazione complessi. Da semplici agenti di ricerca a sistemi sofisticati con memoria e integrazioni personalizzate, LangChain offre i mattoni per realizzare le tue idee di agenti AI. Man mano che il campo degli agenti AI continua a evolversi, padroneggiare framework come LangChain sarà sempre più prezioso per sviluppare applicazioni intelligenti e autonome.

🕒 Published: April 3, 2026