LangGraph: Guida Pratica per Costruire Agenti AI Multi-Step in Python

LangGraph è un framework open-source sviluppato dal team di LangChain per costruire agenti AI stateful utilizzando grafi ciclici. A differenza delle chain lineari di LangChain, LangGraph permette di modellare workflow complessi dove un agente può tornare indietro, prendere decisioni condizionali e orchestrare più strumenti in parallelo.

Perché LangGraph? Quando un task AI va oltre il semplice prompt → risposta, serve un'architettura che supporti cicli, memoria e decisioni condizionali. Esempi concreti: un assistente che ricerca informazioni, le valida, e se non sono sufficienti torna a cercare; un agente che compila un report interrogando più API in sequenza; un sistema RAG che decide autonomamente se la risposta è abbastanza accurata.

Concetti chiave di LangGraph. StateGraph: il contenitore principale che definisce lo stato condiviso tra tutti i nodi. Ogni nodo è una funzione Python che riceve lo stato, lo modifica e lo restituisce. Gli edge (archi) definiscono le transizioni, che possono essere condizionali. Il checkpointer salva lo stato tra le esecuzioni, abilitando conversazioni multi-turno e recovery da errori.

Architettura di un agente LangGraph. Il pattern più comune è il ReAct agent: (1) il nodo 'agent' riceve l'input e decide se usare un tool o rispondere direttamente; (2) se serve un tool, il nodo 'tools' lo esegue e restituisce il risultato; (3) l'agente valuta il risultato e decide se servono altri step o se può generare la risposta finale. Questo ciclo si ripete finché l'agente non è soddisfatto.

Tool-calling: l'arma segreta. LangGraph permette di definire tool tipizzati con Pydantic che l'LLM può invocare. Esempio: un tool che interroga il tuo database PostgreSQL, uno che chiama un'API esterna, uno che invia email. L'agente decide autonomamente quale tool usare e in che ordine, basandosi sul contesto della conversazione.

Human-in-the-loop. Una delle feature più potenti di LangGraph è il supporto nativo per l'intervento umano. Puoi configurare checkpoint dove l'agente si ferma e chiede approvazione prima di procedere — fondamentale in contesti aziendali dove certe azioni (come inviare un'email a un cliente o modificare un ordine) richiedono supervisione.

Memoria e persistenza. Con i checkpointer (SQLite, PostgreSQL, Redis), LangGraph mantiene lo stato della conversazione tra sessioni diverse. Questo significa che l'agente 'ricorda' le interazioni precedenti, le preferenze dell'utente e il contesto — essenziale per assistenti aziendali che devono gestire relazioni continuative.

Quando usare LangGraph vs LangChain LCEL. LangChain LCEL (LangChain Expression Language) è perfetto per pipeline lineari: prompt → LLM → parser → output. LangGraph è la scelta giusta quando servono cicli, decisioni condizionali, multi-agent coordination o stato persistente. In pratica, LangGraph si usa per tutto ciò che richiede un 'agente' che ragiona e agisce.

Deployment in produzione. Per il deploy, LangGraph si integra con LangServe per esporre l'agente come API REST, oppure si può containerizzare con Docker e deployare su Azure, AWS o qualsiasi cloud. Il monitoring si fa con LangSmith, che traccia ogni step dell'agente, i costi dei token e le latenze.

Se la tua azienda vuole integrare agenti AI nei propri processi, LangGraph è il framework che noi di CSF Labs utilizziamo per costruire soluzioni production-ready. Dalla consulenza iniziale al deploy, progettiamo agenti su misura per le esigenze specifiche del tuo business.