LangChain Agents: agenti autonomi con strumenti e memoria — Guida Operativa • Meteora Web Agency

Hai un LLM che risponde in modo brillante ma non può cercare dati in tempo reale, eseguire calcoli o interagire con le tue API. Serve qualcosa che agisca, non solo che parli. L'agente LangChain è la risposta: un sistema che decide quali strumenti usare, in che ordine, e ricorda il contesto delle conversazioni. In questa guida costruiamo un agente funzionante, con strumenti personalizzati e memoria, passo dopo passo. Niente teoria astratta: solo codice che puoi copiare, testare e adattare.

Perché un agente invece di una chain semplice

Una chain esegue una sequenza fissa di passaggi: prendi input, passa a un prompt, ottieni output. È lineare, prevedibile, ma rigida. Un agente, invece, segue un ciclo osservazione-pensiero-azione: riceve un compito, sceglie uno strumento, esegue l'azione, osserva il risultato e decide il passo successivo. È come avere un assistente che sa quando chiamare un esperto (strumento) e quando ragionare da solo.

Noi, di Meteora Web, abbiamo applicato questo pattern in progetti di automazione per PMI: assistenti virtuali che verificano disponibilità magazzino, calcolano preventivi e aggiornano CRM. Il risultato? Meno interventi manuali e risposte più rapide. Ma attenzione: ogni chiamata a un LLM costa tempo e denaro. Prima di lanciare un agente in produzione, valutiamo insieme il ROI — come facciamo con ogni strumento digitale.

Struttura di un agente LangChain

Un agente è composto da quattro elementi base:

LLM: il cervello, che ragiona e decide (es. GPT-4, Claude, Llama).
Prompt: istruzioni che descrivono all'LLM come usare gli strumenti, con esempi e formato di output (solitamente ReAct).
Strumenti: funzioni o API che l'agente può chiamare. Ogni strumento ha un nome, una descrizione e una funzione associata.
Memoria: permette all'agente di ricordare interazioni precedenti. Senza memoria, ogni richiesta parte da zero.

Il ciclo è gestito da un AgentExecutor, che invoca l'agente, esegue gli strumenti scelti e ripete fino a quando non ottiene una risposta finale.

Creare uno strumento personalizzato

Uno strumento è semplicemente una funzione Python con una descrizione chiara. LangChain fornisce decoratori e classi per definirli. Esempio: uno strumento che restituisce il meteo (simulato) per una città.

from langchain.tools import tool

@tool
def get_meteo(citta: str) -> str:
    """Restituisce il meteo attuale per la città specificata."""
    # Simulazione: in produzione chiameresti un'API
    meteo = {
        "Roma": "Sereno, 22°C",
        "Milano": "Nuvoloso, 18°C",
        "Palermo": "Soleggiato, 25°C"
    }
    return meteo.get(citta, "Dato non disponibile")

La descrizione (docstring) è cruciale: l'LLM la legge per capire quando e come usare lo strumento. Più è precisa, migliori saranno le decisioni dell'agente.

Aggiungere la memoria

La memoria trasforma l'agente da risponditore statico a interlocutore contestuale. LangChain offre diverse tipologie: ConversationBufferMemory, ConversationSummaryMemory, ecc. La più semplice è la buffer, che conserva l'intera cronologia della chat.

Integrarla richiede due accorgimenti: (1) aggiungere la memoria al prompt sotto forma di variabili di contesto, (2) passare la memoria all'executor. Ecco un esempio completo.

Costruiamo un agente con strumenti e memoria

Partiamo da un caso reale: un assistente per un e-commerce che può cercare prodotti (simulati) e ricordare le preferenze del cliente. Noi, di Meteora Web, abbiamo esperienza diretta con il retail – abbiamo gestito l'ERP di un negozio di abbigliamento – e sappiamo quanto sia utile un agente che conosce lo storico degli acquisti.

Installazione e import

pip install langchain langchain-openai

import os
from langchain.agents import AgentExecutor, create_react_agent
from langchain.tools import tool
from langchain.memory import ConversationBufferMemory
from langchain_openai import ChatOpenAI
from langchain.prompts import PromptTemplate

Definire gli strumenti

@tool
def cerca_prodotto(nome: str) -> str:
    """Cerca un prodotto per nome e restituisce disponibilità e prezzo."""
    catalogo = {
        "maglietta bianca": {"prezzo": 25, "disponibile": True},
        "jeans blu": {"prezzo": 60, "disponibile": False},
        "scarpe running": {"prezzo": 120, "disponibile": True}
    }
    prodotto = catalogo.get(nome.lower())
    if not prodotto:
        return f"Prodotto '{nome}' non trovato."
    disp = "disponibile" if prodotto["disponibile"] else "non disponibile"
    return f"{nome}: {prodotto['prezzo']}€, {disp}."

@tool
def calcola_spedizione(citta: str) -> str:
    """Calcola il costo di spedizione per una città italiana."""
    costi = {"Roma": 5, "Milano": 7, "Palermo": 10}
    costo = costi.get(citta, 15)
    return f"Costo spedizione per {citta}: {costo}€"

Configurare LLM e prompt

llm = ChatOpenAI(model="gpt-4", temperature=0, openai_api_key=os.getenv("OPENAI_API_KEY"))

prompt = PromptTemplate.from_template(
    """Sei un assistente per un e-commerce. Hai accesso ai seguenti strumenti:
{tools}

Non usare strumenti se non necessario. Rispondi in modo chiaro e completo.

Contesto della conversazione:
{chat_history}

Richiesta dell'utente: {input}

{agent_scratchpad}"""
)

Creare memoria ed executor

memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)

# Lista degli strumenti
strumenti = [cerca_prodotto, calcola_spedizione]

# Crea agente (ReAct style)
agente = create_react_agent(llm, strumenti, prompt)

# Executor con memoria
executor = AgentExecutor(
    agent=agente,
    tools=strumenti,
    memory=memory,
    verbose=True,
    handle_parsing_errors=True
)

Testare l'agente

# Prima interazione
esecutor.invoke({"input": "Cerca la maglietta bianca e dimmi il costo di spedizione a Palermo"})
# Output: cerca_prodotto -> calcola_spedizione -> risposta

# Seconda interazione (con memoria)
esecutor.invoke({"input": "Quale prodotto ho cercato prima?"})
# L'agente dovrebbe ricordare la maglietta bianca grazie alla memoria

Nota: il campo {agent_scratchpad} è dove l'agente annota i propri pensieri e azioni intermedie. È gestito automaticamente da LangChain.

Errori comuni e come evitarli

Loop infiniti: l'agente continua a chiamare strumenti senza trovare una risposta. Soluzione: limitare il numero massimo di iterazioni con max_iterations nell'executor (es. max_iterations=5).

Descrizioni degli strumenti troppo vaghe: l'LLM non capisce quando usarli. Sii specifico: “Cerca nel catalogo per nome esatto del prodotto” è meglio di “Cerca prodotto”.

Memoria non persistente: in produzione, usa una memoria esterna (Redis, database) per mantenere lo stato tra sessioni. ConversationBufferMemory è solo in-memory.

Costi imprevisti: ogni chiamata a uno strumento può generare più round di LLM. Monitora il numero di token e imposta un budget massimo.

Quando un agente conviene e quando no

Un agente è potente ma ha un costo: latenza maggiore, token extra per il ragionamento, complessità di debug. Noi lo consigliamo quando:

Il compito richiede decisioni dinamiche (es. assistenza clienti multi-dominio).
Gli strumenti sono numerosi e cambiano spesso.
La conversazione deve essere contestuale e multi-turno.

Se invece hai un flusso fisso (es. “ricevi email, estrai dati, scrivi su DB”), una chain è più semplice ed economica. Non usare un cannone per sparare a una mosca. Nella nostra esperienza, molti clienti iniziano con agenti complessi per poi semplificare quando scoprono che il 90% dei casi è lineare.

Inoltre, ricorda: possedere il proprio stack (LLM open source, strumenti custom) spesso batte l'affitto di soluzioni pronte, specialmente per dati sensibili. Noi, di Meteora Web, abbiamo costruito una piattaforma proprietaria per gestire la presenza social di più clienti: scelta analoga, controllo totale.

In sintesi — cosa fare adesso

Installa LangChain e un provider LLM (OpenAI, Ollama per modelli locali).
Definisci 2-3 strumenti legati al tuo dominio: cerca prodotto, calcola prezzo, invia email.
Costruisci un agente con memoria buffer seguendo il codice sopra.
Testa con 5-10 conversazioni reali e verifica che l'agente scelga gli strumenti giusti.
Misura il costo per conversazione (token stimati) e confrontalo con il valore generato (risparmio tempo, conversioni).
Valuta se passare a una chain per i casi più semplici.

Per approfondire, consulta la documentazione ufficiale di LangChain sugli agenti. Se vuoi capire come integrare agenti in un flusso aziendale più ampio, leggi la nostra guida su Automazione con AI per PMI.