Vue d'ensemble de l'architecture LangGraph

源码版本1.2.9

En une phrase

LangGraph est un framework d'orchestration d'agents à base de machines à états dont le cœur repose sur canal (channel) + boucle Pregel : au niveau construction, StateGraph compile nœuds et arêtes en un exécutable Pregel ; à l'exécution, PregelLoop.tick répète « lire les canaux → planifier les tâches → écrire dans les canaux → checkpoint » jusqu'à convergence. Pendant ce temps, StreamMux assure la sortie en streaming multi-modes, interrupt/Command implémente la collaboration humain-machine, la famille BaseCheckpointSaver gère la persistance au niveau du thread, et @entrypoint/@task fournit une API fonctionnelle équivalente.

Couches

Une phrase par couche

• Démarrage et configuration : RunnableConfig transporte thread_id/store/checkpointer, StateSnapshot est l'instantané immuable renvoyé par get_state.
• Construction du graphe : StateGraph est l'entrée utilisateur ; add_node/add_edge/add_conditional_edges définissent la topologie ; compile produit un CompiledStateGraph (c'est-à-dire une instance de Pregel).
• Moteur Pregel : Pregel est le produit de compilation ; stream/invoke/astream en sont les points d'entrée ; PregelLoop.tick exécute un pas, PregelRunner fait tourner les tâches en parallèle, _algo gère préparation/écriture/décision d'interruption des tâches.
• Canal : BaseChannel abstrait les sémantiques update/consume/checkpoint ; LastValue est l'écrasement par défaut, Topic est du pub-sub, Binop est une agrégation par opérateur binaire.
• Checkpoint : interface BaseCheckpointSaver avec put/get/list ; trois implémentations InMemory/Sqlite/Postgres, synchrones et asynchrones.
• Streaming : StreamMux fait le mux/demux multi-mode ; chaque transformer (values/updates/messages/debug/lifecycle/subgraph/checkpoints/tasks) produit une vue différente.
• API fonctionnelle : @entrypoint transforme une fonction en exécutable Pregel, @task déclare des sous-tâches concurrentes.
• Interruption et sous-graphe : interrupt() déclenche une interruption humain-machine, Command(resume/goto/update) pilote la reprise et les sauts, Send réalise le fan-out.

Motivation du découpage en couches

LangGraph découple complètement « comment définir le graphe » (construction graph), « comment exécuter » (Pregel), « comment mettre à jour l'état » (channel), « comment persister » (checkpoint), « comment observer » (stream), « équivalent fonctionnel » (func), « comment interagir avec un humain » (interrupt) et « comment orchestrer » (subgraph). Ainsi, changer de backend de checkpoint n'affecte pas la logique d'exécution, changer de mode de stream n'affecte pas la définition du graphe, ajouter des interruptions ne modifie pas les canaux. Pregel est le seul hub : tous les chemins d'exécution passent au final par PregelLoop.tick.

Malentendus courants

• « LangGraph n'est qu'un emballage de graphe autour de LangChain » — non. Il dispose de son propre moteur d'exécution Pregel, ne dépend pas des abstractions chain/agent de LangChain, et peut être utilisé seul.
• « channel, c'est l'état » — le canal est la couche sémantique de mise à jour de l'état ; les différents types de canaux (LastValue/Topic/Binop) déterminent comment l'état est fusionné, c'est ce qui le rend plus puissant qu'une machine à états ordinaire.
• « @entrypoint est du sucre syntaxique pour StateGraph » — fonctionnellement équivalent mais d'implémentation différente ; l'API func passe par le chemin FunctionalAPI et finit aussi par être compilée en Pregel, mais ses sémantiques de concurrence et de join sont plus proches de celles d'une fonction ordinaire.

Ordre de lecture recommandé

Commencez par Démarrage et configuration, puis StateGraph et le moteur Pregel, et descendez dans l'ordre : PregelLoop tick → Channel → Checkpoint → Streaming → API fonctionnelle → Interruption et reprise → Orchestration de sous-graphes.

Voir la documentation officielle : LangGraph docs · GitHub.