Build something like this?

LangGraph: inside the agent runtime

LangGraph — a low-level orchestration framework for stateful, long-running LLM agents, built as a Python monorepo. libs/ ships eight independently versioned PyPI packages: the langgraph core runtime, langgraph-prebuilt agent APIs, a checkpointer family (base interfaces, Postgres and SQLite savers, a shared conformance suite), the langgraph-cli deployment tool, and the langgraph-sdk server client. Board grain: container-grade — each package is an opaque drill-down into its own L1 board.

8 layers2 insightsby Supportv3Published Oct 30, 2026

The map

The map · Spine

Architecture

What's on this map
  • Checkpoint Base · library package
  • Checkpointer Conformance Suite · library package
  • Postgres Checkpointer · library package
  • SQLite Checkpointer · library package
  • LangGraph CLI · library package
  • CLI Telemetry (Supabase) · external integration
  • Docker Engine · external integration
  • Example & Fixture Agent Apps · module
  • GitHub Template Repositories · external integration
  • langchain-core · library package
  • LangGraph Core · library package
  • LangGraph Platform Control Plane · external integration
  • LangGraph Server · external integration
  • LangSmith · external integration
  • PostgreSQL · postgresql
  • Prebuilt Agents · library package
  • PyPI · external integration
  • Repo Tooling & CI · infrastructure component
  • Python SDK · library package
  • SQLite · data store

The map · Layers

Layers8

+1 more

What's on each layer

Checkpoint Base

langgraph-checkpoint: shared persistence kernel of the checkpoint family. Defines the BaseCheckpointSaver and BaseStore contracts, checkpoint/metadata data model, ormsgpack-backed serde with a type allowlist, and in-memory/Redis reference implementations that langgraph-checkpoint-postgres, langgraph-checkpoint-sqlite and langgraph-checkpoint-conformance build against. Board grain: terminal (budgetVerdict fits, predicted 26 vs band 10-40, no drill-downs proposed).

  • BaseCache · class interface
  • Cache · domain group
  • Checkpoint ID Generator · module
  • Checkpoint Persistence · domain group
  • BaseCheckpointSaver · class interface
  • EncryptedSerializer · module
  • InMemoryCache · module
  • InMemorySaver · module
  • InMemoryStore · module
  • JsonPlusSerializer · module
  • Key-Value Store · domain group
  • Msgpack Safety Allowlist · module
  • RedisCache · module
  • Serde Event Hooks · module
  • Serde Types · class interface
  • Serialization · domain group
  • SerializerProtocol · class interface
  • AsyncBatchedBaseStore · module
  • BaseStore · class interface
  • Store Embeddings Helpers · module

Checkpointer Conformance Suite

langgraph-checkpoint-conformance: a published pytest suite that is the executable form of the BaseCheckpointSaver contract. A harness (validator + capability detector + registry) dispatches to per-capability spec modules exercising get_tuple/list/put/put_writes/delete/copy/prune/delta-history against any injected saver. Board grain: terminal (budgetVerdict fits, predicted 19 vs band 10-40, no drill-downs proposed).

  • Base Capability Specs · domain group
  • Capability Detector · engine component
  • Capability Report · service component
  • Checkpointer Registry · engine component
  • Conformance Harness · domain group
  • Conformance Public API · facade component
  • Conformance Spec Suite · domain group
  • Conformance Test Utilities · module
  • Conformance Validator · engine component
  • Copy Thread Spec · evaluation
  • Delete For Runs Spec · evaluation
  • Delete Thread Spec · evaluation
  • Delta Channel History Spec · evaluation
  • Extended Capability Specs · domain group
  • Get Tuple Spec · evaluation
  • List Spec · evaluation
  • Memory Saver Self-Test · evaluation
  • Prune Spec · evaluation
  • Put Spec · evaluation
  • Put Writes Spec · evaluation
  • Spec Shared Fixtures · module

Postgres Checkpointer

The production Postgres persistence backend for LangGraph: sync/async/shallow checkpoint savers and a pgvector-backed long-term store, both implementing langgraph-checkpoint's base contracts via psycopg3 with pooled connections and versioned SQL migrations. Terminal board: group-plan reports budgetVerdict 'fits' with no drill-down clusters proposed, so component grain is correct at this depth.

  • Async Connection Adapter · adapter component
  • Async Postgres Saver · repository component
  • Async Postgres Store · repository component
  • Checkpoint Saver · domain group
  • langgraph-checkpoint (base contracts) · library package
  • Long-Term Store · domain group
  • PostgreSQL · postgresql
  • Postgres Saver · repository component
  • Postgres Saver Base · engine component
  • Postgres Store · repository component
  • Shallow Postgres Saver · repository component
  • Sync Connection Adapter · adapter component

SQLite Checkpointer

langgraph-checkpoint-sqlite: SQLite-backed implementations of the checkpoint family's BaseCheckpointSaver, BaseStore and BaseCache contracts, in both sync and async (aiosqlite) form, plus sqlite-vec vector search on the store. The usual local-dev/test backend. Board grain: terminal (budgetVerdict fits, predicted 18 vs band 10-40, no drill-downs proposed).

  • AsyncSqliteSaver · adapter component
  • AsyncSqliteStore · repository component
  • BaseCache (contract) · class interface
  • BaseCheckpointSaver (contract) · class interface
  • BaseStore (contract) · class interface
  • SqliteCache · adapter component
  • Delta Channel History Helpers · engine component
  • SQLite Checkpoint Saver · domain group
  • SqliteSaver · adapter component
  • SQLite · data store
  • SQLite Store · domain group
  • SqliteStore · repository component

LangGraph CLI

`langgraph-cli` — the CLI tool that scaffolds, builds, runs and deploys LangGraph applications: config parsing, Docker image/compose build, local dev server, Platform deploys, dependency and template resolution. Board grain: terminal — group plan reads directory-fallback, budgetVerdict fits (39 predicted vs band 10-40), no drill-down candidates; groups below come from an actual read of the imports, not the flat directory listing the fallback proposed.

  • Command Telemetry · adapter component
  • Build Context Archive · module
  • CLI Entrypoint & Commands · module
  • CLI Test Suite · module
  • Config Resolution · module
  • uv Lockfile Resolution · module
  • Tracked-Package Detection · adapter component
  • Deploy Orchestration · module
  • Docker Build & Compose · module
  • Docker & Deploy Runtime · domain group
  • Docker Engine · external integration
  • Subprocess Runner · module
  • GitHub Template Archives · external integration
  • Platform Control-Plane Client · adapter component
  • LangGraph Platform Control Plane · external integration
  • Platform & External Integrations · domain group
  • Progress Reporting · module
  • PyPI · external integration
  • Config Schema & Generator · schema model
  • Supabase Logs Endpoint · external integration
  • Project Template Fetcher · adapter component
  • Shared Utilities · module

LangGraph Core

The `langgraph` core Python library: the Pregel/BSP graph execution engine, the StateGraph and functional (@entrypoint/@task) builder APIs, state channels, streaming, and shared internal utilities. Board grain: container-grade (over-band file-level plan, directory-fallback evidence) — two drill-downs: the Pregel execution engine and the Graph API & runtime primitives (builder APIs, channels, managed values, core types, `_internal` execution primitives).

  • Benchmarks · developer tooling
  • Core API & Types · domain group
  • Core API Internals · module
  • Graph Builder API · domain group
  • Graph Builder Internals · module
  • Internal Utilities · domain group
  • Checkpoint Base · boundary port
  • Prebuilt Agents · boundary port
  • Python SDK · boundary port
  • Graph API & Runtime Primitives · domain group
  • Pregel Execution Engine · engine component
  • Streaming · domain group
  • Stream Plumbing · module
  • Stream Transformers · adapter component
  • Test Suite · developer tooling

Graph API & Runtime Primitives

Pregel core: the langgraph library's graph-building DSL, channel/state-propagation primitives, managed values, and internal execution engine that implement the Pregel-style superstep runtime. Board grain: container-grade (the group plan's `_internal` cluster escalated over the L2 band and was resolved into domain groups plus two proposed drill-downs rather than inlined flat).

  • Aggregate & Barrier Channels · class interface
  • Benchmark Suite · developer tooling
  • Branch Spec · class interface
  • Base Channel · class interface
  • Channel Types · domain group
  • Core Runtime Types · domain group
  • Core Types & Runtime Context · module
  • Engine Internals · domain group
  • Errors, Warnings & Callbacks · module
  • Functional API (entrypoint/task) · facade component
  • Graph Builder API · domain group
  • Async Execution Primitives · engine component
  • Config Merging · module
  • Checkpoint Replay · engine component
  • Retry and Timeout Policy · module
  • Runnable Wrapping · engine component
  • Schema Typing Helpers · module
  • IsLastStep Managed Value · module
  • Managed Values · domain group
  • Managed Value Base · class interface
  • Message State Reducer · module
  • State Node Spec · class interface
  • Benchmarks · boundary port
  • Graph Builder Internals · boundary port
  • Pregel Execution Engine · boundary port
  • Public Config Accessors · module
  • Pregel Scratchpad · module
  • StateGraph · class interface
  • UI Message Helpers · module
  • Value Channels · class interface

Pregel Execution Engine

The Pregel BSP execution engine: the superstep loop, task planning/execution, checkpointing, channel I/O, streaming/debug surface, and the remote-execution proxy that together run a compiled LangGraph graph. Terminal component-grain board (one node per significant file, grouped into 6 lifecycle-role containers) — the plan's own budget read over-band because the unit's fixed 22-file scope exceeds the L2 high band, not because further drill-down is warranted.

  • BSP Superstep Loop · domain group
  • Checkpoint & Channel I/O · domain group
  • Contracts & Utilities · domain group
  • Graph API & Runtime Primitives · boundary port
  • Stream Plumbing · boundary port
  • Stream Transformers · boundary port
  • Task Planner (_algo) · engine component
  • Runnable Resolution (_call) · adapter component
  • Checkpoint Store Mapper · repository component
  • Debug Stream Builder · handler component
  • Graph Drawing Engine · engine component
  • Background Executor · adapter component
  • Channel I/O Helpers · handler component
  • Pregel Logger · module
  • Pregel Loop · engine component
  • Pregel Facade · facade component
  • Message Stream Handler · adapter component
  • Pregel Protocol · class interface
  • Channel Read / Pregel Node · handler component
  • RemoteGraph · adapter component
  • Remote Run Stream Adapter · adapter component
  • Retry & Timeout Policy · adapter component
  • Pregel Runner · engine component
  • Tool Call Stream Handler · adapter component
  • Types (Deprecated Re-export) · module
  • Pregel Utilities · module
  • Graph Validation · module
  • Channel Write · handler component
  • Remote Execution · domain group
  • Streaming & Debug Surface · domain group
  • Task Execution & Retry · domain group

Pregel Facade

Pregel main module: the Pregel runtime class and its NodeBuilder, implementing the Bulk Synchronous Parallel actor/channel execution engine that powers LangGraph. Terminal component-level board — the group plan for this single-file unit reads under-band with no drill-downs proposed, so main.py is documented as one leaf component rather than split further.

  • Task Planner (_algo) · boundary port
  • Runnable Resolution (_call) · boundary port
  • Checkpoint Store Mapper · boundary port
  • Debug Stream Builder · boundary port
  • Graph Drawing Engine · boundary port
  • Channel I/O Helpers · boundary port
  • Pregel Loop · boundary port
  • Message Stream Handler · boundary port
  • Pregel Protocol · boundary port
  • Channel Read / Pregel Node · boundary port
  • Retry & Timeout Policy · boundary port
  • Pregel Runner · boundary port
  • Tool Call Stream Handler · boundary port
  • Pregel Utilities · boundary port
  • Graph Validation · boundary port
  • Channel Write · boundary port
  • Pregel · engine component

Prebuilt Agents

langgraph-prebuilt: high-level agent constructs (ToolNode, ReAct agent graph, tool-call streaming, validation, HITL types) on top of the core runtime. Grain: terminal (component-level) — budgetVerdict fits, no drill-downs.

  • create_react_agent · agent orchestrator
  • Interrupt Types · human in the loop
  • ToolCallStream · class interface
  • ToolCallTransformer · adapter component
  • ToolNode · tool node
  • ValidationNode · agent guardrail

Python SDK

The LangGraph Python SDK: client library for the LangGraph API — v3 thread-streaming protocol with pluggable transports, auth hooks, runtime/cache modules and the async/sync parity test harness. Grain: container-grade with 1 drill-down — the async & sync client library (mirrored resource clients, HTTP transport, schema, errors, SSE, encryption) is its own board.

  • Async & Sync Client Library · domain group
  • Auth & Encryption · domain group
  • Auth Middleware · adapter component
  • Client Core & Facade · domain group
  • HTTP Response Cache · module
  • Integration Test Harness · domain group
  • Integration Test Graphs · developer tooling
  • Integration Test Scripts · developer tooling
  • Multi-Cursor Replay Buffer · engine component
  • Checkpoint Base · boundary port
  • LangGraph Core · boundary port
  • Resource Clients (Async/Sync) · domain group
  • Thread Stream Client (v3) · adapter component
  • SDK Integration Tests · developer tooling
  • Runtime Context · module
  • Shared Utilities · module
  • Stream Controllers · engine component
  • Stream Decoders · module
  • Streaming Subsystem (v3 Protocol) · domain group
  • Streaming Tests · developer tooling
  • Stream Subscription · module
  • Stream Transports · adapter component
  • Test Suite · domain group
  • Unit Tests · developer tooling

Async & Sync Client Library

langgraph-sdk: async and sync HTTP clients (mirrored via unasync) for the LangGraph Platform API, shared utilities, Auth/Encryption extensions, schema models, and integration scripts. Group-plan was under-band (1 coupling cluster vs band 5-20) so this board is terminal (component-grade); no drill-downs created.

  • AssistantsClient · adapter component
  • Async Client · domain group
  • Auth & Encryption · domain group
  • Auth · engine component
  • CronClient · adapter component
  • Encryption · engine component
  • HttpClient · engine component
  • Integration Test Helpers · module
  • Integration Scripts · domain group
  • Cancel Flow Integration Script · module
  • Update State Integration Script · module
  • LangGraphClient (Async) · facade component
  • Thread Stream Client (v3) · boundary port
  • RunsClient · adapter component
  • SDK Entry Point · facade component
  • SDK Errors · module
  • SDK Schema Models · schema model
  • Shared Utilities · module
  • SSE Stream Parser · engine component
  • StoreClient · adapter component
  • SyncAssistantsClient · adapter component
  • Sync Client · domain group
  • SyncCronClient · adapter component
  • SyncHttpClient · engine component
  • SyncLangGraphClient · facade component
  • SyncRunsClient · adapter component
  • SyncStoreClient · adapter component
  • SyncThreadsClient · adapter component
  • ThreadsClient · adapter component

What to notice

Inbound · Signals

Insights2 analyses

2Insights
1Critical
risk1strength1
Read all 2

interrupt() matches resumes by call position, not name, inside Core Types

risk · critical · verified

interrupt() takes a per-task counter from the scratchpad and returns resume[idx], so a resumed node must call its interrupts in the same order as the first run; reorder, add or conditionally skip one and it silently receives another prompt's answer. That logic sits in Core Types & Runtime Context, which 18 of 26 elements here depend on, 11 directly with no fallback, including StateGraph and the Functional API.

Impact: A node that reorders, adds or conditionally skips an interrupt() call gets another prompt's resume value silently, with no error to point at the mismatch, and the risk travels through every one of Core Types' 11 dependents.

Recommendation (small effort): Call interrupt() unconditionally and in a fixed order within a node, and add a regression test that resumes a multi-interrupt node out of order to catch positional drift before it reaches State Node Spec, StateGraph or the Functional API.

  1. Schema Typing Helpers
  2. Core Types & Runtime Context
  3. State Node Spec
  4. Errors, Warnings & Callbacks
  5. Functional API (entrypoint/task)
  6. StateGraph
  7. Aggregate & Barrier Channels

Pregel is a single 3,700-line class with every sync path hand-duplicated for async

strength · medium · verified

The Pregel class (main.py:449-4190) is the sole entry point into the runtime: all 16 outbound calls it makes reach the checkpoint mapper, channel I/O helpers, task planner, loop and runner — nothing else in the file has a way out. That concentration comes with a duplication cost: bulk_update_state and abulk_update_state are each about 470 hand-kept lines, as are the stream/astream pairs, so a fix has to land twice, as the recent nested checkpoint_ns regression did.

Impact: Every bug fix or behavior change to checkpointing, I/O shaping, task planning or execution has to be applied once for the sync path and once for the async path inside this class, with no shared implementation to catch a missed side.

Recommendation (medium effort): Extract the shared logic behind bulk_update_state/abulk_update_state and the stream/astream pairs into one implementation, so a fix like the checkpoint_ns one lands once, without giving up the single entry point into the runtime.

  1. Pregel
  2. Checkpoint Store Mapper
  3. Checkpoint Store Mapper
  4. Channel I/O Helpers
  5. Channel I/O Helpers
  6. Task Planner (_algo)
  7. Task Planner (_algo)
  8. Pregel Loop
  9. Pregel Loop
  10. Pregel Runner
  11. Pregel Runner

In the code

Database 29 · Clients 3

Inbound · From code

Database

29tables

No primary key
0
Partitioned
0
Deprecated
0
Tables per schema
  • public22
  • main7

Tables

+25 more

Inbound · From code

AuthZ

0roles

Permissions
0
Policies
2
Resource types
5
Permissions per role

    Roles

      Inbound · From code

      Clients

      3clients

      HTTP
      3
      gRPC
      0
      Calls
      100
      Calls by target
      • langgraph-server100

      Clients