LangGraph décrit un agent comme un graphe : les nœuds font le travail, les arêtes décident de la suite, et un état partagé circule entre eux et est sauvegardé après chaque étape. Un processus interrompu par un plantage reprend là où il s'est arrêté au lieu de repartir de zéro. La version 1.0 est sortie avec LangChain 1.0 le 17 octobre 2025, et la ligne a depuis atteint la 1.2.
En quoi il diffère de LangChain
LangChain vous donne un agent fonctionnel en une fonction et une boucle qui décide seule quand s'arrêter. LangGraph retire cette décision au modèle et vous la confie : vous dessinez le flux, vous fixez les conditions de transition, vous marquez les points où le processus se met en pause.
Cette différence a des conséquences. Dans un agent simple, vous ne savez pas combien de tours le modèle va faire ni dans quel ordre il va chercher les outils. Dans un graphe, vous le savez, car le flux vit dans le code et peut être testé sans appeler un modèle du tout. Le prix est que chaque graphe doit être conçu, ce qui sur une tâche de trois étapes est un travail dont vous n'aviez pas besoin.
Il vaut aussi la peine de regarder cela du point de vue de celui qui maintient le résultat. Une boucle d'agent est lisible par quiconque lit le prompt, alors qu'un graphe demande de lire du code pour savoir ce qui va se passer. En échange, il répond sans ambiguïté à la question de savoir pourquoi le processus a pris un chemin plutôt qu'un autre, car la condition de transition est écrite. Face à une réclamation de client, cette différence décide si le diagnostic prend un quart d'heure ou une demi-journée à deviner ce que le modèle avait en tête.
La frontière pratique se situe là où un processus cesse de tenir dans un appel. Une conversation avec un seul outil relève de LangChain. Un processus qui attend une validation humaine, se ramifie selon le résultat d'un contrôle et doit survivre à un redémarrage de serveur relève de LangGraph.
Un graphe n'est pas la seule façon de décrire un tel processus. LlamaIndex Workflows modélise la même chose avec des événements : une étape écoute un événement d'un type donné et en émet elle-même d'autres, donc ajouter une étape n'exige pas de redessiner les arêtes. Le prix va exactement dans l'autre sens, puisque le flux n'est pas visible en un seul endroit et doit être reconstitué à partir des types d'événements éparpillés dans les étapes, ce qui face à une réclamation de client est plus difficile que de lire un graphe.
Installation et premier graphe
pip install langgraph langchain-openaiUn graphe minimal comporte trois parties : un schéma d'état, des nœuds et des arêtes.
from typing import TypedDict, Annotated
from operator import add
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
question: str
chunks: Annotated[list[str], add]
answer: str
def search(state: State) -> dict:
return {"chunks": retriever.invoke(state["question"])}
def answer(state: State) -> dict:
context = "\n".join(state["chunks"])
return {"answer": model.invoke(f"{context}\n\nQuestion: {state['question']}").content}
graph = StateGraph(State)
graph.add_node("search", search)
graph.add_node("answer", answer)
graph.add_edge(START, "search")
graph.add_edge("search", "answer")
graph.add_edge("answer", END)
app = graph.compile()
app.invoke({"question": "how do returns work"})Chaque nœud est une fonction ordinaire qui reçoit l'état et renvoie un dictionnaire de modifications. Il n'a pas à renvoyer l'état entier, seulement les champs qu'il modifie. Un petit détail qui simplifie beaucoup une fois qu'on a dix nœuds.
État, reducers et typage
L'annotation Annotated[list[str], add] dans le schéma d'état déclare un reducer, c'est-à-dire la manière dont une nouvelle valeur fusionne avec l'ancienne. Sans lui, chaque nœud écrase le champ. Avec lui, les valeurs s'accumulent, ce qu'il faut partout où plusieurs nœuds contribuent à une liste partagée.
L'erreur la plus courante à ce stade est de garder trop de choses dans l'état. L'état est persisté après chaque étape, donc y déposer des documents entiers au lieu de leurs identifiants augmente le coût d'écriture et la taille des checkpoints. Gardez ce dont la décision suivante a besoin, et récupérez le reste à l'intérieur du nœud.
Les branches sont décrites par une fonction qui renvoie le nom du nœud suivant.
def is_enough(state: State) -> str:
return "answer" if len(state["chunks"]) >= 3 else "expand_query"
graph.add_conditional_edges("search", is_enough)Une fonction conditionnelle peut aussi renvoyer une liste de noms, ce qui répartit en parallèle vers plusieurs nœuds et fusionne leurs résultats via le reducer. Cela aide quand on interroge plusieurs sources à la fois, là où les interroger en séquence allonge la réponse sans raison.
La condition est du Python ordinaire, donc vous la testez sans appels réseau et sans tokens. C'est l'un des meilleurs côtés de cette approche : la logique de contrôle est testable séparément du modèle.
Exécution durable et checkpointers
Un checkpointer sauvegarde l'état après chaque étape sous un identifiant de thread. Si le processus meurt en cours de route, vous reprenez avec le même identifiant et le graphe continue depuis le dernier nœud sauvegardé.
from langgraph.checkpoint.postgres import PostgresSaver
with PostgresSaver.from_conn_string(os.environ["DATABASE_URL"]) as saver:
app = graph.compile(checkpointer=saver)
app.invoke(
{"question": "how do returns work"},
config={"configurable": {"thread_id": "ticket-8842"}}
)Le mode de durabilité se règle avec le paramètre durability. La valeur async écrit l'état en arrière-plan pendant que l'étape suivante s'exécute, et c'est le compromis par défaut. La valeur sync écrit avant le début de l'étape suivante, donc rien n'est perdu même si le processus est tué net, au prix de quelques dizaines de millisecondes par nœud. La valeur exit n'écrit qu'à la fin et convient aux exécutions courtes où la reprise n'a pas de sens.
Le choix compte partout où un nœud produit un effet de bord. Si un nœud envoie un paiement et que l'état est écrit de façon asynchrone ensuite, un redémarrage au mauvais moment peut répéter l'opération. Pour de tels nœuds, réglez sync et ajoutez une clé d'idempotence de votre côté.
PostgresSaver n'est pas livré avec le paquet langgraph mais avec un paquet séparé langgraph-checkpoint-postgres, donc ajoutez-le à vos dépendances avant de copier l'import ci-dessus. Au premier lancement, appelez aussi setup() sur le checkpointer, car c'est ce qui crée les tables.
Les tests locaux se contentent de InMemorySaver de langgraph-checkpoint, qui est une dépendance du cœur. La production veut Postgres, et une base de Neon ou de Supabase y répond sans infrastructure supplémentaire, car le checkpointer n'a besoin que de quelques tables.
L'humain dans la boucle
Mettre un processus en pause en attendant un humain fait partie du langage de LangGraph, pas d'un contournement. Appeler interrupt arrête l'exécution, renvoie les données à examiner et attend.
from langgraph.types import interrupt, Command
def approve_refund(state: State) -> dict:
decision = interrupt({"amount": state["amount"], "order": state["number"]})
if decision["action"] == "reject":
return {"status": "rejected", "reason": decision.get("reason", "")}
return {"status": "approved"}
app.invoke(Command(resume={"action": "approve"}), config=config)Le processus peut rester là pendant des heures, car l'état vit dans une base de données plutôt que dans la mémoire du processus. Vous pouvez redémarrer le serveur, déployer une nouvelle version ou réduire la capacité entre-temps. Vous reprenez en fournissant le même thread_id et la décision de l'opérateur.
Deux choses méritent attention dans la conception de cette étape. Premièrement, les données passées à l'interruption doivent suffire pour que l'opérateur décide sans ouvrir un autre système, sinon la validation devient un jeu de changement de fenêtres. Deuxièmement, prévoyez l'expiration : un processus qui attend une validation pendant trois semaines devrait généralement se clore de lui-même plutôt que de rester éternellement dans la base.
Ce mécanisme est la principale raison pour laquelle les équipes passent d'un agent simple à un graphe. Tout processus qui touche à l'argent, aux données personnelles ou à la communication avec les clients finit par recevoir une exigence de validation, et la greffer sur une boucle d'agent se termine par un système de files d'attente maison.
Topologies multi-agents
Plusieurs agents peuvent être reliés de quelques manières, et le choix affecte à la fois le coût et la difficulté de diagnostiquer les pannes.
| Topologie | Fonctionnement | Avantage | Coût et risque |
|---|---|---|---|
| Agent unique | Un modèle, un ensemble d'outils | Diagnostic le plus simple | À 15 outils le modèle se met à mal choisir |
| Superviseur | Un agent aiguille le travail vers des sous-agents spécialisés | Répartition claire des responsabilités | Un appel de modèle supplémentaire par transfert |
| Réseau de pairs | Les agents se passent directement les tâches | Chemins plus courts | Difficile de prévoir l'exécution ou le coût |
| Pipeline | Séquence fixe d'étapes | Temps et prix prévisibles | Aucune souplesse pour une entrée inhabituelle |
Commencez avec un agent unique et ne divisez que lorsque l'ensemble d'outils cesse de tenir dans un prompt. Diviser en cinq agents dès la première semaine produit généralement un système où personne ne peut dire lequel a pris la mauvaise décision.
Streaming et inspection des exécutions
Un graphe diffuse à plusieurs niveaux : tokens du modèle, mises à jour de l'état après chaque nœud, ou instantanés complets de l'état. Dans une interface utilisateur, le deuxième mode est le plus utile, car il permet de montrer à quelle étape le processus est arrivé.
for kind, data in app.stream(payload, config=config, stream_mode=["updates", "messages"]):
if kind == "updates":
print("node:", list(data.keys()))Pour le diagnostic en dehors de l'interface, il y a le traçage LangSmith, où chaque exécution apparaît comme un arbre de nœuds avec les durées et le nombre de tokens. Sans lui, déboguer un graphe de douze nœuds revient à lire des logs, ce qui cesse de fonctionner dès que des branches apparaissent.
Comment tester un graphe
Un graphe l'emporte sur une boucle d'agent en testabilité, car il se découpe en couches, et chaque couche veut un type de test différent.
En bas se trouvent les fonctions conditionnelles. C'est du code ordinaire sans modèle, donc vous les couvrez par des tests unitaires et vérifiez les cas limites : un résultat de recherche vide, une valeur exactement sur le seuil, un champ manquant dans l'état. Ils s'exécutent en millisecondes et attrapent la plupart des bogues de flux de contrôle.
Au-dessus se trouvent les nœuds qui appellent un modèle. Ici, vous remplacez le modèle par une doublure qui renvoie une réponse fixe et vérifiez que le nœud la transforme en la bonne modification d'état. Il s'agit du contrat, pas de la qualité de la réponse, donc une doublure suffit.
Tout en haut se trouve le graphe entier. Vous l'exécutez avec InMemorySaver sur un ensemble de cas et comparez le chemin qu'il a pris à la liste attendue de nœuds.
from langgraph.checkpoint.memory import InMemorySaver
def test_short_search_expands_the_query():
app = graph.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "test-1"}}
app.invoke({"question": "returns", "chunks": []}, config=config)
visited = [s.next for s in app.get_state_history(config)]
assert "expand_query" in str(visited)Les interruptions méritent leur propre test. Couvrez les deux chemins, reprise avec approbation et reprise avec refus, car en pratique la branche du refus est celle qui reste non testée, et c'est celle qui abandonne un processus dans un état sans issue.
Il vaut aussi la peine de garder un jeu d'une douzaine de vraies requêtes avec leur résultat final attendu et de le lancer après chaque changement de prompt. Ce n'est plus un test unitaire mais une mesure de qualité, donc lancez-le délibérément, car il coûte des tokens.
Coûts et LangSmith Deployment
La bibliothèque elle-même est open source sous licence MIT et tourne gratuitement sur votre propre serveur. La partie payante est l'hébergement de graphes avec une file de tâches, la reprise et un panneau d'inspection des exécutions. Le nom a changé : ce que LangChain vendait sous le nom LangGraph Platform apparaît dans la grille tarifaire comme LangSmith Deployment, et les offres couvrent désormais ensemble le traçage et les déploiements.
| Offre | Coût par siège | Ce qu'elle couvre |
|---|---|---|
| Bibliothèque sur votre propre infrastructure | 0 USD | Fonctionnalités complètes, checkpointer sur votre propre base |
| LangSmith Developer | 0 USD, un siège | 5k traces par mois, pas de déploiements cloud |
| LangSmith Plus | 39 USD par siège et par mois | 10k traces, un déploiement Serverless en taille Small |
| LangSmith Enterprise | devis sur mesure | Déploiement hybride et auto-hébergé, SSO, SLA |
Le tarif par siège n'est que la première moitié de la facture, et le tableau seul ne le montrera pas. Tout ce que l'agent consomme réellement est mesuré séparément dans deux unités : LCU à 1,50 USD pour le travail et le calcul, et LSU à 1 USD pour les traces et le stockage. Le quota de traces inclus dans une offre n'est pas un plafond strict mais le point où commence le paiement à l'usage, donc un mois sur un seul siège peut représenter un multiple de ces 39 USD. Le déploiement cloud exige aussi au moins l'offre Plus, et faire tourner le plan de contrôle dans votre propre cluster exige Enterprise.
Les dépenses en tokens dominent toujours. Un graphe à superviseur avec trois sous-agents fait de cinq à quinze appels de modèle par requête d'utilisateur, donc l'écart entre un grand modèle et un plus petit dans les nœuds auxiliaires change le coût de plusieurs fois. N'envoyez au grand modèle que les décisions réellement difficiles.
Si l'équipe écrit en TypeScript, il vaut la peine de savoir que le portage est souvent le point faible de cet écosystème : avec Instructor, la version TypeScript s'est arrêtée à une version de janvier 2025. Mastra va dans l'autre sens, étant natif TypeScript et livrant des agents, des workflows sous forme de graphes d'étapes et un tableau de bord local pour inspecter les exécutions dans un seul paquet. Le prix est double : le projet est jeune et change très vite, et le stockage par défaut des exécutions et de la mémoire est un outil de développement, donc la production exige une décision délibérée sur l'endroit où vont ces données.
Erreurs courantes
La première est un graphe sans limite d'étapes. Une branche qui revient à un nœud antérieur pour une certaine forme de données crée un cycle qui tourne jusqu'à épuisement du budget. Réglez recursion_limit et traitez son atteinte comme un bogue du flux.
La deuxième est un état qui grandit sans limite. Une liste de messages complétée par un reducer à chaque tour dépassera la fenêtre de contexte après quelques dizaines d'étapes. Ajoutez un nœud qui résume ou tronque l'historique.
La troisième est de garder des secrets dans l'état. Tout ce qui entre dans l'état atterrit dans la base des checkpoints et dans les traces, donc passez un token d'accès utilisateur par la configuration plutôt que par les champs de l'état.
La quatrième est de concevoir le graphe autour du prompt actuel. Si les nœuds portent le nom de fragments d'une instruction au modèle, chaque changement de prompt impose un changement structurel. Nommez les nœuds d'après les étapes du processus métier, qui changent bien moins souvent.
Quand ne pas recourir à LangGraph
| Situation | Meilleur choix |
|---|---|
| Un appel de modèle et une réponse | Le SDK du fournisseur, par exemple OpenAI ou Claude |
| Agent avec quelques outils et sans pauses | create_agent de LangChain |
| Séquence fixe de tâches en arrière-plan | Une file de tâches comme Celery ou BullMQ |
| Processus métier avec SLA et nouvelles tentatives | Un moteur de workflow comme Temporal |
| Agent avec ramifications, mémoire et validation humaine | LangGraph |
La dernière ligne est la seule où le graphe gagne sans réserve. Partout ailleurs, il ajoute une couche que vous devez ensuite maintenir.
FAQ
LangGraph exige-t-il LangChain ?
Non. LangGraph s'appuie sur les abstractions de langchain-core mais ne vous oblige pas à utiliser les chaînes ou les agents de LangChain. Un nœud peut appeler directement le SDK d'un fournisseur, et le graphe fournit toujours l'état, la reprise et les pauses.
Fonctionne-t-il en TypeScript ?
Oui, la bibliothèque a une version JavaScript et TypeScript avec le même modèle de graphes, d'état et de checkpointers. Les nouvelles fonctionnalités arrivent généralement d'abord en Python, donc pour des intégrations exotiques il vaut la peine de vérifier si l'équivalent existe déjà. Le typage de l'état du côté TypeScript fonctionne bien et attrape les fautes de frappe dans les noms de champs.
Comment reprendre un processus après un redémarrage du serveur ?
Appelez à nouveau le graphe avec le même thread_id dans la configuration. Le checkpointer restaure l'état depuis la dernière étape sauvegardée et l'exécution continue à partir du nœud suivant. La condition est un checkpointer sur un stockage durable, car celui en mémoire disparaît avec le processus.
Puis-je voir quel chemin le graphe a emprunté ?
Oui, chaque exécution laisse un historique d'état disponible via get_state_history, et avec le traçage activé aussi un arbre de nœuds dans LangSmith. L'historique d'état permet aussi de rembobiner le processus jusqu'à une étape choisie et de le relancer sur une autre branche.
Combien de nœuds, c'est trop ?
Un graphe de plus de vingt nœuds signale généralement qu'un processus fait plusieurs choses à la fois. Plutôt que de le faire grossir davantage, extrayez un sous-graphe et appelez-le comme un seul nœud. Un sous-graphe porte son propre état et se teste séparément.
La documentation sur l'exécution durable se trouve sur docs.langchain.com, et le code dans le dépôt GitHub.