Claude Agent SDK et LangGraph créent tous deux des agents d’IA, mais ils ne s’accordent pas sur celui qui décide de l’étape suivante. Ce comparatif détaille la boucle d’agent face au graphe explicite, les outils intégrés, l’état et la persistance, l’approbation humaine, la dépendance au modèle et les coûts en production, puis donne une règle simple pour choisir.
Choisir entre le Claude Agent SDK et LangGraph revient à une seule question : est-ce le modèle qui décide de la suite, ou votre code ? Le Claude Agent SDK fournit à votre application la même boucle d’agent que celle qui tourne dans Claude Code, de sorte que Claude choisit ses propres outils et ses étapes. LangGraph vous donne en revanche une machine à états. Vous dessinez les nœuds et les arêtes, et le modèle travaille à chaque arrêt. Les deux permettent de construire des agents d’IA capables. Ils ne s’accordent simplement pas sur celui qui tient le volant.
Ce comparatif passe en revue le flux de contrôle, les outils, l’état, l’approbation humaine, le choix du modèle et les coûts en production, afin que vous choisissiez avant d’écrire mille lignes pour la mauvaise solution.
Si votre agent consiste surtout à « donner à un modèle performant de bons outils et le laisser travailler », commencez par le Claude Agent SDK. Si votre agent est un flux de travail avec des étapes fixes, des embranchements, des nouvelles tentatives et des points d’audit, commencez par LangGraph. La plupart des hésitations disparaissent dès que vous rangez votre projet dans l’une de ces deux formes.
Voici le tableau comparatif avant les détails :
| Question | Claude Agent SDK | LangGraph |
|---|---|---|
| Idée centrale | Boucle d’agent prête à l’emploi autour de Claude | Graphe de nœuds, d’arêtes et d’état partagé |
| Qui choisit l’étape suivante | Le modèle | Votre graphe, le modèle travaillant à l’intérieur des nœuds |
| Modèles | Claude, via l’API d’Anthropic, Amazon Bedrock ou Google Vertex AI | Tout modèle disposant d’une intégration LangChain |
| Outils intégrés | Lecture, écriture, modification de fichiers, shell, recherche, récupération web | Aucun ; vous branchez vos propres outils |
| État | Sessions avec gestion automatique du contexte | État typé avec un point de sauvegarde à chaque étape |
| Approbation humaine | Modes de permission et hooks | Interruptions et reprise |
| Langages | Python, TypeScript | Python, JavaScript et TypeScript |
| Idéal pour | Agents de code, de recherche, de fichiers et de shell | Flux de travail métier en plusieurs étapes avec un routage strict |
💡 Règle empirique : comptez les étapes que vous pouvez écrire à l’avance. Si vous pouvez les noter sur un coin de table, dessinez un graphe. Si la réponse honnête est « cela dépend de ce que l’agent trouve », utilisez la boucle.
Anthropic a d’abord publié cet outil sous le nom de Claude Code SDK, avant de le renommer Claude Agent SDK, car il servait bien au-delà du code. Vous installez claude-agent-sdk pour Python ou @anthropic-ai/claude-agent-sdk pour TypeScript, vous appelez query() avec un prompt et quelques options, puis vous recevez les messages en flux pendant que l’agent travaille.
Sous le capot, on trouve le même harnais que celui qui alimente Claude Code. Il envoie le contexte à Claude, exécute les outils que Claude demande, renvoie les résultats et recommence jusqu’à ce que Claude juge la tâche terminée. Ce que vous obtenez sans l’écrire vous-même :
CLAUDE.md et des skills chargés depuis le système de fichiersLangGraph vient de l’équipe de LangChain et est conçu pour des agents à longue durée d’exécution et avec état. Sa version 1.0 est sortie fin 2025. Vous définissez un schéma d’état, écrivez les nœuds sous forme de fonctions ordinaires, les reliez par des arêtes fixes ou conditionnelles, puis compilez le résultat en un graphe exécutable.
Le graphe est le produit. Chaque étape lit l’état partagé et renvoie une mise à jour, ce qui vous permet de voir précisément où en est une exécution à tout moment. Les checkpointers sauvegardent cet état après chaque étape, ce qui rend possibles la pause, la reprise et le rejeu. LangGraph est indépendant du modèle : tout modèle de chat disposant d’une intégration LangChain se branche dans un nœud, et LangSmith ajoute le traçage lorsque vous voulez observer les exécutions.
C’est la véritable bifurcation. Dans le SDK, Claude choisit le prochain geste à chaque tour : lire un autre fichier, exécuter une commande, faire une recherche sur le web ou s’arrêter. Dans LangGraph, ce sont les arêtes qui choisissent, et le modèle ne décide qu’à l’intérieur du nœud qui lui est confié.
| Caractéristique | Boucle (Claude Agent SDK) | Graphe (LangGraph) |
|---|---|---|
| Prévisibilité | Plus faible, le modèle improvise | Plus élevée, les chemins sont déclarés |
| Souplesse | Élevée, gère des tâches que vous n’aviez pas prévues | Limitée par les arêtes que vous avez tracées |
| Débogage | Lire la transcription des appels d’outils | Inspecter l’état à chaque nœud |
| Temps jusqu’à la première démo | Quelques minutes | Un après-midi pour un vrai graphe |
| Échec typique | Errance, appels d’outils superflus | Un chemin rigide avec une branche manquante |
Aucune approche n’est fausse. Une boucle absorbe les imprévus, comme un rapport de bug qui se révèle être un problème de configuration. Un graphe garantit le processus, par exemple « toujours valider l’adresse avant de débiter la carte ».
Prenons une tâche simple : auditer un module d’authentification et signaler les fonctions les plus risquées. Voici la version avec le Claude Agent SDK :
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob"],
system_prompt="You review code for security risks.",
)
async for message in query(
prompt="Audit the auth module and list the three riskiest functions.",
options=options,
):
print(message)
asyncio.run(main())
C’est tout le programme. Claude décide quels fichiers ouvrir, dans quel ordre, et quand il en a vu assez.
Maintenant, la même tâche dans LangGraph, avec une étape de relecture garantie. Les fonctions auxiliaires run_audit et passes_checks sont des espaces réservés pour votre propre code :
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
question: str
report: str
approved: bool
def audit(state: State) -> dict:
return {"report": run_audit(state["question"])}
def review(state: State) -> dict:
return {"approved": passes_checks(state["report"])}
def route(state: State) -> str:
return "done" if state["approved"] else "retry"
builder = StateGraph(State)
builder.add_node("audit", audit)
builder.add_node("review", review)
builder.add_edge(START, "audit")
builder.add_edge("audit", "review")
builder.add_conditional_edges("review", route, {"done": END, "retry": "audit"})
graph = builder.compile()
Ici, c’est vous qui avez écrit le processus : chaque rapport est relu, et une relecture échouée revient toujours en arrière. Le modèle ne peut jamais sauter la relecture. Le prix à payer, c’est la plomberie : plus de code, plus de décisions et un graphe à maintenir.
Le SDK gère la délégation avec des sous-agents. Vous définissez chaque assistant avec une description, un prompt et une liste d’outils restreinte, puis l’agent principal leur confie du travail. Chaque sous-agent s’exécute dans son propre contexte, ce qui garde la fenêtre du parent propre. La mise en place est rapide, et les décisions de délégation restent à la charge de Claude.
LangGraph modélise la même chose avec des sous-graphes ou un nœud superviseur qui route vers des nœuds de travail. Les passages de relais sont explicites, l’état partagé est typé et vous pouvez tester chaque worker isolément. Quand cinq agents doivent coopérer dans un ordre fixe, cette explicitation se rentabilise. Quand les agents sont des spécialistes indépendants, cela peut ressembler à de la paperasse.
Le SDK arrive avec une boîte à outils complète, ce qui explique qu’il paraisse productif dès le premier jour. Un agent capable de lire un dépôt, modifier des fichiers et lancer des tests fonctionne dès que vous passez allowed_tools. Des outils personnalisés s’ajoutent via des serveurs MCP intégrés au processus ou n’importe quel serveur MCP externe. Restreindre la boîte compte autant que la remplir : Bash est puissant, donnez-le uniquement aux agents qui en ont besoin.
LangGraph part d’un établi vide. Les outils sont des fonctions que vous liez à un modèle dans un nœud, et un nœud d’outils préconstruit exécute les appels. Cela demande plus de mise en place, mais offre plus de liberté : un outil peut être n’importe quelle fonction appelable depuis Python ou JavaScript, et vous décidez de ce que chaque nœud peut toucher.
Le SDK suit une session. Chaque exécution a un identifiant, et vous pouvez la reprendre plus tard avec tout l’historique de conversation, ou la dupliquer pour essayer une autre piste. Le harnais compacte les anciens tours pour que les longues tâches ne saturent pas le contexte.
LangGraph suit un checkpoint pour chaque étape, regroupés par fil d’exécution. Vous pouvez reprendre un fil après un plantage, rejouer depuis une étape antérieure, ou modifier l’état et repartir de là. Un store séparé conserve la mémoire à long terme partagée entre les fils, comme les préférences d’un utilisateur.
💡 La différence : une session retient la conversation. Un checkpoint retient où en est le flux de travail. Si votre agent doit redémarrer à la quatrième étape sur sept, sur un autre serveur, les checkpoints sont le choix naturel.
Les agents qui manipulent de l’argent, des données de production ou des e-mails clients ont besoin d’une personne dans la boucle. Les deux outils le prennent en charge, à des endroits différents.
Le SDK protège les actions. Les modes de permission vont de la demande de confirmation avant tout, à l’acceptation automatique des modifications de fichiers, jusqu’à un mode de planification en lecture seule. Vous pouvez autoriser ou refuser des outils par leur nom, fournir un callback qui approuve chaque appel, et attacher des hooks qui s’exécutent avant un outil et peuvent le bloquer ou le réécrire. Un hook qui refuse toute commande shell contenant rm -rf tient en une courte fonction.
LangGraph protège les étapes. Un nœud appelle interrupt(), le graphe s’arrête, et le checkpointer enregistre tout. Des heures ou des jours plus tard, une personne répond, vous reprenez avec un Command, et l’exécution continue au même endroit, même sur une autre machine. Cela rend simples à construire les files d’approbation, comme les remboursements au-delà d’un seuil.
Lequel est préférable ? Si vous vous inquiétez de ce que l’agent a le droit de faire, les permissions du SDK conviennent. Si vous vous inquiétez de quand un humain doit valider dans un processus métier, les interruptions de LangGraph conviennent.
Le Claude Agent SDK exécute les modèles Claude. Vous pouvez y accéder via l’API d’Anthropic ou via des fournisseurs cloud comme Amazon Bedrock et Google Vertex AI, mais vous ne pouvez pas remplacer ce modèle par celui d’un autre éditeur. Si Claude est de toute façon votre choix, c’est un atout, car le harnais est réglé sur la façon dont Claude utilise les outils.
LangGraph est neutre. Vous pouvez faire tourner un nœud sur un modèle rapide et peu coûteux pour le routage, un autre sur un modèle de raisonnement puissant, et remplacer l’un ou l’autre par un simple changement de configuration. Avant de vous engager, testez le même prompt d’agent sur plusieurs modèles sur PicassoIA : Claude Sonnet 5 pour le code et l’usage d’outils équilibrés, Claude Opus 4.7 pour les raisonnements plus complexes, Claude Fable 5 pour les tâches de code complexes, GPT 5.6 Sol, Gemini 3.1 Pro, et Kimi K2.6, présenté comme conçu pour construire des agents. Si un seul éditeur s’impose nettement pour votre tâche, la question de la dépendance se règle d’elle-même.
Un agent du SDK exécute le runtime de Claude Code, donc déployez-le là où ce runtime peut vivre, généralement dans un conteneur au système de fichiers verrouillé. Comme l’agent peut lancer des commandes shell, le sandboxing n’est pas facultatif. Pour la visibilité, vous disposez du flux de messages, des transcriptions sauvegardées et de hooks qui journalisent chaque appel d’outil.
Les agents LangGraph sont des services classiques. LangSmith trace chaque nœud, un studio visuel vous permet de parcourir l’état pas à pas, et une option de déploiement hébergé existe pour les graphes à longue durée. L’exécution durable grâce aux checkpoints signifie qu’un redéploiement ou un plantage n’efface pas une exécution en cours.
Les deux sont gratuits à installer. La facture correspond aux tokens du modèle plus l’hébergement. Les boucles coûtent souvent plus cher lorsque la tâche est floue, car le modèle peut ouvrir dix fichiers là où trois suffiraient. Les graphes vous permettent de limiter cela : envoyer les étapes simples à un petit modèle, borner les tentatives avec une limite de récursion, et se passer du modèle pour les étapes déterministes. Revers de la médaille, une boucle atteint souvent plus vite un résultat fonctionnel sur un travail ouvert, car personne n’a besoin de concevoir le graphe au préalable.
Ils ne s’excluent pas. Un schéma courant utilise LangGraph comme flux de travail externe, avec un nœud qui appelle le Claude Agent SDK pour la partie ouverte, comme « corrige les tests en échec ». Le graphe gère le routage, l’approbation et les nouvelles tentatives. Le SDK prend en charge le milieu compliqué.
| Votre situation | Meilleur choix |
|---|---|
| Développeur solo qui livre un agent de code cette semaine | Claude Agent SDK |
| Workflow de support avec approbation des remboursements | LangGraph |
| Assistant de recherche bâti sur Claude | Claude Agent SDK |
| Pipeline combinant des modèles de trois éditeurs | LangGraph |
| Étape de réparation ouverte dans un flux réglementé | Les deux |
💡 À retenir : les deux projets livrent des changements rapidement. Vérifiez les notes de version de chacun avant de vous appuyer sur un détail de cet article, en particulier les noms et valeurs par défaut des options.
La meilleure façon de trancher un débat entre frameworks est de tester sur quelque chose de petit. Il en va de même pour les visuels. Votre projet d’agent aura besoin d’une image principale pour le README, d’une photo pour l’article de lancement ou d’un moodboard pour la page produit, et Picasso IA permet de le faire rapidement.
Prototypez votre prompt d’agent avec Claude Sonnet 5 sur PicassoIA :
Puis créez quelque chose qui accompagne le projet. Décrivez une scène, par exemple une équipe de développeurs devant un tableau blanc dans une lumière matinale douce, photographiée sur pellicule 35 mm, et générez-la en quelques secondes. Parcourez tous les modèles disponibles sur picassoia.com/en/all-models, testez trois ou quatre prompts, et voyez jusqu’où une seule phrase peut vous mener. Votre prochain agent mérite un lancement soigné.
Choisissez votre langue
