LangGraph : Guide pour créer des agents IA avec état

La plupart des codes d'agents commencent simplement puis s'effondrent sous le poids de leurs propres tentatives. Vous connectez un LLM, lui donnez quelques outils, et dès que le workflow doit boucler, se ramifier ou se mettre en pause pour un humain, le script linéaire s'écroule. LangGraph est le framework conçu précisément pour ce désordre : il modélise un agent comme un graphe avec un état partagé, de sorte que les boucles et les ramifications deviennent une structure de première classe au lieu d'enchevêtrements d'instructions if. Ce guide explique ce qu'est LangGraph, le problème qu'il résout et où les tests d'API s'intègrent lorsque votre agent appelle des services réels.

Qu'est-ce que LangGraph

LangGraph est un framework d'orchestration de bas niveau et un environnement d'exécution pour construire des agents durables et à état. Il est développé par LangChain Inc, l'équipe derrière LangChain, mais c'est une bibliothèque séparée avec son propre objectif. Vous l'installez seule avec pip install -U langgraph, et vous pouvez l'utiliser sans le reste de l'écosystème LangChain.

L'idée principale est simple. Vous décrivez votre agent comme un graphe. Les nœuds effectuent le travail (appeler un modèle, exécuter un outil, transformer des données). Les arêtes décident ce qui est exécuté ensuite. Un objet d'état partagé circule à travers chaque nœud, et chaque nœud peut le lire et y écrire. Parce que les arêtes peuvent pointer vers l'arrière, le graphe peut boucler. C'est la partie qu'une chaîne simple ne peut pas bien faire.

Si vous avez utilisé l'ancienne abstraction Chain de LangChain, la différence réside dans la forme du flux de contrôle. Une chaîne est un pipeline : étape un, étape deux, étape trois, terminé. Un graphe permet à un nœud d'inspecter l'état actuel, puis de sauter vers une branche différente, de revenir en arrière pour réessayer, ou de se ramifier vers plusieurs nœuds qui s'exécutent en parallèle et fusionnent leurs résultats. Les agents réels ont besoin de cela, car "raisonner, agir, observer, raisonner à nouveau" est une boucle, pas une ligne.

Le problème que LangGraph résout

Les workflows agentiques sont cycliques par nature. Un agent appelle un outil, examine le résultat, décide s'il a terminé, et si non, réessaye. Modéliser cela avec des conditions imbriquées devient rapidement illisible, et cela empire une fois que vous ajoutez les éléments dont les agents de production ont réellement besoin :

• Boucles avec une condition d'arrêt. Continuer à appeler des outils jusqu'à ce que la tâche soit terminée, sans tourner indéfiniment.
• Ramification selon l'état. Acheminer vers un nœud différent en fonction de ce que le modèle a renvoyé.
• Persistance. Survivre à un crash, un timeout ou un redémarrage et reprendre au dernier bon point.
• Intervention humaine. Mettre en pause, laisser une personne inspecter ou modifier l'état, puis continuer.
• Streaming. Émettre des tokens et des étapes intermédiaires au fur et à mesure, et non pas seulement à la fin.

LangGraph transforme chacune de ces fonctionnalités en une capacité intégrée au lieu de quelque chose que vous devez coder manuellement. Vous obtenez une machine à états avec une exécution durable, de sorte qu'un agent peut s'exécuter pendant des minutes ou des heures et reprendre là où il s'était arrêté.

Concepts clés : graphe, état, nœuds, arêtes

Quatre primitives constituent l'essentiel du framework. Voici comment elles s'articulent.

L'état est un objet typé partagé sur l'ensemble de l'exécution. Vous définissez sa forme avec un schéma, souvent un TypedDict, et LangGraph fusionne les mises à jour de chaque nœud dans celui-ci. Un point de départ courant est MessagesState, un schéma pré-construit qui contient une liste de messages de chat en cours.

Les nœuds sont des fonctions. Chacun prend l'état actuel et renvoie une mise à jour partielle. Vous les enregistrez avec add_node().

Les arêtes connectent les nœuds. Une arête normale avec add_edge() va toujours de A à B. Une arête conditionnelle avec add_conditional_edges() exécute une fonction de routage qui lit l'état et renvoie le nom du nœud suivant, ce qui permet d'exprimer "si le modèle a demandé un outil, exécutez-le ; sinon, terminez".

START et END sont des marqueurs spéciaux pour le début et l'arrêt de l'exécution.

Voici la forme d'un graphe minimal. C'est un pseudo-code, mais les noms d'API sont réels.

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")   # loop back

graph = builder.compile()

La ligne add_edge("tools", "model") est le cycle. Après l'exécution des outils, le contrôle revient au modèle, qui peut appeler d'autres outils ou s'arrêter. Cette boucle est la raison d'être de LangGraph.

Persistance et intervention humaine

Compilez un graphe avec un checkpointer et il enregistre un instantané de l'état après chaque étape. Passez un thread_id dans la configuration, et LangGraph restaure le dernier checkpoint pour ce thread lors de l'appel suivant. Vos nœuds ne changent pas ; l'environnement d'exécution gère la sauvegarde et la restauration.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)

InMemorySaver convient pour le développement. Pour quelque chose qui survit aux redémarrages, LangGraph propose des "savers" basés sur des bases de données (SQLite pour un seul serveur, Postgres pour une mise à l'échelle multi-instances). Parce que l'état est durable, vous obtenez également l'intervention humaine presque gratuitement. Vous pouvez interrompre le graphe à un point choisi, afficher l'état actuel pour qu'une personne puisse l'inspecter ou le modifier, puis reprendre à partir de ce checkpoint exact. Les étapes d'approbation, les corrections manuelles et les étapes "êtes-vous sûr ?" s'appuient toutes là-dessus.

Le streaming complète le tableau. LangGraph peut diffuser les tokens du modèle et les mises à jour au niveau des nœuds au fur et à mesure que l'exécution progresse, de sorte qu'une interface utilisateur peut montrer l'agent en train de réfléchir au lieu d'afficher une icône de chargement.

Comment LangGraph se rapporte à LangChain

Ceci déroute les gens, alors soyons directs. LangChain est la boîte à outils plus large : wrappers de modèles, modèles de prompts, retrieveurs, chargeurs de documents et intégrations avec des centaines de fournisseurs. LangGraph est la couche d'orchestration sous-jacente aux parties agentiques de cette boîte à outils.

Vous n'avez pas besoin de LangChain pour utiliser LangGraph. Vous pouvez définir votre état, vos nœuds et vos arêtes, et appeler n'importe quel client de modèle que vous aimez à l'intérieur d'un nœud. De nombreuses équipes associent les deux, car les abstractions de modèle et d'outil de LangChain sont pratiques, et l'assistant create_react_agent pré-construit de LangGraph (dans langgraph.prebuilt) vous offre un agent d'appel d'outils fonctionnel en quelques lignes lorsque vous n'avez pas besoin d'un graphe personnalisé.

Une note pour les utilisateurs actuels : la ligne LangGraph v1.0 (stable depuis fin 2025) a fait évoluer l'assistant d'agent pré-construit vers langchain.agents.create_agent, alors vérifiez votre version installée et la référence officielle pour le chemin d'importation exact avant de copier d'anciens extraits. Construire des agents personnalisés à partir de zéro est également une compétence utile ici ; consultez notre tutoriel sur la création d'agents IA personnalisés pour une vue d'ensemble.

Plateforme et Studio LangGraph

La bibliothèque open-source est le cœur, mais deux produits adjacents deviennent importants une fois que vous déployez.

LangGraph Studio est un IDE visuel d'agent. Il rend votre graphe, vous permet de l'exécuter et affiche l'état à chaque nœud afin que vous puissiez observer l'exécution étape par étape à travers vos nœuds et vos arêtes. Pour tout ce qui implique des cycles et un routage conditionnel, voir le chemin réel emprunté par l'agent est bien plus efficace que de lire des lignes de journal.

LangGraph Platform est le côté déploiement géré : des points d'API pour vos agents, une persistance intégrée pour les exécutions de longue durée et des options d'hébergement allant de l'auto-hébergement au entièrement géré dans le cloud. Vous n'en avez pas besoin pour utiliser la bibliothèque ; elle est là lorsque vous voulez une infrastructure pour les agents en production plutôt que de les exécuter vous-même.

Quand utiliser LangGraph

Utilisez LangGraph lorsque votre agent a un véritable flux de contrôle. Bons signaux :

• Le travail est une boucle, pas une séquence (appeler des outils, vérifier, répéter).
• Vous devez bifurquer en fonction de la décision du modèle.
• Une exécution peut être longue, et vous voulez qu'elle survive à un crash et reprenne.
• Un humain doit approuver ou modifier quelque chose en cours d'exécution.
• Vous coordonnez plusieurs acteurs ou sous-agents qui partagent un état.

Évitez-le lorsqu'un simple appel de modèle ou une courte chaîne linéaire suffit. Un graphe est une surcharge inutile pour "résumer ce texte". Réservez la structure aux workflows qui se ramifient et bouclent réellement.

Où s'intègrent les tests et la simulation d'API

C'est la partie qui pose problème aux équipes en développement. Un agent LangGraph n'est fiable que dans la mesure où les API qu'il appelle le sont, et il en appelle beaucoup : le point de terminaison LLM, plus toutes les API d'outils (recherche, un CRM, votre propre backend). LangGraph orchestre ces appels ; il ne les teste pas. C'est un travail distinct, et c'est là qu'Apidog intervient.

Deux problèmes apparaissent rapidement. Premièrement, atteindre les API en direct à chaque exécution de test consomme des tokens et déclenche des limites de débit. Vous pouvez simuler l'API dont dépend un agent afin qu'un point de terminaison d'outil renvoie une réponse déterministe et instantanée pendant que vous itérez sur la logique du graphe. Simulez le point de terminaison LLM de la même manière et vous arrêtez de payer des tokens juste pour tester le routage.

Deuxièmement, vos nœuds supposent une certaine forme de réponse. Si l'API d'un outil modifie discrètement un nom de champ, votre arête conditionnelle lit la mauvaise chose et l'agent boucle ou cale. L'établissement de ces contrats avec les assertions d'API détecte la dérive avant qu'elle n'atteigne votre graphe. Et parce que les agents jonglent avec les clés entre les environnements de staging et de production, leur gestion dans les environnements garde les secrets hors de votre code de nœud. Si vous voulez le workflow complet axé sur l'agent, le harnais de test Apidog pour les agents IA le parcourt de bout en bout. Pour être clair, rien de tout cela n'orchestre l'agent ; Apidog teste et simule les API qui le sous-tendent.

Questions fréquemment posées

LangGraph remplace-t-il LangChain ? Non. LangGraph est l'environnement d'exécution de l'orchestration ; LangChain est l'ensemble plus large de composants et d'intégrations. Ce sont des bibliothèques distinctes de la même équipe, et vous pouvez exécuter LangGraph sans LangChain ou les utiliser ensemble. LangGraph gère le flux de contrôle cyclique et à état avec lequel les chaînes simples ont du mal.

Ai-je besoin de connaître LangChain pour commencer avec LangGraph ? Non. Vous pouvez définir un StateGraph, ajouter des nœuds et des arêtes, et appeler n'importe quel client de modèle à l'intérieur d'un nœud. Les wrappers de modèles de LangChain sont pratiques, mais ils sont facultatifs. Commencez avec les primitives de graphe de base et ajoutez le reste uniquement lorsque vous en avez besoin.

Comment LangGraph se souvient-il des choses entre les appels ? Grâce aux checkpointers. Compilez votre graphe avec un checkpointer et passez un thread_id, et LangGraph enregistre un instantané d'état après chaque étape, puis le restaure lors de l'appel suivant pour ce thread. C'est ainsi que vous obtenez la mémoire de conversation et la récupération après crash sans modifier la logique de votre nœud.

Comment tester les API que mon agent appelle ? Testez et simulez-les séparément du graphe. Simulez les points de terminaison LLM et d'outils pour que les exécutions soient rapides et gratuites pendant le développement, et affirmez les formes de réponse afin qu'un champ modifié ne casse pas un nœud. Notre guide sur le test de l'API ChatGPT couvre l'authentification, le streaming et les appels d'outils, qui sont les surfaces exactes dont un agent dépend.

En résumé

LangGraph vous offre la structure manquante pour les agents qui bouclent, se ramifient, persistent et se mettent en pause pour un humain. Modélisez le workflow comme un graphe avec un état partagé, appuyez-vous sur les checkpointers pour la mémoire et la récupération, et utilisez Studio et la Plateforme lorsque vous êtes prêt à déboguer et à déployer. Le framework gère l'orchestration. Les API que votre agent appelle ont toujours besoin de leur propre filet de sécurité, alors simulez et testez-les dans Apidog pour maintenir des coûts de développement bas et des contrats d'outils honnêtes. Téléchargez Apidog pour simuler un point de terminaison et affirmer ses réponses avant que votre agent ne l'atteigne réellement.