LangGraph 1.2.20 è stato pubblicato il 5 novembre 2026 e i tracker di release segnalano già una 1.2.21 per il 13 novembre. La linea 1.x ha fissato le API del grafo e il modello di esecuzione, quindi il codice scritto oggi con LangGraph non invecchia a ogni aggiornamento minore. Per un progetto in produzione è la differenza tra un esperimento e un componente su cui puntare.
Perché LangGraph è utile
Un agente utile fa tre cose che uno script con un ciclo while gestisce male: ricorda dove si è fermato, attende una persona senza tenere un processo acceso per ore e riparte dallo stesso punto dopo un riavvio del server. LangGraph risolve questi tre problemi con tre concetti fondamentali: stato esplicito, checkpoint e interruzioni. Imparare LangGraph in Python significa, in pratica, imparare a usarli bene.
Il caso di studio
Il tutorial costruisce un agente di triage per ticket di assistenza clienti. L’agente classifica ogni messaggio in spam, urgente o standard, cerca le regole aziendali pertinenti, scrive una bozza di risposta e si ferma in attesa di un operatore, che può approvare, modificare, rigenerare o rifiutare. Tutto gira in locale, con SQLite come memoria durevole e con test automatici che non chiamano modelli a pagamento.
Cos’è LangGraph e quando usarlo
LangGraph è un framework open source per costruire agenti come grafi di nodi. Ogni nodo è una funzione Python che riceve lo stato corrente e restituisce un aggiornamento parziale. Gli archi decidono quale nodo gira dopo, in modo fisso oppure in base al contenuto dello stato. Il runtime si occupa del resto: applica gli aggiornamenti, salva i checkpoint, gestisce le pause e i tentativi ripetuti.
La documentazione descrive LangGraph v1 come una release orientata alla stabilità, che conserva le API del grafo e il modello di esecuzione e migliora tipizzazione ed ergonomia. La 1.0 è stata rilasciata il 22 ottobre 2025, la 1.1 ha aggiunto a marzo 2026 streaming e invocazione tipizzati con coercizione di Pydantic e dataclass, senza rompere la compatibilità. La politica di rilascio prevede major ogni 6‑12 mesi, minor ogni 1‑2 mesi e patch frequenti, spesso settimanali.
LangGraph vs LangChain
LangChain v1 offre createagent, un’API di alto livello costruita sopra LangGraph. La documentazione la indica al posto di langgraph.prebuilt.createreactagent come punto di partenza consigliato. Le funzioni legacy sono finite nel pacchetto langchain-classic. Se un tutorial online importa createreact_agent o usa i vecchi AgentExecutor, trattalo come storico e controlla la guida alla migrazione.
Quando scegliere LangGraph diretto e quando fermarsi a create_agent? La tabella seguente riassume il criterio usato nei progetti reali:
- Approccio: ciclo
whilecon chiamate al modello – totale, ma tutto a mano; da scrivere e mantenere da soli – prototipo da un pomeriggio. - create_agent di LangChain: il modello sceglie gli strumenti in un ciclo standard; middleware per approvare, modificare o rifiutare le chiamate – agente con strumenti e flusso aperto.
- Grafo LangGraph esplicito: archi e condizioni dichiarati nel codice; checkpoint e
interrupt()nativi – flusso con passaggi obbligati e approvazioni. - LangGraph con sottografi: grafi annidati con stato proprio; checkpoint condivisi tra i livelli – processi lunghi con più squadre di agenti, orchestrazione fatta in casa.
- Dipende dal team: vincoli che nessun framework copre.
Contesto di mercato
Nel sondaggio Gartner di settembre 2025, secondo il comunicato dell’istituto, “Solo il 15% dei responsabili IT applicativi sta valutando, sperimentando o implementando agenti AI completamente autonomi, cioè strumenti orientati agli obiettivi che non richiedono supervisione umana.” La maggior parte delle aziende vuole agenti con una persona nel circuito, il caso d’uso in cui LangGraph eccelle perché la pausa per l’approvazione è un elemento nativo del grafo, non un’aggiunta fragile.
Prerequisiti e versioni da installare
Servono Python, un terminale e un modello linguistico raggiungibile da LangChain. Il modello può essere locale (Ollama o qualunque server compatibile) oppure un’API a pagamento. Il tutorial non dipende da un fornitore: l’identificatore del modello sta in una variabile d’ambiente e i test usano un modello finto, quindi è possibile completare il percorso anche senza chiavi API.
Componenti richiesti:
- Python 3.11 o successivo (gli esempi usano 3.12).
- langgraph >=1.2,<2 (1.2.20 o superiore, test anche su 1.2.21).
- langchain >=1.5,<2 (release 11 novembre 2026, fornisce
initchatmodel). - langchain-core >=1.8 (include i modelli finti usati nei test).
- langgraph-checkpoint-sqlite (pacchetto separato).
- pacchetto del fornitore, es.
langchain-ollamaolangchain-anthropic. - python-dotenv e pytest (ultime versioni).
Nota: la riga della 1.2.21 va letta con prudenza: il registro ufficiale dei pacchetti resta il riferimento finale, quindi nel file dei requisiti il vincolo è >=1.2,<2 e non una versione esatta. Se il tuo ambiente ha ancora Python 3.10, aggiornalo prima di installare qualsiasi altra cosa: pip potrebbe selezionare pacchetti più vecchi senza avvisarti.
Passo 1 – Creare l’ambiente virtuale
Crea una cartella dedicata e un ambiente virtuale. Isolare le dipendenze evita il guaio più comune dell’ecosistema, cioè un vecchio langchain 0.x che convive con langgraph 1.x e produce errori di importazione incomprensibili.
mkdir triage-agent && cd triage-agent
python3 -m venv .venv
source .venv/bin/activate # su Windows: .venv\Scripts\activate
python --version
Il comando python --version deve stampare 3.11 o una versione successiva. Poi crea il file requirements.txt e installa tutto in un colpo solo.
langgraph>=1.2,<2
langchain>=1.5,<2
langgraph-checkpoint-sqlite
python-dotenv
pytest
Installa i pacchetti:
pip install -r requirements.txt
pip install langchain-ollama # oppure il pacchetto del tuo fornitore
pip list | grep -i -E "langgraph|langchain"
L’ultimo comando elenca le versioni installate. Controlla che compaiano langgraph, langchain, langchain-core e langgraph-checkpoint-sqlite. Se manca il pacchetto del checkpoint, il Passo 7 fallirà con un ModuleNotFoundError.
Passo 2 – Strutturare il progetto
Il progetto si divide in un pacchetto triage con quattro moduli (stato, modello, nodi, grafo), uno script run.py da riga di comando e una cartella tests. Separare i nodi dal grafo sembra burocrazia finché non scrivi i test: i nodi diventano funzioni pure da provare una per una, il grafo resta un file di sole connessioni che si legge in trenta secondi.
triage-agent/
├── .env # MODEL_ID e chiavi, mai nel repository
├── requirements.txt
├── run.py # interfaccia a riga di comando
├── triage/
│ ├── _init_.py
│ ├── stato.py # definizione della classe State e metodi di persistenza
│ ├── modello.py # wrapper per il modello linguistico
│ ├── nodi.py # funzioni pure per classificazione, regole, risposta
│ └── grafo.py # definizione del grafo LangGraph
├── tests/
│ ├── conftest.py
│ ├── test_nodi.py
│ └── test_grafo.py
└── README.md
Il file .env contiene MODEL_ID e eventuali chiavi API, ma non deve mai essere committato.
Passo 3 – Definire lo stato
In stato.py creiamo una dataclass che contiene tutti gli attributi necessari: ticketid, messaggio, categoria, bozzarisposta, approvazione e un flag interrupted. Aggiungiamo metodi per caricare e salvare su SQLite usando sqlite3 e pydantic per la validazione.
Passo 4 – Wrapper del modello
In modello.py usiamo langchain per creare un ChatModel generico. L’identificatore del modello è letto da os.getenv("MODELID"). Per i test, impostiamo MODELID=dummy e usiamo langchain-core per restituire risposte fittizie.
Passo 5 – Implementare i nodi
Nel file nodi.py definiamo le funzioni:
classifica_messaggio(state: State) -> dict: usa il modello per classificare in spam/urgente/standard.trova_regole(state: State) -> dict: ricerca regole aziendali in un file JSON.genera_bozza(state: State) -> dict: costruisce una risposta basata su template.attendi_approvazione(state: State) -> dict: impostainterrupted=Truee salva il checkpoint.processa_risposta(state: State) -> dict: gestisce approvazione, modifica o rigenerazione.
Ciascuna funzione restituisce solo le parti di stato modificate, rispettando il modello di aggiornamento parziale di LangGraph.
Passo 6 – Costruire il grafo
In grafo.py importiamo StateGraph da langgraph e colleghiamo i nodi:
graph = StateGraph(State)
graph.addnode("classifica", classificamessaggio)
graph.addnode("regole", trovaregole)
graph.addnode("bozza", generabozza)
graph.addnode("attendi", attendiapprovazione)
graph.addnode("processa", processarisposta)
graph.setentrypoint("classifica")
graph.add_edge("classifica", "regole")
graph.add_edge("regole", "bozza")
graph.add_edge("bozza", "attendi")
graph.addconditionaledges(
"attendi",
lambda state: "approvata" if state.approvazione == "yes" else "modifica",
{"approvata": "processa", "modifica": "bozza"}
)
graph.add_edge("processa", "END")
graph.compile()
Il runtime gestisce i checkpoint automaticamente grazie al pacchetto langgraph-checkpoint-sqlite, che persiste lo stato in un file checkpoints.db.
Passi 7‑12 – Esecuzione, testing e deployment
Passo 7 – Test unitari: in tests/testnodi.py usiamo pytest per verificare che ogni nodo produca l’output atteso dato un input di esempio. In tests/testgrafo.py simuliamo un flusso completo e controlliamo che il checkpoint venga salvato e ripristinato correttamente.
Passo 8 – Script di esecuzione: run.py carica le variabili d’ambiente, crea il grafo e chiama graph.invoke({"ticket_id": 123, "messaggio": "..."} ). Se il grafo si interrompe, lo script stampa un messaggio e termina; l’operatore può quindi approvare via console o API.
Passo 9 – Gestione delle interruzioni: l’operatore interagisce con un semplice endpoint FastAPI che legge lo stato dal checkpoint e aggiorna il campo approvazione. Una volta aggiornato, il grafo può essere ripreso con graph.resume().
Passo 10 – Deploy locale: il progetto può essere containerizzato con Docker. Il Dockerfile copia il codice, installa le dipendenze e avvia uvicorn run:app. Il volume Docker monta la cartella checkpoints.db per persistenza.
Passo 11 – Monitoraggio: aggiungi logging con structlog nei nodi e nel grafo per tracciare transizioni, errori e tempi di esecuzione. I log possono essere inviati a un servizio come Loki o a CloudWatch.
Passo 12 – Aggiornamenti futuri: grazie alla stabilità dell’API 1.x, quando uscirà la 1.2.22 o la 1.3.0 potrai aggiornare con pip install --upgrade langgraph senza modificare il codice. Solo in caso di salto a 2.0 sarà necessario rivedere la definizione del grafo.
Con questi dodici passi hai una pipeline completa, resistente a riavvii, capace di gestire approvazioni umane e pronta per essere integrata in un sistema di ticketing aziendale. LangGraph ti offre il controllo fine‑grained del flusso, la persistenza dei checkpoint e la possibilità di annidare grafi per scenari più complessi, rendendo gli agenti AI davvero pronti per la produzione.