# https://github.com/langchain-ai/langgraphjs Project Manual Generated at: 2026-06-18 09:44:01 UTC ## Table of Contents - [Core Framework: StateGraph, Channels & Pregel Runtime](#page-1) - [Persistence, Checkpointing & Long-Term Memory](#page-2) - [SDK, API Server, CLI & Frontend Framework Integrations](#page-3) - [Streaming Protocols, Prebuilt Patterns & Multi-Agent Ecosystem](#page-4) ## Core Framework: StateGraph, Channels & Pregel Runtime ### Related Pages Related topics: [Persistence, Checkpointing & Long-Term Memory](#page-2), [Streaming Protocols, Prebuilt Patterns & Multi-Agent Ecosystem](#page-4)
Related Source Files The following source files were used to generate this page: - [libs/langgraph-core/src/graph/state.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/state.ts) - [libs/langgraph-core/src/graph/graph.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/graph.ts) - [libs/langgraph-core/src/graph/annotation.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/annotation.ts) - [libs/langgraph-core/src/graph/messages_reducer.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/messages_reducer.ts) - [libs/langgraph-core/src/channels/index.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/channels/index.ts) - [libs/langgraph-core/src/pregel/algo.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/pregel/algo.ts) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) - [libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json) - [libs/langgraph-core/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/package.json) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md)
# Core Framework: StateGraph, Channels & Pregel Runtime ## Purpose and Scope The Core Framework — primarily the `libs/langgraph-core` package and the public `langgraph` entry point — provides the runtime that turns a developer-defined graph of nodes and edges into a stateful, multi-actor application. Its stated mission is to "build stateful, multi-actor applications with LLMs" ([libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json)). The framework is explicitly inspired by [Pregel](https://research.google/pubs/pub37252/), [Apache Beam](https://beam.apache.org/), and [NetworkX](https://networkx.org/documentation/latest/), as noted in the project README. Pregel and Beam supply the *superstep* and *channel* execution model, while NetworkX shapes the public graph-construction interface ([README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md)). The framework is split into three cooperating layers, each living in `libs/langgraph-core/src`: | Layer | Module | Role | | --- | --- | --- | | Graph definition | `graph/` | `StateGraph`, node/edge wiring, state schema | | Channels | `channels/` | Per-key state containers updated each superstep | | Pregel runtime | `pregel/` | Superstep scheduling, fan-out, checkpointing | Source: [libs/langgraph-core/src/graph/state.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/state.ts), [libs/langgraph-core/src/channels/index.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/channels/index.ts), [libs/langgraph-core/src/pregel/algo.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/pregel/algo.ts). ## StateGraph and Annotation A `StateGraph` is the developer-facing API used to assemble a graph: you declare a state schema via `Annotation`, add nodes (functions that read and return partial state), and connect them with conditional or static edges. The `create-langgraph` CLI scans for these patterns to auto-generate a `langgraph.json` deployment file: ```ts // ESM exports that the scanner recognises export const agent = createAgent({ model, tools }); export const graph = new StateGraph(annotation).compile(); export const app = workflow.compile(); ``` Source: [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md). The annotation module is what gives each state key its reducer — the function that merges the partial update produced by a node into the existing channel value. The `messages_reducer` module is the canonical reducer for the `messages` key, handling append, replace, and ID-based updates of chat messages ([libs/langgraph-core/src/graph/messages_reducer.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/graph/messages_reducer.ts)). A subtle but important constraint surfaces in community issue [#1722](https://github.com/langchain-ai/langgraphjs/issues/1722): LangGraph Studio's Chat tab does not appear when a graph is built inside a class. Because the `create-langgraph` scanner only matches *exported* call sites of `createAgent`, `new StateGraph(...).compile()`, and `workflow.compile()`, encapsulation inside a class hides the graph from the tooling — a useful reminder that graph construction is a top-level pattern in this framework. ## Channels Channels are the per-key storage primitives the runtime reads from and writes to each superstep. They are the bridge between the developer-friendly `StateGraph` model and the Pregel-style execution engine. The channel layer exposes: - `BaseChannel` — abstract channel with `update`, `get`, `consume`, and `checkpoint` operations. - Reducer-backed channels (e.g. `BinaryOperatorAggregate`, `LastValue`) — apply a reducer function to merge a node's partial return into the current value. - Topic and named-barrier channels — used for fan-in/fan-out patterns such as Send / Map-Reduce. Source: [libs/langgraph-core/src/channels/index.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/src/channels/index.ts). Channels also implement the `checkpoint` interface consumed by `@langchain/langgraph-checkpoint`, the companion package that defines "base interfaces for LangGraph checkpoint savers" ([libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json)). This is how the runtime persists channel state to backends like an in-memory `MemorySaver` or a Postgres store. The `libs/checkpoint/src/store/base.ts` file shows the lower-level storage operations (`PutOperation` with `namespace`, `key`, `value`) that a durable channel writer uses, demonstrating that channels are not just in-memory buffers — they can be backed by a long-term store for human-in-the-loop and time-travel debugging ([libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)). ## Pregel Runtime The Pregel runtime (`libs/langgraph-core/src/pregel/`) executes the compiled graph. It runs the canonical superstep loop: ```mermaid flowchart LR A[Plan superstep
from pending nodes] --> B[Read channel values
into node input] B --> C[Invoke nodes
in parallel] C --> D[Apply channel
reducers / writes] D --> E{More
steps?} E -- yes --> A E -- no --> F[Emit final
output] ``` The `algo.ts` module houses the superstep planner, the conditional-edge resolver, and the integration with channels. By staying faithful to Pregel's BSP (Bulk Synchronous Parallel) model, the runtime preserves the determinism and replayability guarantees that checkpointing depends on. The framework's description in the package metadata underscores that this runtime is the foundation of features higher-level libraries build on: "out-of-box support for streaming, short-term and long-term memory and human-in-the-loop" ([libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md), [libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md)). These higher-level libraries (supervisor, swarm, CUA) compile their multi-agent topologies into the same `StateGraph` + `Pregel` primitives, which is why they can be deployed uniformly through the CLI scanner. Community issue [#107](https://github.com/langchain-ai/langgraphjs/issues/107) notes that the Python version supports PNG visualization of a `StateGraph`; in the JS port, the same graph metadata is introspectable but no first-party visualizer ships with the runtime. ## Configuration and Common Pitfalls The core framework ships as dual ESM/CJS with a strict Node engine floor: | Package | Engines | Peer dependencies | | --- | --- | --- | | `langgraph` | `node >= 20` | `@langchain/core ^1.1.44`, `zod ^3.25.32 \|\| ^4.1.0`, `zod-to-json-schema ^3.x` | | `@langchain/langgraph-checkpoint` | `node >= 18` | `@langchain/core ^1.1.48` | Source: [libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json), [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json). Two recurring community failure modes are worth flagging when configuring this runtime: 1. **`AsyncLocalStorage` in the browser** — issue [#1699](https://github.com/langchain-ai/langgraphjs/issues/1699) reports that `async_hooks` cannot be used in the browser under `@langchain/core` 1.0.0-alpha. The Pregel runtime relies on `AsyncLocalStorage` for context propagation per run, so browser-only deployments must remain on the stable core line. 2. **Streaming through a proxy** — issue [#1295](https://github.com/langchain-ai/langgraphjs/issues/1295) describes `useStream` failing to update messages when a Next.js proxy sits in front of a LangGraph server. The root cause lies in how SSE events emitted by the runtime are re-encoded by the proxy; the framework itself streams correctly when consumed directly. ## See Also - [Checkpoint and Long-Term Memory](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/README.md) - [LangGraph SDK and Streaming](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [Multi-Agent Supervisor](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md) - [Swarm Multi-Agent](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - [Computer Use Agent](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) --- ## Persistence, Checkpointing & Long-Term Memory ### Related Pages Related topics: [Core Framework: StateGraph, Channels & Pregel Runtime](#page-1), [SDK, API Server, CLI & Frontend Framework Integrations](#page-3)
Related Source Files The following source files were used to generate this page: - [libs/checkpoint/src/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/base.ts) - [libs/checkpoint/src/types.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/types.ts) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/checkpoint/src/store/memory.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/memory.ts) - [libs/checkpoint-postgres/src/index.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/index.ts) - [libs/checkpoint-postgres/src/migrations.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/migrations.ts) - [libs/checkpoint-redis/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-redis/README.md) - [libs/checkpoint-validation/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-validation/README.md) - [libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md) - [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json)
# Persistence, Checkpointing & Long-Term Memory ## Overview and Core Concepts LangGraph.js provides two complementary persistence abstractions that together power durable, stateful agents. The first is **checkpointing**, which captures the short-term, per-thread state of a graph run at every super-step and lets an execution be paused, replayed, resumed, or branched ("forked") after a failure. The second is a **store**, which provides long-term, cross-thread memory keyed by a hierarchical namespace. Both are wired into a graph at compile time via `checkpointer` and `store` arguments to `compile()` (Source: [libs/langgraph-supervisor/README.md:18-30](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md)). Checkpointing is what enables the headline features described in the project README: **durable execution**, **human-in-the-loop** (`interrupt`), and **comprehensive memory** (Source: [libs/langgraph/README.md:9-19](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md)). A `thread` represents one ongoing conversation or run; a `checkpoint` is one snapshot of that thread's state; `pending writes` are intermediate channel mutations not yet committed to a checkpoint. ## Checkpoint Saver Architecture The core contract is the abstract `BaseCheckpointSaver` class in `libs/checkpoint/src/base.ts`. Every concrete saver must implement `getTuple`, `list`, `put`, and `putWrites`, and may override `deleteThread` (Source: [libs/checkpoint/src/base.ts:60-110](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/base.ts)). The data model is intentionally minimal so that multiple backends can be supported: | Type | Purpose | Source | | --- | --- | --- | | `Checkpoint` | Snapshot of channel values and versions at a step | `libs/checkpoint/src/base.ts` | | `CheckpointMetadata` | `source` (`input`/`loop`/`update`/`fork`), `step`, `parents`, channel counters | `libs/checkpoint/src/types.ts` | | `CheckpointTuple` | `config` + `checkpoint` + `metadata` + `parentConfig` + `pendingWrites` | `libs/checkpoint/src/base.ts` | | `PendingWrite` | `[channel, value]` tuple produced by a node | `libs/checkpoint/src/types.ts` | | `DeltaChannelHistory` | Per-channel on-path writes plus an ancestor `seed` value (beta) | `libs/checkpoint/src/types.ts` | A `CheckpointMetadata` distinguishes how a checkpoint was created: `input` (initial invoke/stream), `loop` (created inside the Pregel loop), `update` (manual state update), or `fork` (copy of another) (Source: [libs/checkpoint/src/types.ts:60-95](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/types.ts)). The `step` is `-1` for the first `input` checkpoint, `0` for the first `loop` checkpoint, and increments from there. The base class also defines a `serde: SerializerProtocol` slot — by default `JsonPlusSerializer` — that any concrete saver can swap to control how channel values are encoded (Source: [libs/checkpoint/src/base.ts:64-67](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/base.ts)). ```mermaid flowchart LR A[Graph Node] -->|PendingWrite| B[BaseCheckpointSaver] B -->|putWrites| C[(Backend Storage)] B -->|put / getTuple| C C -->|list| D[Pregel Loop] D -->|fork / resume| A H[compile store] --> S[BaseStore] S -->|batch: put / get / search| C ``` Concrete implementations live in dedicated packages. `MemorySaver` (in-process, for development) and `PostgresSaver` share the contract above, with `PostgresSaver` using `pg.Pool` and configurable `schema` (default `public`) (Source: [libs/checkpoint-postgres/src/index.ts:18-45](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/index.ts)). Schema management is delegated to `getMigrations`, which emits DDL for the `checkpoint_*` and `checkpoint_writes` tables and is applied automatically (Source: [libs/checkpoint-postgres/src/migrations.ts:1-25](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/migrations.ts)). For Redis, the `RedisSaver` and memory-optimized `ShallowRedisSaver` ship in `@langchain/langgraph-checkpoint-redis`; both require **RedisJSON** and **RediSearch** modules (bundled in Redis 8.0+, otherwise via Redis Stack) (Source: [libs/checkpoint-redis/README.md:13-29](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-redis/README.md)). ## Long-Term Memory Stores Where a checkpointer scopes its keys to a single `thread_id`, a store keys items by a `namespace: string[]` plus a `key: string`, giving a folder-like path that spans users, sessions, and applications (Source: [libs/checkpoint/src/store/base.ts:25-55](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)). The `PutOperation` and `SearchOperation` interfaces cover the CRUD plus query surface; setting `value: null` in a `PutOperation` signals a delete (Source: [libs/checkpoint/src/store/base.ts:60-95](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)). `InMemoryStore` is the reference implementation. It indexes items lazily based on an optional `IndexConfig`, tokenizing JSON paths (e.g. `metadata.title`) and supporting vector similarity search alongside lexical query strings (Source: [libs/checkpoint/src/store/memory.ts:25-55](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/memory.ts)). A `RedisStore` counterpart is shipped by the Redis package. The supervisor pattern shows the typical wiring: a `MemorySaver` for per-thread checkpoints plus an `InMemoryStore` for cross-agent memory, both passed to `compile()` (Source: [libs/langgraph-supervisor/README.md:18-30](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md)). ## Custom Savers and Validation Teams that need a custom backend (e.g., DynamoDB, Spanner) can extend `BaseCheckpointSaver` and validate it with `@langchain/langgraph-checkpoint-validation`. The validation tool requires Node 20, 22, or 24, and runs against a user-supplied `CheckpointerTestInitializer` that knows how to provision and clean up a checkpointer instance (Source: [libs/checkpoint-validation/README.md:9-15](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-validation/README.md)). Initializer functions may be sync or async; the harness awaits them as needed. ## Operational Notes and Community Context - **Engines**: `@langchain/langgraph-checkpoint` declares `node >= 18` (Source: [libs/checkpoint/package.json:6-9](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json)). Browser users have reported that `async_hooks` (used by some checkpoint paths) cannot run in the browser at `@langchain/core` `^1.0.0-alpha.x` (issue #1699); production deployments therefore typically target a Node server. - **Studio integration**: When a graph is built inside a class, LangGraph Studio may fail to surface the Chat tab (issue #1722). Keeping the compiled graph reachable as a top-level export, alongside the configured `checkpointer`, is the recommended workaround. - **Streaming proxies**: The React `useStream` hook can fail to populate state when wrapped behind a Next.js proxy that strips SSE framing (issue #1295); this is a transport concern rather than a checkpointing one, but it affects how persisted state is surfaced to UIs. - **Delta channel history**: `BaseCheckpointSaver.getDeltaChannelHistory` exposes a per-channel view of writes plus the nearest ancestor seed, marked as beta in the source (Source: [libs/checkpoint/src/types.ts:10-30](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/types.ts)). Field names and semantics may change. ## See Also - [Durable execution](https://docs.langchain.com/oss/javascript/langgraph/durable-execution) - [Human-in-the-loop / interrupts](https://docs.langchain.com/oss/javascript/langgraph/interrupts) - [Memory concepts](https://docs.langchain.com/oss/javascript/langgraph/memory) - [LangSmith deployments](https://docs.langchain.com/langsmith/deployments) - API Reference: [langchain-langgraph](https://reference.langchain.com/javascript/langchain-langgraph) --- ## SDK, API Server, CLI & Frontend Framework Integrations ### Related Pages Related topics: [Core Framework: StateGraph, Channels & Pregel Runtime](#page-1), [Persistence, Checkpointing & Long-Term Memory](#page-2), [Streaming Protocols, Prebuilt Patterns & Multi-Agent Ecosystem](#page-4)
Related Source Files The following source files were used to generate this page: - [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [libs/sdk-react/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [libs/create-langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/package.json) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json) - [libs/langgraph-cua/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/package.json) - [libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) - [README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md)
# SDK, API Server, CLI & Frontend Framework Integrations The `langgraphjs` monorepo ships a complete stack for moving from a locally defined LangGraph to a deployable agent service. The pieces are layered: a server-runtime graph library ([`libs/langgraph`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json)), a stateful checkpoint + store layer ([`libs/checkpoint/src/store/base.ts`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)), a thin server-side API client ([`libs/sdk`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md)), React/Vue framework bindings ([`libs/sdk-react`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md)), and a project scaffolder CLI ([`libs/create-langgraph`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md)). Together they let developers define a graph in TypeScript, expose it over HTTP, stream its execution to a UI, and persist long-term memory. ## LangGraph JS/TS SDK The `@langchain/langgraph-sdk` package is the canonical client for the LangGraph API server. It exposes a single `Client` class that, by default, points at `http://localhost:2024` (the URL of `langgraph dev`) when no `apiUrl` is provided ([`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md)). Five sub-clients hang off the root client, each wrapping a single API surface: | Sub-client | Purpose | Source | | --- | --- | --- | | `client.threads` | Create threads, manage state, and stream runs | [`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) | | `client.assistants` | CRUD for assistants (schemas, graphs, versions) | [`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) | | `client.runs` | Trigger/join/cancel runs without streaming | [`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) | | `client.crons` | Schedule recurring runs | [`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) | | `client.store` | Namespaced KV + semantic store | [`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) | The recommended entry point for streaming is `client.threads.stream({ assistantId: "my-agent" })`, which returns a `ThreadStream` with typed, lazy projections: `thread.messages`, `thread.toolCalls`, `thread.values`, `thread.output`, `thread.interrupts`, `thread.subgraphs`, `thread.subagents`, plus media iterators (`thread.audio`, `thread.images`, `thread.video`, `thread.files`) and a custom `thread.extensions.` channel ([`libs/sdk/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md)). The store sub-client operates on the data shape defined in [`libs/checkpoint/src/store/base.ts`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts), where a `PutOperation` is described by a hierarchical `namespace` (e.g. `["documents", "user123"]`), a `key`, and a JSON-serializable `value` (or `null` to delete). ## React & Vue Frontend Integrations The `@langchain/react` package (v1) is a v2-native React SDK that ships a `useStream` hook for live UI updates. Always-on root projections (`values`, `messages`, `toolCalls`, `interrupts`) cost zero per-subscription, while less common namespaces — subagent messages, media streams, submission queue, message metadata, raw channels — are opt-in via small companion selector hooks that open ref-counted subscriptions and release them on unmount ([`libs/sdk-react/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md)). The transport is session-based and automatically re-attaches on remount, eliminating older flows like `reconnectOnMount` or `joinStream`. `useStream()` infers state, tool calls, and subagent state maps from the agent brand, and the hosted-server path and custom-adapter path form a single discriminated union so they cannot be mixed at compile time. A parallel Vue adapter exists; the latest published release is `@langchain/vue@1.0.24`, which tracks the `@langchain/langgraph-sdk` family ([community release notes](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/CHANGELOG.md)). ```mermaid flowchart LR UI[React/Vue UI] -->|useStream| Hook[Selector Hooks] Hook -->|SSE| API[LangGraph API Server] API -->|invoke| Graph[Compiled StateGraph] Graph -->|read/write| Store[(Checkpoint + Store)] Graph -->|tokens| API API -->|events| Hook ``` ### Known integration caveats - **#1295 — useStream through a Next.js proxy.** When `useStream` is consumed behind a Next.js API proxy, the hook may receive and parse SSE events correctly but still fail to populate `messages` or `values`. This is an open regression observed against `@langchain/langgraph-sdk@0.0.84` and is the most active frontend-streaming bug in the issue tracker ([issue #1295](https://github.com/langchain-ai/langgraphjs/issues/1295)). - **#1699 — async_hooks in the browser.** Versions of `@langchain/core` in the `^1.0.0-alpha.x` range cannot use `async_hooks` in a browser environment, which surfaces in proxy/middleware paths used by the SDK ([issue #1699](https://github.com/langchain-ai/langgraphjs/issues/1699)). - **#504 — Vercel data-stream protocol.** A long-standing request asks LangGraph to natively speak Vercel's AI-SDK data-stream protocol so React apps already using the AI SDK client can adopt LangGraph as a drop-in ([issue #504](https://github.com/langchain-ai/langgraphjs/issues/504)). - **#1722 — Studio Chat tab inside a class.** LangGraph Studio fails to surface the Chat tab when the graph is constructed inside a class because the inspector looks for module-scope agent exports ([issue #1722](https://github.com/langchain-ai/langgraphjs/issues/1722)). ## Project Scaffolding CLI `create-langgraph` is the official CLI for bootstrapping a project and for reverse-engineering a `langgraph.json` config from an existing codebase ([`libs/create-langgraph/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md)). It exposes two subcommands: - **`create-langgraph`** — downloads a selected template from GitHub, extracts it to a target directory, optionally initializes Git, and prints next steps. - **`create-langgraph config [path]`** — scans a project for LangGraph agents and writes a `langgraph.json` configuration. Detection covers `createAgent({ model, tools })`, `new StateGraph(...).compile()`, and the workflow-builder pattern `workflow.compile()` / `builder.compile()` across both ESM (`export const …`) and CommonJS (`module.exports` / `exports.…`) styles. **Only exported agents are included**; unexported ones are listed as warnings, which directly addresses issue #1722's underlying detection rule. The CLI is built on `@clack/prompts` and `commander`, ships as an ESM package, and is published under `create-langgraph@1.1.5` ([`libs/create-langgraph/package.json`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/package.json)). ## See Also - [Graph runtime and streaming core](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md) - [Checkpoint & Store API](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [Computer-Use Agent (`@langchain/langgraph-cua`)](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/package.json) - [React SDK deep dive](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md) - [Vercel AI-SDK interop discussion (#504)](https://github.com/langchain-ai/langgraphjs/issues/504) --- ## Streaming Protocols, Prebuilt Patterns & Multi-Agent Ecosystem ### Related Pages Related topics: [Core Framework: StateGraph, Channels & Pregel Runtime](#page-1), [SDK, API Server, CLI & Frontend Framework Integrations](#page-3)
Related Source Files The following source files were used to generate this page: - [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [libs/sdk-react/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md) - [libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md) - [libs/sdk-angular/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/README.md) - [libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts) - [libs/sdk-svelte/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/README.md) - [libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md) - [libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - [libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [examples/streaming/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/examples/streaming/package.json) - [README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md)
# Streaming Protocols, Prebuilt Patterns & Multi-Agent Ecosystem ## Overview LangGraph.js is a JavaScript/TypeScript framework for building stateful, long-running agent applications. The repository is organised as a monorepo that ships a **core graph runtime**, a **streaming-capable HTTP/WebSocket SDK**, **framework adapters** (React, Vue, Angular, Svelte), and a family of **prebuilt multi-agent libraries** (supervisor, swarm, computer-use-agent). Source: [README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md) and [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md). ## Streaming Protocols ### V2-Native Streaming Protocol The current SDK family is built around a **v2 streaming protocol** that is session-based and supports automatic re-attach on remount. The protocol supersedes the older `reconnectOnMount` / `joinStream` choreography. Source: [libs/sdk-react/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md) ("v2-native streaming protocol. Session-based transport with automatic re-attach on remount; no more `reconnectOnMount` / `joinStream` dance.") The transport is **discriminated** between a hosted Agent Server path and a custom-adapter path; mixing them is a compile-time error. The root `useStream` / `injectStream` / `useStream` (Svelte) handle exposes always-on projections for `values`, `messages`, `toolCalls`, and `interrupts`, with namespaced data (subagents, subgraphs, media, submission queue, per-message metadata) delivered through ref-counted selector hooks so components only pay for data they consume. Source: [libs/sdk-react/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md). ### Framework Adapters and Stream Channels Each framework adapter normalises the protocol to its native reactivity primitive: | Framework | Package | Reactive primitive | Stream entry point | | --- | --- | --- | --- | | React | `@langchain/react` | Hook return value | `useStream({ assistantId, apiUrl })` | | Vue | `@langchain/vue` | `ref` / computed | `useStream({ assistantId, apiUrl })` | | Angular | `@langchain/angular` | Angular Signals | `injectStream({...})` | | Svelte 5 | `@langchain/svelte` | Getters on a stable handle | `useStream({ assistantId, apiUrl })` | For Angular, the returned handle is signal-based: `stream.toolCalls()` (a `Signal[]>`), `stream.interrupts()` (a `Signal[]>`), and `stream.isLoading()` (a `Signal`) are driven by root-namespace lifecycle events. Source: [libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts). Svelte exposes the same fields as getters on a stable `stream` handle so templates and `$derived` expressions track updates automatically — destructuring freezes the value, so callers must use `stream.messages` rather than `const { messages } = stream`. Source: [libs/sdk-svelte/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/README.md). ### Custom Transports and Browser Considerations For non-default backends the SDK exposes an `AgentServerAdapter` interface, with an `HttpAgentServerAdapter` reference implementation, that can target SSE, WebSocket, or a custom HTTP boundary. Source: [libs/sdk-react/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/README.md) and [libs/sdk-svelte/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/README.md). Community issue #1295 documents a known edge case where `useStream` fails to populate `messages` / `values` when the agent server is reached through a Next.js API proxy, even though the underlying SSE events arrive correctly. Community issue #1699 tracks browser-side incompatibility between `@langchain/core` 1.0.0-alpha and Node's `async_hooks`. These are environment-level caveats rather than protocol defects. Community issue #504 (Vercel AI SDK data-stream protocol) highlights ongoing interest in adopting the Vercel `data-stream` wire format for drop-in compatibility with the AI SDK client. The v2 protocol's discriminated transport design is the foundation that would make such an adapter possible; today clients must continue using the SDK's own projections. ## Prebuilt Multi-Agent Patterns ### Supervisor and Swarm Two first-party libraries implement the most common multi-agent coordination styles. The **supervisor** library creates a hierarchical system in which a central supervisor agent decides which specialised agent to invoke and mediates all message flow via tool-based handoffs. Source: [libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md). The **swarm** library offers a peer-to-peer alternative: agents hand off to each other through `createHandoffTool()` and `createSwarm()`, retaining short-term and long-term memory plus human-in-the-loop support from the underlying LangGraph runtime. Source: [libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md). ```mermaid flowchart LR User --> Sup[Supervisor Agent] Sup -- tool handoff --> A1[Specialist A] Sup -- tool handoff --> A2[Specialist B] A1 -. result .-> Sup A2 -. result .-> Sup Sup --> User ``` ### Computer Use Agent (CUA) `@langchain/langgraph-cua` provides a ready-made computer-use agent built on LangGraph. It uses [Scrapybara](https://scrapybara.com/) to drive a virtual machine, OpenAI as the policy model, and ships with a typed `createCua()` factory plus peer-deps on `@langchain/langgraph`, `@langchain/core`, and `@langchain/openai`. Source: [libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) and [libs/langgraph-cua/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/package.json). ### Streaming Example Set The `examples/streaming` workspace enumerates concrete recipes for both in-process and remote execution paths: `basic`, `messages` (including a `model` mode for token-level streaming), `parallel`, `custom-transformer`, `subgraphs`, `human-in-the-loop`, `subagents`, `subagent-status`, and `a2a` (agent-to-agent). Source: [examples/streaming/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/examples/streaming/package.json). ## Project Scaffolding and Visualisation The `create-langgraph` CLI bootstraps new agents from a template registry and ships a `config` subcommand that scans a project for `createAgent()`, `new StateGraph(...).compile()`, and `workflow.compile()` patterns, generating a `langgraph.json` for the LangGraph Platform. Only **exported** agents are included; unexported ones surface as warnings. Source: [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md). Community issue #107 (PNG visualisation parity with the Python port) and issue #1722 (LangGraph Studio failing to show the Chat tab when a graph is defined inside a class) remain open and reflect the trade-off between dynamic graph construction and Studio's static introspection. Source: [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md). ## See Also - [LangGraph Core Concepts & State Management]() - [React / Vue / Angular / Svelte SDK Reference]() - [Checkpointing & Long-Term Memory Store]() - [LangGraph Platform & `langgraph.json` Configuration]() --- --- ## Pitfall Log Project: langchain-ai/langgraphjs Summary: Found 11 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification. ## 1. Identity risk - Identity risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `npm install @langchain/langgraph` - Evidence: identity.distribution | https://www.npmjs.com/package/@langchain/langgraph ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2496 ## 3. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://www.npmjs.com/package/@langchain/langgraph ## 4. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2551 ## 5. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/@langchain/langgraph ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://www.npmjs.com/package/@langchain/langgraph ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2040 ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/1836 ## 10. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph ## 11. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph