LangGraph : guide des graphes, mémoire et déploiement

LangGraph est une bibliothèque d’orchestration qui représente un traitement par un état partagé, des nœuds de calcul et des transitions explicites. Elle permet de combiner règles déterministes, appels de modèles, outils et validation humaine dans une application capable de conserver sa progression. Sa fiabilité dépend toutefois du stockage, des conditions d’arrêt et des protections que vous construisez autour des actions externes.

À quoi sert LangGraph dans une application d’agents ?

LangGraph intervient lorsque vous devez décider quelle étape exécuter, avec quelles données et dans quelles conditions reprendre un traitement. Cette orchestration d’agents ne remplace ni le modèle de langage, ni les services métier : elle organise leurs interactions.

Imaginez un assistant de traitement des demandes clients. Il identifie la demande, consulte une commande, prépare une proposition, attend une validation si nécessaire, puis exécute une action autorisée. Le graphe rend ces étapes visibles et permet de distinguer une décision du modèle d’une règle imposée par votre application.

LangChain fournit notamment des abstractions de modèles, messages et outils ; LangGraph donne un contrôle plus direct sur les transitions. Pour situer cette approche parmi les solutions disponibles, consultez notre annuaire des agents et frameworks et l’article sur les frameworks d’agents IA.

Le choix doit partir du besoin de contrôle :

Critère	Fonctions séquentielles	Boucle agentique	Graphe explicite
Chemin d’exécution	Fixé dans le code	Choisi en partie par le modèle	Transitions définies et décisions encadrées
État intermédiaire	À organiser	Souvent centré sur les messages	Schéma partagé entre étapes
Validation humaine	À développer	Dépend de l’implémentation	Peut devenir une étape du parcours
Complexité de conception	Limitée pour un traitement court	Croît avec les exceptions	Demande de concevoir état et transitions

Un graphe ne rend pas automatiquement une réponse exacte. Son intérêt est de rendre les décisions contrôlables et les échecs interprétables.

Comprendre l’état, les nœuds et les transitions

L’état contient les informations nécessaires à la suite du traitement : demande initiale, documents récupérés, résultats vérifiés, proposition et statut de validation. Un nœud reçoit cet état et retourne une mise à jour. Les arêtes définissent les étapes suivantes, éventuellement selon une condition. La documentation de la Graph API décrit ces primitives et la compilation du graphe.

Séparez les faits des interprétations. Une référence de commande issue du logiciel métier n’a pas le même statut qu’une catégorie estimée par un modèle. Conservez leur provenance pour pouvoir expliquer une décision et corriger une interprétation sans perdre les données d’origine.

Chaque champ possède une règle de mise à jour, appelée reducer. Par défaut, une nouvelle valeur remplace l’ancienne ; une règle personnalisée peut combiner les contributions. Cette distinction devient essentielle lorsque plusieurs branches produisent des résultats pour le même champ.

Préférez des champs structurés à un long texte cumulatif. Un statut explicite comme validation_requise se teste plus facilement qu’une phrase dans laquelle le modèle suggère une relecture. Gardez également les connexions et les secrets hors de l’état métier enregistré.

Enfin, dessinez les sorties avant les boucles. Pour chaque étape, identifiez le succès, l’échec récupérable, l’abandon et le besoin d’intervention. Un parcours dont vous ne savez pas expliquer l’arrêt reste insuffisamment défini.

Prérequis et étape 1 : installer le socle

La partie pratique utilise Python et commence sans appel de modèle. Vous devez savoir définir une fonction, manipuler un dictionnaire, lire une exception et gérer les dépendances d’un projet. Pour le serveur local présenté plus loin, la documentation consultée le 24 octobre 2026 demande Python 3.11 ou ultérieur.

Préparez un environnement isolé avec votre gestionnaire habituel. La documentation officielle d’installation donne cette commande, reproduite à l’identique :

pip install -U langgraph

Cette commande installe ou actualise le paquet disponible ; elle ne constitue pas un verrouillage reproductible. Après validation de votre application, enregistrez les versions effectivement utilisées dans votre gestionnaire de dépendances et conservez son fichier de verrouillage.

Aucune clé de fournisseur n’est nécessaire pour l’exemple suivant. Quand vous ajouterez un modèle, installez son intégration selon sa documentation et fournissez les secrets au processus par un mécanisme adapté à votre environnement. Évitez de les copier dans les exemples, les journaux ou les checkpoints.

Définissez aussi un scénario de vérification avant de programmer. Ici, une demande produira un brouillon, attendra une décision puis aboutira à un statut. Les résultats attendus sont simples : l’approbation termine le parcours, le refus bloque sa poursuite, et aucune action extérieure n’est effectuée.

Cette progression permet d’isoler les erreurs d’orchestration des erreurs de modèle ou de réseau.

Étape 2 : construire un graphe avec validation humaine

L’exemple pédagogique ci-dessous adapte les primitives officielles. Il construit un brouillon déterministe afin que vous puissiez examiner le mécanisme de pause sans dépendre d’une réponse générée.

from typing import TypedDict

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class Etat(TypedDict, total=False):
    demande: str
    brouillon: str
    approuve: bool
    statut: str


def preparer(etat: Etat):
    return {
        "brouillon": "Proposition à examiner : " + etat["demande"],
        "statut": "en_attente",
    }


def valider(etat: Etat):
    decision = interrupt({
        "action": "examiner_brouillon",
        "brouillon": etat["brouillon"],
    })
    return {"approuve": decision is True}


def orienter(etat: Etat):
    return "terminer" if etat["approuve"] else "refuser"


def terminer(etat: Etat):
    return {"statut": "approuve_sans_envoi"}


def refuser(etat: Etat):
    return {"statut": "refuse"}


builder = StateGraph(Etat)
builder.add_node("preparer", preparer)
builder.add_node("valider", valider)
builder.add_node("terminer", terminer)
builder.add_node("refuser", refuser)

builder.add_edge(START, "preparer")
builder.add_edge("preparer", "valider")
builder.add_conditional_edges("valider", orienter)
builder.add_edge("terminer", END)
builder.add_edge("refuser", END)

graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "demande-demo"}}

pause = graph.invoke(
    {"demande": "Préparer une réponse au client"},
    config=config,
)
print(pause)

# À appeler après une décision explicite dans votre application.
resultat = graph.invoke(Command(resume=True), config=config)
print(resultat["statut"])

L’appel à interrupt suspend le parcours ; la reprise transmet une valeur avec Command. La documentation des interruptions impose notamment un checkpointer, un identifiant de thread et une charge utile sérialisable.

Dans cet exemple, la valeur True représente une approbation déjà obtenue. Une interface réelle doit authentifier la personne, afficher le brouillon exact et transmettre sa décision. Le thread identifie le parcours ; il ne prouve pas que l’utilisateur a le droit de le consulter.

Vérifiez séparément le refus avec un autre thread et une reprise à False. Vous disposez alors d’un premier contrôle du routage, sans avoir encore autorisé un envoi.

Étape 3 : organiser la mémoire et la persistance

LangGraph distingue deux mécanismes complémentaires : le checkpointer conserve l’état d’un thread, tandis qu’un store conserve des données applicatives utilisables entre threads. Cette distinction est décrite dans la documentation sur la persistance.

Critère	Checkpointer	Store
Données conservées	Instantanés de l’état du graphe	Informations définies par l’application
Périmètre logique	Thread donné	Plusieurs threads selon votre organisation
Usage courant	Continuité et reprise d’un traitement	Préférences ou connaissances durables
Question de conception	Où reprendre le parcours ?	Que faut-il retrouver plus tard ?

InMemorySaver convient à une démonstration dans le même processus. Il ne doit pas être présenté comme une sauvegarde survivant au redémarrage. Pour une application durable, choisissez un stockage persistant compatible avec vos contraintes d’exploitation.

La mémoire d’agent demande également une politique éditoriale et technique. Une information proposée par le modèle ne devrait pas devenir un fait durable sans vérification. Enregistrez sa source, sa portée et, lorsque cela compte, sa période de validité.

Conserver l’historique et l’envoyer intégralement au modèle sont deux décisions distinctes. Vous pouvez garder des événements pour l’audit tout en préparant un contexte réduit pour chaque appel. L’article sur la mémoire des agents IA développe cette différence.

Définissez enfin la suppression : effacer une préférence du store peut laisser des copies dans les anciens états, les traces ou les sauvegardes. Inventoriez ces emplacements avant d’annoncer qu’une donnée est supprimée.

Étape 4 : ajouter un modèle et des outils contrôlés

Une fois le parcours déterministe compris, remplacez la préparation du brouillon par un appel de modèle. Conservez la validation et les règles métier dans le code. Une instruction demandant au modèle de respecter une limite ne remplace pas un contrôle effectif de cette limite.

Le quickstart officiel présente une boucle dans laquelle le modèle propose des appels d’outils, un nœud les exécute, puis les observations retournent au modèle. Utilisez cette structure comme point de départ, en ajoutant les contrôles propres à votre application.

Pour chaque outil, formalisez :

les arguments acceptés et leur validation ;
les droits nécessaires et le périmètre des données accessibles ;
le délai maximal et les erreurs récupérables ;
les effets externes et les conditions d’approbation ;
le résultat structuré attendu par la suite du graphe.

Un outil de lecture et un outil d’écriture devraient avoir des autorisations distinctes. Si l’assistant doit seulement préparer une réponse, son accès à une messagerie ne devrait pas permettre l’envoi.

L’injection de prompt reste possible dans les documents et les résultats d’outils. Traitez ces contenus comme des données : ils ne peuvent pas élargir les permissions ni annuler une validation prévue. Les protections doivent rester actives même si le modèle suit une instruction hostile.

Quand un service renvoie un résultat incomplet, évitez de le transformer en succès apparent. Retournez un statut exploitable : absence de résultat, accès refusé, délai dépassé ou données invalides. Le graphe pourra alors choisir une suite explicite.

Étape 5 : rendre les reprises compatibles avec les actions

Les checkpointers enregistrent des instantanés aux frontières des super-étapes et permettent notamment d’inspecter l’historique. Un checkpoint ne constitue cependant pas une transaction commune avec votre messagerie, votre logiciel comptable ou votre service de paiement.

Considérez un envoi réussi suivi d’une panne avant l’enregistrement de sa confirmation. À la reprise, votre application peut ignorer si l’envoi a eu lieu. Elle doit pouvoir retrouver cette information, plutôt que répéter aveuglément l’action.

Pour les opérations sensibles, utilisez une clé d’idempotence reconnue par le service cible ou un registre métier permettant de vérifier le résultat. Conservez une référence stable de l’opération, indépendante d’une reformulation du modèle.

Le code précédant une interruption dans un nœud peut être rejoué lors de la reprise. Placez donc les effets externes après la décision nécessaire et concevez-les pour supporter les réexécutions. Évitez un grand nœud mêlant recherche, approbation et envoi.

Appliquez également une politique de reprise différente selon l’erreur. Un incident réseau temporaire peut justifier une nouvelle tentative ; une autorisation refusée exige généralement une autre décision. Une entrée invalide doit être corrigée avant de solliciter à nouveau le service.

Documentez le comportement attendu après une coupure à chaque frontière sensible. Cette analyse révèle souvent davantage de défauts qu’un simple essai où tous les services répondent normalement.

Étape 6 : démarrer le serveur local et préparer le déploiement

Pour explorer une application sous forme de service, la procédure officielle du serveur local, consultée le 24 octobre 2026, fournit les commandes suivantes :

pip install -U "langgraph-cli[inmem]"
langgraph new path/to/your/app --template new-langgraph-project-python
cd path/to/your/app
pip install -e .

Le chemin proposé est un exemple à adapter. Le modèle généré contient la structure de départ ; il faut y intégrer votre graphe et vérifier sa déclaration dans la configuration de l’application.

La procédure demande également de créer un fichier .env à partir du modèle fourni et d’y renseigner une clé de LangSmith. Gardez ce fichier hors du dépôt, puis lancez :

langgraph dev

Cette commande démarre un environnement de développement. Utilisez les adresses affichées pour inspecter l’application et vérifier les parcours dans Studio. Le fonctionnement local ne valide pas encore la persistance, l’isolation ou la capacité du service en production.

La documentation de déploiement présente LangSmith Cloud ainsi que des options hybrides et auto-hébergées. L’hébergement de la bibliothèque dans votre propre service constitue aussi une décision d’architecture, avec des responsabilités opérationnelles à prévoir.

Le vocabulaire actuel est LangSmith Deployment ; l’ancienne appellation LangGraph Platform peut subsister dans des ressources historiques. Vérifiez les conditions de l’offre retenue, sans déduire de la disponibilité de la bibliothèque que tous les services associés ont les mêmes modalités.

Exploiter le graphe : droits, budget et évaluation

Avant l’ouverture aux utilisateurs, rattachez chaque thread à une identité et à un périmètre autorisé. Le serveur doit contrôler l’accès aux états, aux reprises et aux documents. Une séparation dans le prompt ne suffit pas à isoler les données de plusieurs clients.

Pour les validations, liez la décision à la version exacte de l’action. Une approbation portant sur un brouillon ne devrait pas autoriser un destinataire ou un montant modifié ensuite. Fixez aussi une expiration et un comportement lorsque la demande reste sans réponse.

Mesurez le coût au niveau de la tâche terminée. Les appels de modèle, les résultats d’outils volumineux, les reprises et les traitements abandonnés participent tous au budget. Le calculateur de prix LLM aide à estimer la composante liée aux tokens ; ajoutez séparément stockage et exploitation.

Préparez un jeu de scénarios comportant succès, refus, donnée manquante, outil indisponible et tentative de contournement. Vérifiez les transitions et les actions réellement effectuées, au-delà de la formulation finale. Le guide pour évaluer un agent IA propose une méthode de suivi.

Les traces doivent permettre de retrouver une erreur sans accumuler inutilement des données privées. Enregistrez les identifiants d’exécution, statuts et durées utiles ; masquez les secrets et contrôlez les accès. Le guide pour sécuriser un agent IA complète ces mesures.

Problèmes fréquents

Le parcours repart sans retrouver son historique. Vérifiez le checkpointer, sa disponibilité et l’identifiant du thread. Un nouvel identifiant désigne un autre parcours ; un stockage uniquement en mémoire disparaît avec le processus.

Des données précédentes disparaissent. Examinez les règles de mise à jour du champ concerné. Un remplacement peut être correct pour un statut, mais inadapté pour une collection de résultats à accumuler.

La reprise répète une action. Recherchez les effets externes avant une interruption ou dans une opération susceptible d’être rejouée. Vérifiez ensuite l’idempotence et la possibilité de consulter le résultat auprès du service cible.

La boucle continue sans progrès. Ajoutez une condition d’arrêt métier, un budget et une détection des tentatives répétitives. Augmenter seulement la limite technique reporte le problème.

Le modèle annonce un succès absent du logiciel métier. Faites dépendre le statut final d’une confirmation structurée du service. Une réponse générée ne constitue pas une preuve d’exécution.

Le prototype fonctionne, mais les utilisateurs se bloquent mutuellement. Examinez les accès concurrents au même thread et aux mêmes ressources métier. Définissez une politique de coordination avant d’accepter plusieurs opérations simultanées.

Checklist avant la mise en service

Pages liées

Questions fréquentes

Faut-il utiliser LangChain pour travailler avec LangGraph ?

Non. Vous pouvez appeler vos modèles et vos services depuis des fonctions ordinaires. Les abstractions de LangChain deviennent utiles si vous souhaitez mutualiser les interfaces de messages, de modèles et d'outils.

LangGraph peut-il fonctionner sans modèle de langage ?

Oui : un graphe peut orchestrer uniquement des fonctions déterministes. Cette possibilité permet de vérifier le routage, les interruptions et les mises à jour d'état avant d'ajouter les appels au modèle.

Un checkpoint empêche-t-il un outil de s'exécuter deux fois ?

Il ne suffit pas à garantir cette propriété dans un système externe. Pour une opération sensible, prévoyez une clé d'idempotence et un moyen de vérifier si l'action a déjà été effectuée.

Peut-on héberger une application LangGraph sur son infrastructure ?

Oui, mais intégrer la bibliothèque à votre propre service et déployer Agent Server correspondent à des choix distincts. Vérifiez les conditions et les dépendances de la formule de déploiement retenue avant de dimensionner votre infrastructure.

Quand LangGraph ajoute-t-il trop de complexité ?

Si votre traitement suit un chemin court, sans reprise ni validation intermédiaire, des fonctions ordinaires peuvent suffire. Le graphe devient pertinent quand ses transitions et son état rendent les erreurs plus faciles à maîtriser.

LangGraph, guide de référence : graphes d'états, mémoire, outils, déploiement