OpenAI Agents SDK vs LangGraph: confronto pratico per scegliere il framework

Un team costruisce con LangGraph un prototipo di agent per il customer support. Quando lo fa girare, scopre che la maggior parte dei nodi fa la stessa cosa: chiama un modello e poi uno strumento. Il codice è ordinato, ma il boilerplate pesa. A quel punto nasce la domanda: si può passare a OpenAI Agents SDK e togliere quello strato?

Un altro scenario è più delicato. Un reporting agent gira ogni giorno per 20 minuti e, a metà, deve aspettare che una persona approvi la SQL prima di continuare. Qui “meno codice” non è più l’unico criterio. Pausa, ripresa e audit diventano centrali. OpenAI Agents SDK ha sessions e guardrail, ma può sostituire checkpoint e interrupt di LangGraph?

I due casi portano alla stessa domanda: OpenAI Agents SDK sembra leggero, ma può davvero sostituire LangGraph o solo una parte del lavoro? La vera decisione è capire se il tuo agent ha bisogno solo di modelli, strumenti e delega, oppure se richiede già stato persistente, pause umane, esecuzione riprendibile e replay per audit.

Prima chiarisci il livello: non sono la stessa astrazione

Prima di parlare di sostituzione, conviene separare i ruoli. OpenAI descrive Agents SDK come un toolkit leggero, semplice da usare e con poche astrazioni per creare agentic app. Il suo centro è agent loop, tool call, handoff, guardrail e tracing. LangGraph si presenta come infrastruttura di orchestrazione low-level per workflow lunghi e stateful. Il suo centro è grafo di stato esplicito, persistenza con checkpoint, interrupt, resume, time travel e fault tolerance.

Uno assomiglia di più a un runtime di conversazione e delega. L’altro assomiglia di più a una macchina a stati diretta. La differenza di astrazione si vede qui:

La tabella mostra la separazione principale: Agents SDK è più vicino a primitive di runtime agent, mentre LangGraph è più vicino a orchestrazione di workflow con stato. Se ti serve solo un agent loop che chiama strumenti e ogni tanto delega a un agent specialista, Agents SDK può bastare. Se il task deve fermarsi, riprendere, essere auditabile o continuare dopo un errore, checkpoint e interrupt di LangGraph diventano il punto chiave.

Non è una gara a chi è più forte. Stanno lavorando su livelli diversi. Agents SDK è come un SDK con tracing per eseguire agent. LangGraph è come un motore di macchina a stati con persistenza. Se il tuo processo si può disegnare come transizioni di stato chiare, LangGraph è più adatto. Se è quasi sempre “modello + strumenti + escalation occasionale”, Agents SDK può essere più leggero. Per il confine tra prompt e macchine a stati, puoi leggere anche macchine a stati per agent e limiti dei workflow.

Matrice delle capacità: 10 dimensioni pratiche

Livelli di astrazione diversi non impediscono un confronto concreto. La tabella seguente confronta i due framework su 10 dimensioni ingegneristiche:

Le differenze più importanti sono persistenza dello stato, recupero da errori e workflow riproducibili. Le sessions di Agents SDK servono alla continuità della conversazione. I checkpointer di LangGraph salvano l’intero stato del grafo: storico dei nodi, variabili intermedie e input esterni in attesa. Se un reporting agent si blocca a metà, Agents SDK di solito deve ripartire dall’inizio. LangGraph può continuare dall’ultimo checkpoint ed evitare di ripetere i passaggi già completati.

Un’altra differenza chiave è HITL. Agents SDK ha guardrail e una HITL API, utili per controllare input e output, ma il meccanismo dei guardrail è un tripwire: quando scatta, l’esecuzione si ferma. Gli interrupt di LangGraph sono pause della macchina a stati. interrupt() può fermarsi dentro un nodo, il checkpointer salva lo stato corrente e poi si riprende con Command(resume=...). Questo permette a LangGraph di fermarsi prima di un tool call, aspettare l’approvazione e continuare. I guardrail di Agents SDK sono più adatti a “ferma se l’input è fuori scope” che a “pausa, revisione e poi continua”. Per il confine completo, vedi design delle approvazioni human-in-the-loop per agent.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

La terza differenza è il replay. Il time travel di LangGraph permette di tornare a qualsiasi checkpoint, ispezionare stato e percorso di esecuzione, e fare debug o audit. Il tracing di Agents SDK visualizza il percorso, ma non torna a uno stato storico per rieseguire da lì. Se devi rispondere a “perché ha preso quel ramo due ore fa?”, LangGraph è più adatto.

Cosa offre Agents SDK: primitive principali

OpenAI Agents SDK ruota attorno a cinque primitive: Agents, Handoffs, Guardrails, Tracing e Sessions/HITL/MCP. In pratica:

Agents: un agent combina un LLM, instructions, tools e comportamento runtime opzionale. Il comportamento include handoff verso altri agent, guardrail per controlli input/output e structured outputs per imporre un formato. Agent e Runner lavorano insieme: il SDK gestisce agent loop, turns, tool call, guardrail checks e delega tramite handoff.

Handoffs: un handoff permette a un agent di delegare lavoro a un altro agent. In pratica, l’agent di destinazione viene esposto al LLM come strumento. handoff() può configurare agent di destinazione, nome e descrizione dello strumento, on_handoff, input_type, input_filter e is_enabled. Funziona bene con specialisti: un agent di supporto classifica il problema e passa al supporto tecnico o alla ricerca ordini.

Guardrails: i guardrail operano su due livelli: input e output. Gli input guardrails controllano l’input utente prima che entri nell’agent. Gli output guardrails controllano la risposta prima che venga restituita. Un tripwire ferma l’esecuzione. È utile per “ferma se l’input è fuori ambito” o “blocca un output con dati sensibili”. Gli esempi ufficiali usano un modello più rapido per verificare se la richiesta è nel perimetro.

Tracing: il SDK include tracing per LLM generations, tool calls, handoffs, guardrail checks e custom events dentro un agent run. Ogni span registra tempi e metadata, utili per debug, visualizzazione e monitoraggio dei workflow. Il tracing è attivo di default, e trace_include_sensitive_data controlla se registrare campi sensibili.

Sessions, HITL e MCP tools: le sessions danno continuità alla conversazione. Più run con lo stesso session_id condividono lo storico. La HITL API può attendere input esterno durante l’esecuzione, ma il suo modello di interruzione non è la stessa astrazione degli interrupt di LangGraph. Gli MCP tools permettono a un agent di chiamare strumenti esposti da MCP servers, gestiti come function tools.

Queste primitive coprono agent loop, tool calling, delega, validazione, tracing e continuità della conversazione. Non offrono però un grafo di stato esplicito, persistenza con checkpoint, interrupt, resume, time travel o fault tolerance. Se il tuo caso è “modello + strumenti + delega occasionale”, Agents SDK può bastare. Se richiede “pausa per approvazione + ripresa + continuazione dopo errore + audit dello stato”, LangGraph è più adatto.

I punti forti di LangGraph: meccanismi di stato

I punti forti di LangGraph sono gestione dello stato e recovery: Checkpointers, Interrupts, Time travel, Fault tolerance e Stores. In pratica:

Checkpointers: i checkpointer salvano thread graph state come checkpoint. Includono storico dei nodi, variabili intermedie, input esterni in attesa e posizione corrente. Ogni checkpoint è uno snapshot completo dello stato, usato per continuità di conversazione, HITL, time travel e fault tolerance. La documentazione distingue chiaramente sessions di Agents SDK e checkpointer di LangGraph: le sessions mantengono la conversazione, i checkpointer salvano snapshot dello stato del grafo.

Interrupts: interrupt() può mettere in pausa l’esecuzione dentro un graph node. Il checkpointer salva lo stato corrente e attende input esterno. La ripresa usa Command(resume=...), e lo stesso thread_id funziona da cursore persistente. La documentazione cita pattern come approval workflows, review/edit state, interrupting tool calls e validating human input. Non è la stessa cosa dei guardrail tripwire di Agents SDK: un interrupt mette in pausa la macchina a stati, un guardrail ferma l’esecuzione.

Time travel: time travel permette di tornare a qualsiasi checkpoint e vedere stato e percorso di esecuzione in quel momento. Serve per audit, debug e riproduzione di problemi, ad esempio “perché ha preso questo ramo due ore fa?”. Il tracing di Agents SDK visualizza il percorso, ma non riesegue da uno stato storico.

Fault tolerance: fault tolerance significa continuare dopo un errore. Se un reporting agent si ferma a metà, LangGraph può riprendere dall’ultimo checkpoint ed evitare di ripetere passaggi conclusi. Agents SDK non ha fault tolerance integrata, quindi di solito il run riparte dall’inizio.

Stores: gli stores salvano dati di lungo periodo tra thread, come preferenze utente, cronologia o stato di business. La documentazione distingue stores e checkpointers: i checkpointers salvano thread graph state, gli stores salvano dati persistenti tra thread. Se più agent run devono condividere stato, stores è lo strato giusto.

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

Questi meccanismi rendono LangGraph adatto a long-running, stateful workflow: attività lunghe, più rami, esecuzione riprendibile, stato auditabile e intervento umano. Se il progetto ha già questi requisiti, la complessità di LangGraph è giustificata. Se è solo un tool agent semplice o uno specialist handoff, Agents SDK è più leggero.

Quando usare Agents SDK

In base alla matrice e alle primitive, Agents SDK è più adatto a questi scenari:

1. Tool agent semplici: ricerca, sintesi ed escalation occasionale a una persona. Per esempio, un agent Q&A su knowledge base interna recupera documenti, sintetizza una risposta e, se non è sicuro, invita l’utente a contattare il supporto. Non servono recovery di stato complesse né workflow di approvazione; tools, handoff e guardrail di Agents SDK possono bastare.

2. Handoff a più specialisti: scenari in cui il lavoro viene delegato a più agent specializzati. Un agent di customer support classifica il problema e poi lo passa a supporto tecnico, ricerca ordine o rimborso. Gli handoff di Agents SDK sono letteralmente “agent as tool”, quindi il pattern si adatta bene.

3. Prototipi rapidi: progetti che devono validare un’idea senza disegnare subito un grafo di stato esplicito. Agents SDK richiede meno codice e parte più in fretta. Se il prototipo mostra che checkpoint o interrupt non servono, può andare in produzione con Agents SDK.

4. Aderenza all’ecosistema OpenAI: se il progetto usa soprattutto modelli OpenAI, Responses API o OpenAI hosted tools, Agents SDK è il toolkit ufficiale e l’integrazione è più fluida. Agent vocali in tempo reale, sandbox agents o strumenti ospitati da OpenAI sono esempi naturali.

5. Esiste già un altro strato di stato: se il progetto usa già database di business, queue o workflow engine per gestire lo stato, Agents SDK può eseguire solo l’agent loop. Un nodo usa Agents SDK per chiamare strumenti, mentre database e coda possiedono lo stato.

Il pattern comune è semplice: niente grafo di stato esplicito, niente persistenza con checkpoint, niente interrupt + resume, niente time travel. Se il progetto corrisponde a questo profilo, partire da Agents SDK può risparmiare lavoro.

Quando mantenere LangGraph

Se il progetto rientra nei casi seguenti, la complessità di LangGraph probabilmente vale il costo:

1. Attività lunghe (20+ minuti): reporting agent, elaborazione dati o analisi complesse possono durare più di 20 minuti e bloccarsi o andare in timeout. Checkpointers e fault tolerance di LangGraph permettono di continuare dall’ultimo checkpoint. Agents SDK non ha fault tolerance integrata e di solito riesegue dall’inizio.

2. Serve approvazione umana: scenari di tool call interrupt, come eliminare dati, inviare email o modificare permessi, richiedono approvazione prima di continuare. Gli interrupt di LangGraph possono fermarsi prima del tool call, salvare lo stato tramite checkpointer e riprendere con Command(resume=...). I guardrail di Agents SDK sono “scatta e ferma”, non “pausa per revisione e continua”.

3. Serve stato auditabile: alcuni sistemi devono riprodurre stati storici, controllare percorsi di esecuzione o auditare decisioni. Una domanda di compliance come “perché ha preso questo ramo due ore fa?” richiede più di un trace. Time travel di LangGraph torna a un checkpoint; tracing di Agents SDK mostra il percorso, ma non riesegue da uno stato storico.

4. L’esecuzione deve continuare dopo errori: se un agent si blocca a metà run o cade la rete, il sistema deve continuare invece di ricominciare. Fault tolerance di LangGraph riprende dal checkpoint. Agents SDK riparte dall’inizio. Se il task ha dipendenze esterne come chiamate API o scritture su database che non devono essere ripetute, questa differenza è critica.

5. Più rami, routing condizionale o macchina a stati di business: workflow con stati espliciti, condizioni o transizioni di business si adattano meglio a LangGraph. Un esempio è l’elaborazione ordini: pagamento riuscito -> spedizione; pagamento fallito -> annullamento; pagamento scaduto -> intervento umano. Questo processo è più chiaro come grafo di stato esplicito; gli handoff di Agents SDK sono per la delega, non per routing complesso.

Il requisito comune è lo stato esplicito: persistenza con checkpoint, interrupt, resume, time travel o fault tolerance. Se il progetto lo richiede, la complessità di LangGraph non è overhead; è parte della sicurezza del sistema.

Decisione di sostituzione: checklist in quattro passaggi

Anche dopo questi scenari, la decisione può restare sfumata. Usa questa checklist:

Passaggio 1: elenca i requisiti principali

Dividi il requisito in capacità concrete: tool calling, recovery dello stato, approvazione umana, attività lunghe, branching, replay per audit e recupero da errori. Non scrivere solo “ci serve un agent”. Rendilo concreto. “Un reporting agent gira 20 minuti, aspetta approvazione SQL e deve continuare dopo un crash” sono tre requisiti: attività lunga, approvazione e recovery.

Passaggio 2: mappa i requisiti forti sulla matrice

Prendi la lista del passaggio 1 e mappala sulle 10 dimensioni. “Attività lunga + approvazione + recovery” corrisponde a persistenza dello stato, HITL e recupero da errori. Agents SDK è debole o assente su queste dimensioni, mentre LangGraph è forte. Se i requisiti forti cadono nelle debolezze di Agents SDK, la sostituzione probabilmente non è adatta.

Passaggio 3: decidi se serve un grafo di stato esplicito

Fai una domanda: il mio processo può essere disegnato come transizioni di stato chiare? Se sì, per esempio un ordine con successo, errore, timeout e passaggi successivi, il grafo di stato esplicito di LangGraph è più adatto. Se il processo è soprattutto “modello + strumenti + delega occasionale” senza flusso fisso, Agents SDK può essere più leggero.

Railway - Piattaforma di deploy moderna, senza operazioni complesse, online in pochi minuti

Inizia ora →Pubbl.

Passaggio 4: valuta la tolleranza del team alla complessità

LangGraph richiede progettazione di grafi, stato e nodi. Se il team ha poca tolleranza per la complessità, inizia con un prototipo Agents SDK e aggiungi uno strato di stato solo quando serve. Se il team ha già esperienza con workflow o macchine a stati, la complessità di LangGraph può non essere un problema.

Dopo questi quattro passaggi, dovresti poter scegliere Agents SDK, LangGraph o un ibrido. Se stai ancora facendo una scelta più ampia tra framework, usa anche la checklist di ingegneria AI Agent 2026.

Percorsi di migrazione per progetti LangGraph esistenti

Se hai già un prototipo LangGraph e vuoi ridurre parte della complessità con Agents SDK, usa questa tabella:

Se usi già Agents SDK e vuoi capire quando passare a LangGraph, usa questa tabella:

Esempio di pattern ibrido: non devi sostituire tutto. LangGraph può gestire il grafo di stato esterno, mentre un nodo usa Agents SDK per eseguire un agent di breve durata. Un reporting agent può tenere il flusso principale in LangGraph: preparazione dati -> generazione SQL -> approvazione umana -> esecuzione query -> export. I nodi di generazione SQL ed export non hanno bisogno di checkpoint o interrupt propri, quindi possono usare agent loop e tool call di Agents SDK, mentre LangGraph mantiene lo stato.

La chiave è la responsabilità: LangGraph possiede lo strato di stato; Agents SDK può eseguire nodi brevi. Non è una scelta secca, ma una distribuzione in base ai punti forti.

Conclusione

OpenAI Agents SDK e LangGraph non sono una scelta binaria. La domanda vera è se ti serve uno strato di stato. Se il progetto richiede solo agent loop, tool call, delega e validazione, come Q&A su knowledge base, triage di supporto o prototipo rapido, parti da Agents SDK. È più leggero e più rapido da mettere in piedi. Se il progetto richiede recovery di attività lunghe, approvazione umana, audit dello stato o continuazione dopo errori, come reporting agent, workflow ordini o processi di compliance, checkpoint, interrupt, time travel e fault tolerance di LangGraph sono capacità necessarie.

Non devi forzare una sostituzione. Un ibrido pratico è lasciare a LangGraph il grafo di stato esterno e usare Agents SDK per i nodi brevi. La decisione parte dai requisiti: elenca i bisogni principali, mappa quelli forti sulla matrice e poi decidi se mantenere, sostituire o combinare.

Passo successivo: se hai già un prototipo LangGraph, usa la tabella di migrazione per identificare quali nodi possono passare ad Agents SDK. Se stai ancora scegliendo il framework, usa la checklist in quattro passaggi per decidere prima se il progetto richiede un grafo di stato esplicito.