LangChain e LangGraph: come si costruiscono gli agenti AI che lavorano davvero

Se segui il mondo degli agenti AI, prima o poi ti imbatti in due nomi: LangChain e LangGraph. Compaiono nelle demo, nei repository GitHub, nei talk dei conferenzieri con la maglietta nera e il caffè freddo. Il problema è che quasi nessuno spiega cosa fanno davvero, mentre la documentazione ufficiale parte dal presupposto che tu sappia già perché sei lì.

Provo a mettere le cose in fila: cosa fa LangChain, cosa aggiunge LangGraph, quando serve uno e quando l’altro. Poi ti racconto tre casi d’uso concreti, in azienda, in editoria e nella SEO, dove questi strumenti smettono di essere giocattoli e diventano ore di lavoro risparmiate.

Perché conta: un agente che funziona non è un chatbot più chiacchierone. È un pezzo di software che prende una decisione, chiama gli strumenti giusti e restituisce un risultato verificabile. Il framework serve a tenere insieme questa catena senza riscriverla ogni volta da zero.

Cosa fa LangChain, senza giri di parole

LangChain è una libreria open source, in Python e TypeScript, che mette un livello di astrazione sopra i modelli linguistici. Traduce un’idea semplice: un agente è un modello più un harness, cioè tutto ciò che gli sta intorno. Prompt, strumenti, formato delle risposte, gestione degli errori.

Dalla versione 1.0, uscita nell’autunno 2025, il cuore della libreria è create_agent. Poche righe e hai un agente con un ciclo di tool calling standard: il modello riceve la richiesta, decide se chiamare uno strumento, il framework esegue e rimanda il risultato al modello. Il giro si ripete finché il modello non produce una risposta finale.

Il vantaggio vero è l’indipendenza dal provider. Cambi modello cambiando una stringa, senza riscrivere l’architettura. Se domani il modello che usi costa troppo o peggiora, passi a un altro e il resto del codice resta dov’è. In un mercato dove il modello migliore cambia ogni sei mesi, non è un dettaglio da poco.

Il secondo pezzo sono i middleware: funzioni che si inseriscono nel ciclo per aggiungere comportamenti senza toccare il prompt. Compattare la cronologia quando la conversazione si allunga, tagliare le chiamate a un tool vietato, registrare ogni passaggio su un log. Sono i punti in cui di solito nascono i bug più fastidiosi.

from langchain.agents import create_agent

def cerca_ordine(numero: str) -> str:
    """Cerca un ordine nel gestionale e restituisce stato e data di consegna."""
    return db.ordini.cerca(numero)

agente = create_agent(
    model="openai:gpt-5.6",
    tools=[cerca_ordine],
    system_prompt="Sei l'assistente ordini. Rispondi solo con dati presenti nel gestionale.",
)

esito = agente.invoke({
    "messages": [{"role": "user", "content": "Dov'è l'ordine 88231?"}]
})
print(esito["messages"][-1].content)

Quindici righe e hai un agente che legge un gestionale. Sembra magia, in realtà è un ciclo while con le scarpe buone.

Cosa aggiunge LangGraph

LangGraph è un runtime di orchestrazione a basso livello. Non ti dice come scrivere il prompt, non ti impone un’architettura: ti dà un grafo di stato condiviso, fatto di nodi e archi. Ogni nodo è una funzione che legge lo stato e restituisce una modifica. Gli archi decidono dove andare dopo, anche in base al contenuto dello stato.

Il punto è che in un grafo puoi mescolare passaggi deterministici e passaggi affidati al modello. Il parsing di un PDF è codice normale, la scelta di come rispondere a un reclamo è del modello. Questa distinzione sembra banale e invece è la differenza tra un sistema che si può mettere in produzione e uno che a un certo punto fa una cosa a caso.

Poi ci sono le tre cose che rendono LangGraph interessante per il lavoro vero. La persistenza: ogni passo salva un checkpoint, quindi se il processo muore alle tre di notte riparte da dove era rimasto invece di rifare tutto. Gli interrupt: il grafo si ferma, un umano controlla o corregge lo stato, poi si riprende. Lo streaming: vedi passaggio per passaggio cosa sta succedendo, utile quando un’operazione dura minuti.

from langgraph.graph import StateGraph, MessagesState, START, END

def classifica(state: MessagesState):
    # codice deterministico: legge il testo e assegna una categoria
    return {"categoria": categoria}

def rispondi(state: MessagesState):
    # nodo con il modello
    return {"messages": [risposta]}

def scala_a_umano(state: MessagesState):
    return {"messages": ["Presa in carico da un operatore"]}

grafo = StateGraph(MessagesState)
grafo.add_node("classifica", classifica)
grafo.add_node("rispondi", rispondi)
grafo.add_node("umano", scala_a_umano)
grafo.add_edge(START, "classifica")
grafo.add_conditional_edges(
    "classifica",
    lambda s: "rispondi" if s["categoria"] in categorie_automatiche else "umano",
)
grafo.add_edge("rispondi", END)
grafo.add_edge("umano", END)

app = grafo.compile(checkpointer=checkpointer)

Quel checkpointer è la riga che salva la giornata. Se il worker viene riavviato a metà pratica, la pratica riparte dal checkpoint e non dall’inizio.

Quando usare uno e quando l’altro

La regola che uso io è semplice: parti dal caso più piccolo che risolve il problema.

• LangChain se ti serve un agente con pochi strumenti, una conversazione lineare e nessun bisogno di riprendere un lavoro interrotto. È il caso del supporto clienti di primo livello, della classificazione di email, della ricerca dentro un archivio.
• LangGraph se il processo ha più fasi, approvazioni umane, fallimenti da recuperare o passaggi che devono restare deterministici. È il caso dei flussi che toccano un gestionale, un contratto o una pubblicazione.
• Entrambi, ed è la combinazione più comune: grafo per l’orchestrazione, agenti LangChain dentro i nodi dove serve un po’ di giudizio.

C’è anche un terzo livello, Deep Agents, che impacchetta pianificazione, subagenti e gestione del contesto sopra LangGraph. Utile quando il problema è “un agente che lavora per ore”, non quando devi solo automatizzare una pratica da dieci minuti.

Un caso aziendale: dall’email al gestionale

Prendi un ufficio commerciale che riceve duecento email al giorno tra richieste di preventivo, ordini, conferme e documenti dei fornitori. Ogni email va letta, capita e trascritta. È il tipo di lavoro che nessuno ama e in cui gli errori costano.

Con LangGraph il flusso si spezza in nodi leggibili. Un primo nodo classifica l’intento con regole e modello. Un secondo estrae i dati con uno schema rigido, tipo ragione sociale, partita IVA, articoli, quantità. Un terzo confronta i dati con l’anagrafica e segnala le discrepanze. Un quarto crea la bozza nel gestionale, ma solo se il punteggio di confidenza supera una soglia. Sotto soglia il grafo si ferma con un interrupt e chiama una persona.

Il valore non sta nell’automazione totale, che raramente esiste. Sta nel fatto che l’operatore trova la pratica già compilata e deve solo confermare. Su una mail complicata risparmia tre minuti, su duecento mail sono ore. E la sera il grafo ha lasciato un log di ogni passaggio, quindi se qualcosa non torna sai dove guardare.

Lo stesso schema vale per l’ordine al fornitore, per la riconciliazione delle fatture e per l’onboarding dei clienti nuovi. Cambiano i nodi, non l’architettura. Se ti interessa il ragionamento dietro le decisioni automatiche, ne ho scritto in modelli decisionali, con e senza RAG.

Editoria: la redazione che non si ferma alle sei

In editoria l’agente non serve a scrivere l’articolo al posto del giornalista. Serve a togliere di mezzo le parti noiose, che sono la maggioranza del tempo: normalizzare i nomi, controllare le date, cercare i link interni, preparare la scheda per il social, verificare che un’affermazione abbia una fonte.

Un grafo editoriale che funziona ha più o meno questa forma. Brief con angolo e fonti obbligatorie. Scaletta discussa con il modello. Bozza. Passaggio di fact-checking che confronta ogni numero con la fonte citata e segna quelli senza riscontro. Passaggio SEO su titolo, meta description, struttura dei titoli. Interrupt finale per l’approvazione dell’editor. Solo dopo, pubblicazione.

La parte interessante è il fact-checking, perché è lì che un agente può fare danni. Il nodo non deve “sapere” se un dato è giusto: deve andare a leggerlo nella fonte, citarla e restituire un verdetto con l’URL. Se la fonte non si apre, il verdetto è “non verificato”, non “probabilmente giusto”. Questa distinzione va scritta nel prompt e nel codice, non lasciata al buon senso del modello.

Sul mio sito uso un’architettura simile per la newsletter settimanale: raccolta delle fonti, scrematura, stesura, controllo dei link e approvazione mia prima dell’invio. Il pezzo che mi ha fatto risparmiare più tempo non è la scrittura, è il controllo incrociato dei link rotti.

SEO: audit, refresh e cannibalizzazione

La SEO è il posto dove gli agenti vengono venduti con più fumo e dove servono più regole. Il motivo è semplice: i dati veri stanno nelle API, non nella testa del modello. Un agente che “fa SEO” senza toccare Search Console ti inventa un calo di traffico con la stessa sicurezza con cui ti dice il meteo.

Il grafo giusto parte dai dati. Un nodo deterministico scarica le query da Search Console e le pagine dal crawler. Un nodo raggruppa le query per intento. Un nodo confronta i contenuti esistenti e segnala i casi di cannibalizzazione, cioè due pagine che competono sulla stessa query. Poi il modello entra in gioco per proporre il brief, riscrivere un titolo o suggerire sezioni mancanti.

Il passaggio finale resta umano, sempre. L’agente produce una lista di interventi ordinata per impatto stimato, con la prova accanto: query, posizione, clic, pagina. Tu decidi cosa fare. Se un suggerimento non ha un numero dietro, non entra nella lista.

Questo schema funziona bene anche per il refresh dei contenuti vecchi, che è il lavoro più noioso e più redditizio della SEO. L’agente trova gli articoli che hanno perso posizioni, legge le SERP attuali, segnala i paragrafi da aggiornare e prepara la bozza di modifica. La revisione editoriale resta tua, perché il tono non si automatizza.

Come capire se l’agente sta funzionando

Un agente in produzione si giudica con numeri, non con l’impressione della demo. Le cinque metriche che guardo io sono queste: tempo medio per pratica, percentuale di pratiche approvate al primo colpo, costo per pratica tra token e infrastruttura, numero di errori che arrivano all’umano e latenza percepita.

Il confronto va fatto con una baseline misurata prima di partire. Se non hai la baseline, non hai idea se stai migliorando o solo spendendo. E serve un set di valutazione con casi reali, anonimizzati, da rilanciare a ogni modifica del prompt o del modello: senza quello, ogni cambiamento è una scommessa.

LangSmith, nella stessa famiglia, serve proprio a questo: traccia ogni passaggio, valuta gli output e ti mostra dove il grafo perde colpi. Non è obbligatorio, ma quando un agente sbaglia una volta su cento e non capisci perché, il tracing smette di essere un lusso.

Gli errori che vedo più spesso

• Agentificare il deterministico. L’IVA si calcola con una formula, non con un modello. Ogni passaggio che può essere codice deve essere codice: costa meno, sbaglia meno e si testa.
• Tool troppo potenti. Un agente con accesso in scrittura al database è un incidente che aspetta il momento giusto. Permessi minimi, azioni reversibili, conferma umana sulle operazioni distruttive.
• Nessuna valutazione. Se il criterio è “sembra funzionare”, non hai un sistema, hai una sensazione con l’API key.
• Prompt monstre. Un prompt da duemila parole che prova a gestire dieci casi è più fragile di cinque nodi piccoli con un compito ciascuno.

Se stai iniziando adesso, il mio consiglio è di prendere un processo che conosci a memoria, con un inizio e una fine chiari, poi automatizzane solo la parte centrale. Un agente che compila una scheda è utile dal primo giorno. Un agente che “ottimizza l’azienda” non esiste. Se qualcuno te lo vende, chiedigli il grafo.

Domande frequenti su LangChain e LangGraph

LangChain e LangGraph sono gratuiti?

Sì, entrambi sono open source con licenza MIT, quindi puoi usarli anche in progetti commerciali. I costi veri sono i modelli, l’infrastruttura e, se lo usi, il piano di LangSmith. La piattaforma di osservabilità ha un livello gratuito e piani a pagamento in base ai trace registrati.

Serve sapere Python per usarli?

Per la versione principale sì, ma non serve essere sviluppatori senior. Bastano funzioni, dizionari e un po’ di asincrono. Esiste anche la versione TypeScript per chi lavora su Node, con le stesse idee di fondo e qualche differenza nelle integrazioni.

Posso usarli con un modello locale?

Sì. Funzionano con Ollama, vLLM e con qualunque endpoint compatibile con l’API di OpenAI. È la strada giusta quando i dati non possono uscire dall’azienda, accettando che un modello locale piccolo sarà meno preciso su compiti di ragionamento complesso.

Meglio LangChain o scrivere tutto a mano?

Dipende dal numero di pezzi che devi tenere insieme. Per un singolo strumento e un solo provider, duecento righe tue sono più chiare di qualsiasi framework. Quando arrivano più provider, memoria, streaming, retry e osservabilità, riscriverli a mano diventa un progetto dentro il progetto.

LangGraph sostituisce LangChain?

No. Nemmeno il contrario. LangGraph è il runtime che esegue il grafo, LangChain è il livello con cui costruisci gli agenti e parli con i modelli. Nella pratica li usi insieme: il grafo orchestrazione, gli agenti dentro i nodi.

Il modo più onesto per capire se ti servono è provarli su un caso piccolo e noioso, di quelli che nessuno mette nelle demo. Se in una settimana ti ha tolto un’ora di lavoro ripetitivo e non ti ha fatto litigare con i log, allora vale la pena allargare. Se ti ha chiesto più tempo di quanto ne ha risparmiato, hai imparato qualcosa di utile comunque: il processo non era pronto, oppure non era il processo giusto.