OpenAI Agents SDK vs LangGraph : comparaison pratique pour choisir le bon framework

Une équipe construit un prototype d’agent de support client avec LangGraph. Une fois le prototype lancé, elle constate que la plupart des nodes font la même chose : appeler un modèle, puis appeler un outil. Le code est propre, mais le boilerplate prend de la place. La question arrive naturellement : peut-on remplacer cette couche par OpenAI Agents SDK ?

Un autre cas est plus délicat. Un agent de reporting tourne 20 minutes chaque jour et doit attendre qu’un humain approuve le SQL avant de continuer. À ce moment-là, « moins de code » n’est plus le seul critère. La pause, la reprise et l’audit deviennent essentiels. OpenAI Agents SDK propose des sessions et des guardrails, mais peut-il remplacer les checkpoints et interrupts de LangGraph ?

Ces deux situations mènent à la même question : OpenAI Agents SDK paraît léger, mais peut-il vraiment remplacer LangGraph, ou seulement une partie des usages ? Le vrai point à trancher est simple : votre agent a-t-il seulement besoin de modèles, d’outils et de délégation, ou a-t-il déjà besoin d’état persistant, de pauses humaines, d’exécution reprise et de replay auditables ?

Clarifier la couche : ce ne sont pas les mêmes abstractions

Avant de parler remplacement, il faut séparer les rôles. OpenAI décrit Agents SDK comme un toolkit léger, facile à utiliser et peu abstrait pour construire des applications agentic. Son centre de gravité : agent loop, tool calls, handoff, guardrails et tracing. LangGraph se présente comme une infrastructure d’orchestration bas niveau pour workflows longs et stateful. Son centre de gravité : graphes d’état explicites, persistance par checkpoint, interrupts, resume, time travel et fault tolerance.

L’un ressemble davantage à un runtime de conversation et de délégation. L’autre ressemble davantage à une machine à états orientée graphe. La différence d’abstraction se voit ici :

La table montre le point clé : Agents SDK est plus proche des primitives de runtime agent, tandis que LangGraph est plus proche d’une orchestration de workflow stateful. Si vous avez seulement besoin d’un agent loop qui appelle des outils et délègue parfois à un agent spécialiste, Agents SDK peut suffire. Si la tâche doit se mettre en pause, reprendre, être auditée ou continuer après un incident, les checkpoints et interrupts de LangGraph deviennent centraux.

Ce n’est pas une question de « plus fort ». Les deux outils ne jouent pas au même niveau. Agents SDK ressemble à un SDK avec tracing pour faire tourner des agents. LangGraph ressemble à un moteur de machine à états avec une couche de persistance. Si votre processus peut être dessiné comme des transitions d’état claires, LangGraph est plus adapté. Si c’est surtout « modèle + outils + escalade occasionnelle », Agents SDK peut être plus léger. Pour la frontière entre prompts et machines à états, voir aussi les machines à états d’agent et les limites du workflow.

Matrice de capacités : 10 dimensions pratiques

Des abstractions différentes n’empêchent pas une comparaison concrète. Voici les deux frameworks sur 10 dimensions d’ingénierie :

Les écarts les plus importants concernent la persistance d’état, la reprise après échec et les workflows rejouables. Les sessions d’Agents SDK servent à garder la continuité de conversation. Les checkpointers LangGraph sauvegardent l’état complet du graphe : historique des nodes, variables intermédiaires et entrées externes en attente. Si un agent de reporting plante au milieu d’une exécution, Agents SDK doit généralement repartir de zéro. LangGraph peut reprendre au dernier checkpoint et éviter de répéter les étapes déjà terminées.

Le HITL est une autre différence majeure. Agents SDK propose des guardrails et une HITL API, utiles pour vérifier les entrées et sorties, mais le mécanisme de guardrail est un tripwire : quand il se déclenche, l’exécution s’arrête. Les interrupts LangGraph sont des pauses de machine à états. interrupt() peut suspendre un node, le checkpointer enregistre l’état courant, puis l’exécution reprend plus tard avec Command(resume=...). LangGraph peut donc s’arrêter avant un tool call, attendre une approbation, puis continuer. Les guardrails d’Agents SDK conviennent mieux à « arrêter si l’entrée est hors scope » qu’à « attendre une revue humaine puis continuer ». Pour approfondir cette frontière, voir la conception des approbations human-in-the-loop pour agents.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Troisième écart : le replay. Le time travel de LangGraph permet de revenir à n’importe quel checkpoint, d’inspecter l’état et le chemin d’exécution, puis de déboguer ou auditer. Le tracing d’Agents SDK visualise le chemin d’exécution, mais ne revient pas à un état historique pour relancer depuis ce point. Si votre scénario inclut « pourquoi a-t-il pris cette branche il y a deux heures ? », LangGraph est plus adapté.

Ce que fournit Agents SDK : les primitives centrales

OpenAI Agents SDK repose sur cinq blocs : Agents, Handoffs, Guardrails, Tracing et Sessions/HITL/MCP. Voici l’inventaire pratique :

Agents : un agent combine un LLM, des instructions, des tools et un comportement runtime optionnel. Ce comportement inclut les handoffs vers d’autres agents, les guardrails pour vérifier input/output et les structured outputs pour forcer un format de réponse. Agent et Runner travaillent ensemble : le SDK gère agent loop, turns, tool calls, vérifications de guardrails et délégation par handoff.

Handoffs : un handoff permet à un agent de déléguer une tâche à un autre agent. En pratique, l’agent cible est exposé au LLM comme un outil. handoff() permet de configurer l’agent cible, le nom et la description de l’outil, on_handoff, input_type, input_filter et is_enabled. C’est adapté aux scénarios avec spécialistes : un agent de support qualifie le problème, puis délègue au support technique ou à la consultation de commande.

Guardrails : les guardrails existent en deux niveaux : input et output. Les input guardrails vérifient l’entrée utilisateur avant qu’elle n’entre dans l’agent. Les output guardrails vérifient la réponse avant retour. Un tripwire interrompt l’exécution. C’est utile pour « arrêter si l’entrée n’est pas dans le périmètre » ou « bloquer une sortie contenant des informations sensibles ». Les exemples officiels utilisent un modèle plus rapide pour vérifier si la demande est dans le périmètre.

Tracing : le SDK intègre le tracing des LLM generations, tool calls, handoffs, vérifications de guardrails et custom events dans un agent run. Chaque span enregistre les temps et les métadonnées, ce qui aide au debug, à la visualisation et au monitoring des workflows. Le tracing est activé par défaut, et trace_include_sensitive_data contrôle l’enregistrement des champs sensibles.

Sessions, HITL et MCP tools : les sessions assurent la continuité de conversation : plusieurs runs avec le même session_id partagent l’historique. La HITL API peut attendre une entrée externe pendant l’exécution, mais son modèle d’interruption n’est pas celui des interrupts LangGraph. Les MCP tools permettent à un agent d’appeler les outils exposés par des MCP servers, comme des function tools.

Ces primitives couvrent agent loop, tool calling, délégation, validation, tracing et continuité de conversation. Elles ne fournissent pas de graphe d’état explicite, de persistance par checkpoint, d’interrupts, de resume, de time travel ni de fault tolerance. Si votre tâche ressemble à « modèle + outils + délégation occasionnelle », Agents SDK peut suffire. Si elle exige « pause pour approbation + reprise + poursuite après incident + audit d’état », LangGraph correspond mieux.

Les points forts de LangGraph : les mécanismes d’état

Les forces de LangGraph se concentrent sur la gestion d’état et la reprise : Checkpointers, Interrupts, Time travel, Fault tolerance et Stores. Voici l’inventaire :

Checkpointers : les checkpointers sauvegardent le thread graph state sous forme de checkpoints. Cela inclut l’historique des nodes, les variables intermédiaires, les entrées externes en attente et la position courante. Chaque checkpoint est un snapshot complet d’état, utilisé pour la continuité de conversation, le HITL, le time travel et la fault tolerance. La documentation officielle distingue clairement les sessions d’Agents SDK des checkpointers LangGraph : les sessions maintiennent la conversation, les checkpointers sauvegardent l’état du graphe.

Interrupts : interrupt() peut suspendre l’exécution dans un graph node. Le checkpointer enregistre l’état courant et attend une entrée externe. La reprise se fait avec Command(resume=...), et le même thread_id sert de curseur persistant. La documentation cite des usages courants : approval workflows, review/edit state, interrupting tool calls et validating human input. C’est différent des guardrail tripwires d’Agents SDK : l’interrupt met la machine à états en pause, le guardrail arrête l’exécution.

Time travel : le time travel permet de revenir à n’importe quel checkpoint et d’observer l’état et le chemin d’exécution de ce moment. C’est utile pour l’audit, le debug et la reproduction d’un problème, par exemple « pourquoi cette branche a-t-elle été prise il y a deux heures ? ». Le tracing d’Agents SDK visualise un chemin, mais ne relance pas depuis un état historique.

Fault tolerance : la fault tolerance est la capacité à continuer après un incident. Si un agent de reporting plante au milieu d’une exécution, LangGraph peut reprendre au dernier checkpoint et éviter de répéter les étapes terminées. Agents SDK n’a pas de fault tolerance intégrée ; l’exécution repart généralement du début.

Stores : les stores conservent des données long terme entre threads : préférences utilisateur, historique ou état métier. La documentation distingue stores et checkpointers : les checkpointers sauvegardent le thread graph state, les stores conservent des données long terme transverses. Si plusieurs agent runs doivent partager un état, les stores sont la bonne couche.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Ces mécanismes rendent LangGraph plus adapté aux workflows longs et stateful : tâches longues, branches multiples, exécution reprise, état auditables et interventions humaines. Si votre projet a déjà ces besoins, la complexité de LangGraph est justifiée. Pour un simple tool agent ou un specialist handoff, Agents SDK sera souvent plus léger.

Quand utiliser Agents SDK

D’après la matrice et l’inventaire des primitives, Agents SDK convient mieux aux scénarios suivants :

1. Agents simples avec outils : recherche, synthèse et escalade occasionnelle vers un humain. Par exemple, un agent Q&A de base de connaissances interne peut récupérer des documents, synthétiser une réponse et inviter l’utilisateur à contacter le support en cas d’incertitude. Ce scénario ne nécessite ni reprise d’état complexe ni workflow d’approbation ; tools, handoffs et guardrails d’Agents SDK peuvent suffire.

2. Handoffs vers plusieurs spécialistes : scénarios où il faut déléguer à plusieurs agents spécialisés. Un agent de support client peut classifier le problème, puis déléguer au support technique, à la recherche de commande ou au remboursement. Les handoffs d’Agents SDK sont précisément des « agent as tool », donc ce modèle correspond bien.

3. Prototypes rapides : projets qui doivent valider une idée sans dessiner un graphe d’état explicite dès le départ. Agents SDK demande moins de code et se prend en main plus vite. Si le prototype montre qu’aucun checkpoint ni interrupt n’est nécessaire, il peut passer en production avec Agents SDK.

4. Affinité avec l’écosystème OpenAI : si le projet utilise surtout des modèles OpenAI, la Responses API ou des OpenAI hosted tools, Agents SDK est le toolkit officiel et l’intégration est plus fluide. Les agents vocaux temps réel, sandbox agents ou outils hébergés par OpenAI sont de bons exemples.

5. Une autre couche d’état existe déjà : si le projet a déjà une base métier, une queue ou un moteur de workflow pour gérer l’état, Agents SDK peut ne faire tourner que l’agent loop. Un node utilise Agents SDK pour appeler les outils, tandis que la base métier et la file de messages possèdent l’état.

Le point commun : pas de graphe d’état explicite, pas de persistance par checkpoint, pas de pause/reprise par interrupt, pas de time travel. Si votre projet correspond à ce profil, commencer avec Agents SDK peut économiser beaucoup de complexité.

Quand garder LangGraph

Si votre projet correspond aux cas suivants, la complexité de LangGraph vaut probablement le coût :

1. Tâches longues (20+ minutes) : agents de reporting, traitement de données ou analyses complexes peuvent durer plus de 20 minutes et planter ou expirer en cours de route. Les checkpointers et la fault tolerance de LangGraph permettent de reprendre au dernier checkpoint au lieu de repartir de zéro. Agents SDK n’a pas de fault tolerance intégrée et relance généralement l’exécution.

2. Approbation humaine nécessaire : les scénarios de tool call interrupt, comme supprimer des données, envoyer un email ou modifier des permissions, exigent une approbation avant de continuer. Les interrupts LangGraph peuvent suspendre avant le tool call, sauvegarder l’état via le checkpointer et reprendre avec Command(resume=...) après approbation. Les guardrails d’Agents SDK déclenchent et arrêtent ; ils ne mettent pas en pause pour revue puis continuation.

3. État auditable nécessaire : certains systèmes doivent rejouer des états historiques, inspecter les chemins d’exécution ou auditer une décision. Une question de conformité comme « pourquoi cette branche a-t-elle été prise il y a deux heures ? » demande plus qu’un trace. Le time travel LangGraph revient à un checkpoint ; le tracing d’Agents SDK montre un chemin mais ne relance pas depuis un état historique.

4. L’exécution doit continuer après incident : si un agent plante au milieu d’un run ou si le réseau tombe, le système doit continuer plutôt que recommencer. La fault tolerance de LangGraph reprend au checkpoint. Agents SDK repart du début. Si la tâche a des dépendances externes comme des appels API ou écritures en base à ne pas répéter, cette différence est critique.

5. Branches multiples, routage conditionnel ou machine à états métier : les workflows avec états explicites, conditions et transitions métier conviennent mieux à LangGraph. Exemple classique : paiement réussi -> expédition ; paiement échoué -> annulation ; paiement expiré -> intervention humaine. Ce type de processus est plus clair avec un graphe d’état explicite qu’avec des handoffs Agents SDK.

Le besoin commun est l’état explicite : persistance par checkpoint, interrupts, resume, time travel ou fault tolerance. Si votre projet en dépend, LangGraph n’est pas une surcharge ; c’est une couche de sécurité.

Décider du remplacement : checklist en quatre étapes

Même après ces scénarios, la décision peut rester floue. Utilisez cette checklist en quatre étapes :

Étape 1 : lister les besoins centraux

Découpez le besoin en capacités concrètes : tool calling, reprise d’état, approbation humaine, tâche longue, routing multibranche, audit replay et reprise après incident. N’écrivez pas seulement « il nous faut un agent ». Soyez concret. « Un agent de reporting tourne 20 minutes, attend une approbation SQL et doit reprendre après un crash » correspond à trois besoins : tâche longue, approbation et reprise après incident.

Étape 2 : mapper les besoins forts sur la matrice

Prenez la liste de l’étape 1 et associez-la aux 10 dimensions. « Tâche longue + approbation + reprise après incident » correspond à persistance d’état, HITL et reprise après échec. Sur ces dimensions, Agents SDK est faible ou absent, tandis que LangGraph est fort. Si vos besoins forts se concentrent dans les faiblesses d’Agents SDK, le remplacement est probablement inadapté.

Étape 3 : décider si un graphe d’état explicite est nécessaire

Posez une question : mon processus peut-il être dessiné comme des transitions d’état claires ? Si oui, par exemple un traitement de commande avec succès, échec, expiration et étapes suivantes, le graphe d’état explicite de LangGraph est plus adapté. Si le processus est surtout « modèle + outils + délégation occasionnelle » sans flux fixe, Agents SDK peut être plus léger.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Étape 4 : évaluer la tolérance de l’équipe à la complexité

LangGraph demande de concevoir des graphes, de l’état et des nodes. Si l’équipe tolère mal cette complexité, commencez par un prototype Agents SDK et ajoutez une couche d’état seulement si elle devient nécessaire. Si l’équipe a déjà l’habitude des workflows ou machines à états, la complexité de LangGraph peut être acceptable.

Après ces quatre étapes, vous devriez pouvoir choisir Agents SDK, LangGraph ou une approche hybride. Si vous êtes encore dans une sélection plus globale de frameworks, la checklist d’ingénierie AI Agent 2026 complète bien cette réflexion.

Chemins de migration pour les projets LangGraph existants

Si vous avez déjà un prototype LangGraph et voulez réduire une partie de la complexité avec Agents SDK, utilisez cette table :

Si vous utilisez Agents SDK et voulez savoir quand passer à LangGraph, cette table donne les signaux :

Exemple de modèle hybride : il n’est pas nécessaire de tout remplacer. LangGraph peut gérer le graphe d’état externe, tandis qu’un node utilise Agents SDK pour un agent court. Un agent de reporting peut garder son flux principal dans LangGraph : préparation des données -> génération SQL -> approbation humaine -> exécution de requête -> export. Les nodes « génération SQL » et « export » n’ont pas besoin de leurs propres checkpoints ou interrupts ; ils peuvent utiliser l’agent loop et les tool calls d’Agents SDK, pendant que LangGraph conserve la responsabilité de l’état.

La clé est la responsabilité : LangGraph possède la couche d’état ; Agents SDK peut exécuter des nodes courts. Ce n’est pas un choix binaire, mais une répartition selon les points forts de chaque outil.

Conclusion

OpenAI Agents SDK et LangGraph ne sont pas un choix binaire. La vraie question est : avez-vous besoin d’une couche d’état ? Si le projet nécessite seulement agent loop, tool calls, délégation et validation, comme une Q&A de base de connaissances, un triage support ou un prototype rapide, commencez avec Agents SDK. Il est plus léger et plus rapide à mettre en route. Si le projet demande reprise de tâches longues, approbation humaine, audit d’état ou continuation après incident, comme un agent de reporting, un workflow de commande ou un processus de conformité, les checkpoints, interrupts, time travel et fault tolerance de LangGraph deviennent nécessaires.

Vous n’avez pas besoin de forcer un remplacement. Une approche hybride pratique consiste à laisser LangGraph gérer le graphe d’état externe et à faire tourner les nodes courts avec Agents SDK. La décision commence par les besoins : listez les exigences centrales, mappez les plus fortes sur la matrice, puis décidez quoi garder, remplacer ou combiner.

Étape suivante : si vous avez déjà un prototype LangGraph, utilisez la table de migration pour identifier les nodes qui peuvent passer à Agents SDK. Si vous êtes encore en phase de choix, utilisez la checklist en quatre étapes pour décider d’abord si le projet a besoin d’un graphe d’état explicite.