LangGraph Primers : nœuds, arêtes et état partagé sans ambiguïté

Penser en termes de cartes plutôt que de lignes droites

LangGraph vise les applications multi-agents à état. Le code quotidien suit souvent une logique linéaire — boucles et conditions avec une étape suivante évidente. Les agents réels se comportent rarement de cette manière. Un graphe ressemble davantage à une carte : des lieux de travail reliés par des itinéraires que l’on choisit en temps de exécution.

L’avantage réside dans le contrôle. Le framework reste relativement de bas niveau, ce qui évite que le comportement ne soit enfermé dans des outils opaques. Trois éléments de base assurent la majeure partie du travail : les nœuds, les arêtes et l’état.

Les nœuds en tant qu’ouvriers spécialisés

Quatre rôles apparaissent de manière répétée. Les nœuds de traitement affinent les données brutes. Les nœuds de validation agissent comme des filtres de qualité. Les nœuds d’intégration se connectent aux API et aux bases de données. Les nœuds de décision choisissent où diriger le contrôle en fonction des conditions actuelles.

Les arêtes en tant que chemins d’exécution

Les arêtes définissent la manière dont l’exécution se déplace d’un nœud à l’autre. Elles permettent un routage dynamique : après trois tentatives infructueuses, envoyer un agent de support pour une révision humaine ; si des données supplémentaires sont nécessaires, revenir à une étape de traitement. La même représentation graphique peut exprimer les deux cas.

L’état en tant que mémoire partagée

L’état est la structure partagée que chaque nœud lit et met à jour — c’est la source de vérité pour l’exécution.

Checklist de conception pour éviter la confusion chez les agents : noms descriptifs (user_query, retry_count) ; formes simples faciles à modifier ; schémas explicites (par exemple TypedDict) qui définissent ce que la mémoire peut contenir.

Un schéma d’agent de support pourrait ressembler à ceci :

from typing import TypedDict
class SupportAgentState(TypedDict):
    user_input: str
    agent_response: str
    issue_type: str
    retry_count: int

Une boucle while peut poser à nouveau une question sans conserver réellement le contexte des cinq minutes précédentes. L’état persistant permet à l’agent de garder cette historique malgré les pauses et les branches secondaires.

Fonctionnalités qui apparaissent une fois les trois éléments assemblés

Les boucles et les branches permettent à l’exécution de revenir en arrière ou de changer de direction. Une intervention humaine est requise avant d’entreprendre des actions risquées. La persistance assure la cohérence des sessions longues. Le « voyage dans le temps » permet de revenir à un point de contrôle antérieur pour expliquer une décision. Les diagrammes Mermaid transforment cette même structure en un audit visuel des goulets d’étranglement et des boucles problématiques.

Plan de développement

Commencez petit : deux nœuds et une arête, puis développez progressivement. Protégez la modularité et les contrats d’état clairs afin que le système reste facile à maintenir à mesure que son comportement évolue.

Parcours d’apprentissage efficace

Lorsque vous apprenez pour la première fois le concept de trinité, créez un modèle simplifié presque trop petit : un nœud de traitement qui met le texte en majuscules, un nœud de validation qui rejette les chaînes vides, et une connexion conditionnelle qui termine le processus ou demande à nouveau des informations. Ce modèle enseigne le cycle lire–agir–mettre à jour sans surcharger l’utilisateur de trop d’outils. Ce n’est qu’ensuite que vous ajoutez un nœud d’intégration qui appelle une API réelle et un nœud de décision qui prend en compte les codes d’état.

Rédigez le schéma des états avant d’écrire les instructions. Les équipes qui inversent cet ordre découvrent souvent en cours de route que la moitié de leurs nœuds ne s’accordent pas sur les noms des champs clés. Un schéma d’une page indiquant les types et les valeurs énumérées autorisées évite ce type de désalignement. Placez des exemples d’extraits d’état valides à côté du schéma afin que les nouveaux arrivants puissent voir à quoi ressemble un état « correct » après trois itérations.

Lorsque le jouet fonctionne, dessinez-le. Mermaid (ou tout autre visualiseur de graphes proposé par LangGraph) met en évidence les arêtes manquantes. Si l’image et le code ne coïncident pas, ne faites confiance à aucun des deux tant qu’ils ne correspondent pas — puis supprimez les commentaires qui mentaient.

Appliquez cette discipline à la première fonction réelle : nommez les nœuds en fonction de verbes métier, gardez les arêtes simples, et refusez d’ajouter une deuxième responsabilité à un nœud déjà fonctionnel. Lorsqu’une solution vous semble ingénieuse, divisez-la. Les graphes trop complexes se dégradent avec le temps ; ceux qui sont clairs survivent aux transferts entre équipes.

Revoyez le plan après la première consultation de la page en production. Si les utilisateurs rencontrent des difficultés, la solution réside souvent dans un message de validation plus clair, et non dans un modèle plus sophistiqué. Apprenez cette leçon tôt, afin que cette approche reste une pratique concrète et non simplement un slogan.