LangGraph architecture overview

源码版本1.2.9

In one sentence

LangGraph is a state-machine-style agent orchestration framework built around a channel + Pregel loop core. At the construction layer, StateGraph compiles nodes and edges into a Pregel executable. At runtime, PregelLoop.tick repeatedly runs "read channels → schedule tasks → write channels → checkpoint" until convergence. Along the way, StreamMux provides multi-mode streaming output, interrupt / Command enable human-in-the-loop collaboration, the BaseCheckpointSaver family handles thread-level persistence, and @entrypoint / @task provide a functionally equivalent API.

Layers

One sentence per layer

• Startup & config: RunnableConfig carries thread_id / store / checkpointer; StateSnapshot is the immutable snapshot returned by get_state.
• Graph construction: StateGraph is the user entry point. add_node / add_edge / add_conditional_edges define the topology; compile produces a CompiledStateGraph (i.e. a Pregel instance).
• Pregel engine: Pregel is the compiled artifact; stream / invoke / astream are its entry points. PregelLoop.tick runs a single step, PregelRunner runs tasks concurrently, and _algo handles task preparation, writeback, and interrupt decisions.
• Channel: BaseChannel abstracts the update / consume / checkpoint semantics. LastValue overwrites by default, Topic is pub-sub, and Binop aggregates via a binary operator.
• Checkpoint: BaseCheckpointSaver exposes put / get / list. There are three implementations — InMemory, Sqlite, Postgres — with sync and async support.
• Streaming: StreamMux handles multi-mode mux/demux, and each transformer (values / updates / messages / debug / lifecycle / subgraph / checkpoints / tasks) produces a different view.
• Functional API: @entrypoint wraps a function into a Pregel executable; @task declares a concurrent subtask.
• Interrupt & subgraph: interrupt() triggers a human-in-the-loop pause, Command(resume/goto/update) drives resumption and routing, and Send implements fan-out.

Layering motivation

LangGraph fully decouples "how the graph is defined" (graph construction), "how it executes" (Pregel), "how state updates" (channel), "how it persists" (checkpoint), "how it is viewed" (stream), "the functional equivalent" (func), "how it talks to a human" (interrupt), and "how it is orchestrated" (subgraph). Swapping the checkpoint backend does not affect execution logic; swapping stream modes does not affect the graph definition; adding interrupts does not change the channels. Pregel is the single hub — every execution path ultimately goes through PregelLoop.tick.

Common misreadings

• "LangGraph is just LangChain's graph wrapper" — No. It has an independent Pregel execution engine and does not depend on LangChain's chain/agent abstractions; it can be used on its own.
• "Channel is just state" — Channel is the update-semantics layer for state. Different channel types (LastValue / Topic / Binop) determine how state is merged, which is what makes it more capable than an ordinary state machine.
• "@entrypoint is syntactic sugar for StateGraph" — Functionally equivalent, but implemented differently. The func API goes through the FunctionalAPI path and is ultimately also compiled into Pregel, but its concurrency and join semantics are closer to those of ordinary functions.

Recommended reading order

Start with Startup & config, then StateGraph and Pregel engine, then work through PregelLoop tick → Channel → Checkpoint → Streaming → Functional API → Interrupt & resume → Subgraph orchestration.

See official docs: LangGraph docs · GitHub.