La plupart des agents commencent simplement, puis deviennent vite difficiles à maintenir dès qu’il faut boucler, brancher le flux, persister l’état ou attendre une validation humaine. Un script linéaire s’effondre vite dans ce type de workflow. LangGraph résout ce problème en modélisant l’agent comme un graphe avec un état partagé : les boucles, les branches et les reprises deviennent des primitives du workflow, pas des if dispersés. Ce guide explique comment l’utiliser, ce 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 bas niveau et un runtime pour construire des agents à état et durables. Il est développé par LangChain Inc, mais il s’agit d’une bibliothèque séparée. Installation minimale :
pip install -U langgraph
Le modèle est simple :
- les nœuds exécutent du travail ;
- les arêtes définissent le prochain nœud ;
- un état partagé circule dans tout le graphe ;
- les arêtes peuvent revenir en arrière, donc le workflow peut boucler.
Si vous avez utilisé l’ancienne abstraction Chain de LangChain, la différence principale est le flux de contrôle. Une chaîne est linéaire. Un graphe peut :
- choisir une branche selon l’état courant ;
- revenir à une étape précédente ;
- exécuter plusieurs branches puis fusionner les résultats.
C’est exactement ce qu’on retrouve dans un agent réel : “raisonner, agir, observer, recommencer”.
Le problème que LangGraph résout
Les workflows agentiques sont naturellement cycliques. L’agent appelle un outil, lit le résultat, décide s’il doit continuer, puis recommence si nécessaire. Avec des if imbriqués, le code devient rapidement illisible.
LangGraph adresse les cas suivants :
- Boucles avec condition d’arrêt : continuer jusqu’à ce que la tâche soit terminée.
- Routage selon l’état : envoyer vers le bon nœud selon la réponse du modèle.
- Persistance : reprendre après un crash, un timeout ou un redémarrage.
- Intervention humaine : mettre en pause, inspecter/modifier l’état, puis reprendre.
- Streaming : exposer les tokens et les étapes intermédiaires en temps réel.
Autrement dit, LangGraph fournit une machine à états durable pour des agents longs à exécuter.
Concepts clés : graphe, état, nœuds, arêtes
Les primitives de base sont peu nombreuses.
État
L’état est l’objet partagé pendant l’exécution. Vous en définissez le schéma avec un TypedDict ou un type équivalent. LangGraph fusionne ensuite les mises à jour retournées par chaque nœud.
Un point de départ courant est MessagesState, qui contient l’historique des messages.
Nœuds
Les nœuds sont des fonctions. Ils prennent l’état courant et renvoient une mise à jour partielle.
Arêtes
Les arêtes relient les nœuds.
-
add_edge(): transition fixe de A vers B. -
add_conditional_edges(): transition choisie dynamiquement selon l’état.
START et END
Ce sont les marqueurs spéciaux du début et de la fin d’exécution.
Exemple minimal
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") # boucle
graph = builder.compile()
Ici, la ligne add_edge("tools", "model") crée le cycle. Après l’exécution des outils, le contrôle revient au modèle, qui peut soit appeler d’autres outils, soit terminer.
Persistance et intervention humaine
Pour rendre un graphe durable, compilez-le avec un checkpointer. LangGraph sauvegarde alors un instantané de l’état après chaque étape. Avec un thread_id, il peut restaurer le dernier checkpoint lors de l’appel suivant.
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 la production, LangGraph propose aussi des sauvegardes basées sur une base de données, par exemple SQLite ou Postgres selon le besoin.
Cette persistance débloque aussi l’intervention humaine :
- interrompre le graphe à un point précis ;
- afficher l’état courant ;
- laisser une personne valider ou corriger ;
- reprendre à partir du checkpoint exact.
Le streaming complète ce modèle : l’agent peut émettre ses tokens et ses étapes au fur et à mesure, au lieu d’attendre la fin.
Comment LangGraph se rapporte à LangChain
LangChain et LangGraph sont complémentaires, mais leur rôle n’est pas le même.
- LangChain : composants et intégrations
- LangGraph : orchestration et exécution
Vous pouvez utiliser LangGraph sans LangChain. Vous définissez votre état, vos nœuds et vos arêtes, puis vous appelez le client de modèle que vous voulez dans un nœud.
Beaucoup d’équipes utilisent les deux ensemble, car les wrappers de modèles, outils et retrievers de LangChain restent pratiques. LangGraph fournit aussi un agent préconstruit via create_react_agent dans langgraph.prebuilt selon la version installée.
| LangChain | LangGraph | |
|---|---|---|
| Rôle | Composants et intégrations | Orchestration et exécution |
| Flux de contrôle | Chaînes linéaires | Graphes avec cycles et branches |
| État intégré | Limité | Partagé, typé, durable |
| Persistance / reprise | Pas l’objectif principal | Checkpointers + thread_id
|
| Idéal pour | Composer modèles et outils | Agents à état, multi-étapes |
Note : la ligne LangGraph v1.0 a fait évoluer certains points d’import. Vérifiez toujours votre version installée et la référence officielle avant de copier un extrait. Pour construire un agent de zéro, vous pouvez aussi consulter notre tutoriel sur la création d'agents IA personnalisés.
Plateforme et Studio LangGraph
La bibliothèque open source est le cœur du framework, mais deux produits deviennent utiles en déploiement.
LangGraph Studio est un IDE visuel pour agents. Il permet de visualiser le graphe, de l’exécuter et d’inspecter l’état à chaque nœud. Pour un workflow avec boucles et routage conditionnel, voir le chemin réel de l’agent est souvent plus utile que lire uniquement des logs.
LangGraph Platform apporte le déploiement managé : points d’API, persistance intégrée pour les exécutions longues, et options d’hébergement allant de l’auto-hébergement au cloud managé. Vous n’en avez pas besoin pour développer avec la bibliothèque, mais c’est utile dès que vous voulez une infrastructure prête pour la production.
Quand utiliser LangGraph
Utilisez LangGraph quand votre agent a un vrai flux de contrôle.
Bons signaux :
- le travail est une boucle, pas une séquence ;
- la branche suivante dépend de la décision du modèle ;
- l’exécution peut durer longtemps ;
- un humain doit valider une étape en cours de route ;
- plusieurs sous-agents doivent partager un état.
Évitez-le si un simple appel de modèle ou une courte chaîne linéaire suffit. Pour “résumer ce texte”, un graphe est souvent surdimensionné.
Où s’intègrent les tests et la simulation d’API
Un agent LangGraph n’est fiable que si les API qu’il appelle le sont aussi. Or il appelle souvent plusieurs surfaces : le LLM, des outils, une base interne, un CRM, une API de recherche, etc.
LangGraph orchestre ces appels, mais ne les teste pas. C’est là qu’intervient Apidog.
Deux problèmes reviennent vite en développement.
1. Les appels réels coûtent cher et ralentissent les tests
Appeler les API live à chaque test consomme des tokens et déclenche des limites de débit. Pour travailler plus vite, simulez l’API utilisée par votre agent. Vous obtenez des réponses déterministes et instantanées.
Vous pouvez faire la même chose avec le point de terminaison LLM pour tester le routage sans brûler de tokens.
2. Une dérive de contrat casse le graphe
Si l’API d’un outil change un nom de champ, une arête conditionnelle peut lire une mauvaise valeur. Résultat : boucle infinie, branche incorrecte ou blocage.
Pour limiter ce risque :
- définissez des assertions d’API pour valider la forme des réponses : API assertions ;
- gérez les variables et secrets par environnement ;
- testez les endpoints d’outils et les endpoints LLM avant d’exécuter le graphe.
Si vous voulez un workflow complet orienté agent, le harnais de test Apidog pour les agents IA couvre le parcours de bout en bout.
Point important : Apidog ne remplace pas LangGraph. Il teste et simule les API que votre agent consomme.
Questions fréquemment posées
LangGraph remplace-t-il LangChain ?
Non. LangGraph gère l’orchestration et le flux de contrôle cyclique. LangChain fournit des composants et des intégrations. Vous pouvez utiliser l’un sans l’autre, ou les combiner.
Faut-il connaître LangChain pour commencer ?
Non. Vous pouvez créer un StateGraph, ajouter des nœuds et des arêtes, puis appeler le client de modèle de votre choix dans un nœud.
Comment LangGraph se souvient-il des exécutions passées ?
Avec un checkpointer. Compilez le graphe avec un checkpoint, passez un thread_id, et LangGraph restaure l’état au prochain appel pour ce thread.
Comment tester les API appelées par mon agent ?
Testez-les séparément du graphe. Simulez les endpoints LLM et outils, puis validez les formes de réponse avec des assertions pour éviter qu’un champ cassé ne rompe le workflow. Notre guide sur le test de l’API ChatGPT couvre l’authentification, le streaming et les appels d’outils.
En résumé
LangGraph fournit la structure qui manque aux agents qui bouclent, se branchent, persistent et attendent une validation humaine. Modélisez le workflow comme un graphe avec un état partagé, utilisez des checkpointers pour la reprise, et servez-vous de Studio ou de la Platform quand vous passez au déploiement.
L’orchestration ne suffit pas : les API appelées par l’agent doivent aussi être testées et simulées. Utilisez Apidog pour garder des contrats d’outils fiables et réduire le coût des tests. Vous pouvez aussi télécharger Apidog pour simuler un endpoint et vérifier ses réponses avant que votre agent ne l’utilise.
Top comments (0)