# Technical Documentation: langchain-ai/langgraphjs > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/langchain-ai/langgraphjs) ### Overview (`.changeset/README.md`) # Changesets Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets) We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) --- ### Overview (`examples/ai-elements/README.md`) # AI Elements — Tool-Calling Agent Example A self-contained chat interface built with [AI Elements](https://elements.ai-sdk.dev/) components and `@langchain/react`. It demonstrates how to build a production-quality agentic UI using AI Elements' composable component library. ## What it shows - **Tool call rendering** — each tool invocation is displayed with `Tool` + `ToolHeader` + `ToolContent` + `ToolInput` + `ToolOutput`, updating live as the agent streams tool input and then the result. - **Reasoning display** — when the model emits reasoning tokens, a collapsible `Reasoning` block auto-opens during streaming and collapses when done. - **Streaming messages** — `Message` + `MessageContent` + `MessageResponse` renders streaming markdown via Streamdown with full GFM support. - **Loading skeleton** — a `Shimmer` placeholder appears between the user's message and the first assistant token. - **Conversation scroll** — `Conversation` + `ConversationContent` + `ConversationScrollButton` auto-scrolls and shows a jump-to-bottom button when you scroll up. - **Message actions** — `MessageActions` + `MessageAction` with a copy button appears below the last assistant message once streaming completes. - **Prompt input** — `PromptInput` + `PromptInputBody` + `PromptInputTextarea` + `PromptInputFooter` + `PromptInputSubmit` provides a full-featured input bar. - **Suggestions** — `Suggestions` + `Suggestion` shows preset prompts before the first message. ## Agent The backing LangGraph agent (`packages/agents/src/agents/ai-elements.ts`) is a `createReactAgent` with two simulated tools: | Tool | Description | | ------------- | ----------------------------------------------------------- | | `get_weather` | Returns deterministic simulated weather data for any city | | `web_search` | Returns three simulated search result objects for any query | No external API keys are required for the tools. ## Setup Create a `.env` file in this folder (optional — defaults are provided): ```bash VITE_LANGGRAPH_API_URL=http://localhost:2024 # default when running locally VITE_LANGGRAPH_ASSISTANT_ID=ai_elements # matches langgraph.json ``` ## Run Start the LangGraph agent server first: ```bash bun run dev --filter=@langchain/playground-agents ``` Then start this preview app: ```bash bun run dev --filter=@langchain/playground-preview-ai-elements ``` Open [http://localhost:4600](http://localhost:4600). ## AI Elements components used | Component | Source file | | ------------------------------------------------------------------------------------------------- | --------------------------------------------- | | `Conversation`, `ConversationContent`, `ConversationScrollButton` | `src/components/ai-elements/conversation.tsx` | | `Message`, `MessageContent`, `MessageResponse`, `MessageActions`, `MessageAction` | `src/components/ai-elements/message.tsx` | | `PromptInput`, `PromptInputBody`, `PromptInputTextarea`, `PromptInputFooter`, `PromptInputSubmit` | `src/components/ai-elements/prompt-input.tsx` | | `Tool`, `ToolHeader`, `ToolContent`, `ToolInput`, `ToolOutput` | `src/components/ai-elements/tool.tsx` | | `Reasoning`, `ReasoningTrigger`, `ReasoningContent` | `src/components/ai-elements/reasoning.tsx` | | `Suggestions`, `Suggestion` | `src/components/ai-elements/suggestion.tsx` | | `Shimmer` | `src/components/ai-elements/shimmer.tsx` | Components live in `src/components/ai-elements/` and are owned by this package (shadcn/AI Elements registry style — copy-paste, not a node_modules import). ## Vite path alias AI Elements components use bare `src/` imports (e.g. `import { cn } from "src/lib/utils"`). The `vite.config.ts` maps `src` → `./src` to resolve these correctly in both dev and production builds. --- ### Overview (`examples/assistant-ui-claude/README.md`) # Assistant-UI Claude Example This example combines: - `@assistant-ui/react` for the Claude-style chat surface - `@langchain/react` for streaming LangGraph state on the frontend - a basic `langchain` agent on the backend ## What it shows - A Claude-inspired assistant-ui thread and composer - A local single-agent graph powered by `langchain` - How to bridge `@langchain/react` state into assistant-ui with `useExternalStoreRuntime` ## Setup Create a local `.env` file in this folder with: ```bash OPENAI_API_KEY=your_openai_api_key OPENAI_MODEL=gpt-4.1-mini ``` Optional overrides: ```bash LANGGRAPH_API_URL=http://localhost:2024 VITE_LANGGRAPH_API_URL=http://localhost:2024 VITE_LANGGRAPH_ASSISTANT_ID=assistant-ui-claude ``` ## Run ```bash pnpm --filter @examples/assistant-ui-claude dev ``` Then open the Vite URL shown in the terminal, usually [http://localhost:5173](http://localhost:5173). The frontend talks directly to the LangGraph dev server at `http://localhost:2024`, which serves the local `assistant-ui-claude` graph from `langgraph.json`. --- ### Overview (`examples/streaming/README.md`) # In-Process Streaming Examples Runnable examples demonstrating `graph.streamEvents(..., { version: "v3" })` — the ergonomic in-process streaming API for LangGraph. ## Setup ```bash # From the monorepo root pnpm install # Set your API key export ANTHROPIC_API_KEY=sk-... ``` ## Examples Each example is a self-contained script that can be run with `npx tsx`. ### `basic.ts` — Protocol event iteration The simplest starting point. Iterates all `ProtocolEvent` objects from a tool-calling graph and awaits the final output. ```bash npx tsx src/basic.ts ``` Shows: `for await (const event of run)`, `await run.output` ### `messages.ts` — Streaming text tokens Demonstrates the `.messages` projection. Each yielded `ChatModelStream` exposes `.text` as both an `AsyncIterable` (for token-by-token streaming) and a `PromiseLike` (for the full text). Also shows `.usage` for token counts. ```bash npx tsx src/messages.ts ``` Shows: `run.messages`, `message.text`, `message.usage` ### `subgraphs.ts` — Recursive subgraph observation A research pipeline with two sequential subgraphs (researcher → analyst). Shows three ways to observe the subgraph tree: 1. Flat event stream — all events, dispatched by `event.method` 2. Subgraph discovery — `run.subgraphs` yields `SubgraphRunStream` per child 3. Concurrent consumption — messages and subgraphs consumed in parallel ```bash npx tsx src/subgraphs.ts ``` Shows: `run.subgraphs`, `sub.messages`, `sub.name`, `sub.index`, recursive walking ### `custom-reducer.ts` — Domain-specific projections Extends `streamEvents(..., { version: "v3" })` with a custom `StreamTransformer` that counts tool calls and tracks token usage. The transformer is passed via the `transformers` option; its projections appear on `run.extensions`. ```bash npx tsx src/custom-reducer.ts ``` Shows: `StreamTransformer`, `graph.streamEvents(input, { version: "v3", transformers: [...] })`, `run.extensions` ### `parallel.ts` — Concurrent projection consumption All projections on `GraphRunStream` share local stream channels, so multiple `for await` loops can run concurrently without interference. This example streams messages, counts state snapshots, and counts raw protocol events in parallel via `Promise.all`. ```bash npx tsx src/parallel.ts ``` Shows: `Promise.all([run.messages, run.values, run])`, independent cursors ### `human-in-the-loop.ts` — Interrupt, inspect, resume Demonstrates the `streamEvents(..., { version: "v3" })` interrupt/resume lifecycle using a planner → approval → executor graph. Turn 1 runs until `interrupt()` is called; the example inspects `run.interrupted` and `run.interrupts`, then resumes with `Command({ resume })` in turn 2. ```bash npx tsx src/human-in-the-loop.ts ``` Shows: `interrupt()`, `run.interrupted`, `run.interrupts`, `Command({ resume })`, multi-turn `streamEvents(..., { version: "v3" })` ### `a2a.ts` — A2A protocol over a deployed server End-to-end deployment example for custom stream transformers. The research pipeline is compiled with an A2A transformer (`createA2ATransformer`) that emits A2A-formatted status updates and artifacts. The graph is deployed via the LangGraph dev server, and the SDK client subscribes to the `custom` channel to receive only A2A events. ```bash npx tsx src/a2a.ts ``` Shows: `.compile({ transformers: [createA2ATransformer] })`, `streamStateV2()`, SDK `client.runs.stream()`, `streamMode: ["custom"]` ## Agents The example agents live in `src/agents/` and `src/a2a/`: | Agent | File | Description | |-------|------|-------------| | Simple tool graph | `agents/simple-tool-graph.ts` | Single ReAct loop with search + calculator | | Research pipeline | `agents/research-pipeline.ts` | Two sequential subgraphs with separate tools | | Approval graph | `agents/approval-graph.ts` | Planner → human approval → executor with interrupt/resume | | A2A research | `a2a/agent.ts` | Research pipeline with A2A stream transformer at compile time | ## API Surface All examples use the `GraphRunStream` returned by `graph.streamEvents(..., { version: "v3" })`: ```typescript const run = await graph.streamEvents(input, { ...options, version: "v3" }); // Iterate all protocol events for await (const event of run) { ... } // Stream AI messages with text/reasoning/usage projections for await (const msg of run.messages) { for await (const token of msg.text) { process.stdout.write(token); } const fullText = await msg.text; const usage = await msg.usage; } // Observe subgraphs recursively for await (const sub of run.subgraphs) { console.log(sub.name, sub.path); for await (const msg of sub.messages) { ... } } // Final output const state = await run.output; // State snapshots per step for await (const snapshot of run.values) { ... } // Messages from a specific node for await (const msg of run.messagesFrom("agent")) { ... } // Custom transformers const run = await graph.streamEvents(input, { version: "v3", transformers: [myTransformer], }); const custom = await run.extensions.myProjection; // Human-in-the-loop const run1 = await graph.streamEvents(input, { ...config, version: "v3" }); for await (const msg of run1.messages) { ... } await run1.output; if (run1.interrupted) { console.log(run1.interrupts); const run2 = await graph.streamEvents( new Command({ resume: userDecision }), { ...config, version: "v3" } ); } ``` ## Coming Soon Additional examples will be added for: - `createAgent` — `AgentRunStream` with typed `run.toolCalls` - `createDeepAgent` — `DeepAgentRunStream` with `run.subagents` - Cancellation — `run.abort()`, `AbortSignal` passthrough --- ### Overview (`examples/ui-multimodal/README.md`) # React + TypeScript + Vite This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available: - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) ## React Compiler The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information. Note: This will impact Vite dev & build performances. ## Expanding the ESLint configuration If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: ```js export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ // Other configs... // Remove tseslint.configs.recommended and replace with this tseslint.configs.recommendedTypeChecked, // Alternatively, use this for stricter rules tseslint.configs.strictTypeChecked, // Optionally, add this for stylistic rules tseslint.configs.stylisticTypeChecked, // Other configs... ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ]) ``` You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: ```js // eslint.config.js import reactX from 'eslint-plugin-react-x' import reactDom from 'eslint-plugin-react-dom' export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ // Other configs... // Enable lint rules for React reactX.configs['recommended-typescript'], // Enable lint rules for React DOM reactDom.configs.recommended, ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ]) ``` --- ### Overview (`examples/ui-react/README.md`) # React + TypeScript + Vite This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available: - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) ## React Compiler The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information. Note: This will impact Vite dev & build performances. ## Expanding the ESLint configuration If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: ```js export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ // Other configs... // Remove tseslint.configs.recommended and replace with this tseslint.configs.recommendedTypeChecked, // Alternatively, use this for stricter rules tseslint.configs.strictTypeChecked, // Optionally, add this for stylistic rules tseslint.configs.stylisticTypeChecked, // Other configs... ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ]) ``` You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: ```js // eslint.config.js import reactX from 'eslint-plugin-react-x' import reactDom from 'eslint-plugin-react-dom' export default defineConfig([ globalIgnores(['dist']), { files: ['**/*.{ts,tsx}'], extends: [ // Other configs... // Enable lint rules for React reactX.configs['recommended-typescript'], // Enable lint rules for React DOM reactDom.configs.recommended, ], languageOptions: { parserOptions: { project: ['./tsconfig.node.json', './tsconfig.app.json'], tsconfigRootDir: import.meta.dirname, }, // other options... }, }, ]) ``` --- ### Overview (`internal/bench/README.md`) # LangGraph Benchmarks This package contains benchmarks for the LangGraph.js. ## Running the tests ```bash yarn test ``` --- ### Overview (`libs/checkpoint-mongodb/README.md`) # @langchain/langgraph-checkpoint-mongodb Implementation of a [LangGraph.js](https://github.com/langchain-ai/langgraphjs) CheckpointSaver that uses a MongoDB instance. ## Usage ```ts import { MongoClient } from "mongodb"; import { MongoDBSaver } from "@langchain/langgraph-checkpoint-mongodb"; const writeConfig = { configurable: { thread_id: "1", checkpoint_ns: "" } }; const readConfig = { configurable: { thread_id: "1" } }; const client = new MongoClient(process.env.MONGODB_URL); const checkpointer = new MongoDBSaver({ client }); // NOTE: you need to call .setup() the first time you're using your checkpointer await checkpointer.setup(); const checkpoint = { v: 1, ts: "2024-07-31T20:14:19.804150+00:00", id: "1ef4f797-8335-6428-8001-8a1503f9b875", channel_values: { my_key: "meow", node: "node" }, channel_versions: { __start__: 2, my_key: 3, "start:node": 3, node: 3 }, versions_seen: { __input__: {}, __start__: { __start__: 1 }, node: { "start:node": 2 } }, pending_sends: [], } // store checkpoint await checkpointer.put(writeConfig, checkpoint, {}, {}); // load checkpoint await checkpointer.get(readConfig); // list checkpoints for await (const checkpoint of checkpointer.list(readConfig)) { console.log(checkpoint); } await client.close(); ``` ## TTL (Time-To-Live) Support Automatically expire old checkpoints using MongoDB's TTL indexes: ```ts import { MongoClient } from "mongodb"; import { MongoDBSaver } from "@langchain/langgraph-checkpoint-mongodb"; const client = new MongoClient(process.env.MONGODB_URL); // Create checkpointer with 1-hour TTL (in seconds) const checkpointer = new MongoDBSaver({ client, ttl: 3600, }); // Create TTL indexes (call during deployment/startup) await checkpointer.setup(); ``` When TTL is enabled: - An `upserted_at` timestamp is added to each document on every write - MongoDB automatically deletes documents after the TTL expires - Each update resets the expiration timer The `setup()` method creates the required TTL indexes. Call it during application startup or deployment. It is idempotent and handles concurrent calls safely. --- ### Overview (`libs/checkpoint-postgres/README.md`) # @langchain/langgraph-checkpoint-postgres Implementation of a [LangGraph.js](https://github.com/langchain-ai/langgraphjs) CheckpointSaver that uses a Postgres DB. ## Usage ```ts import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres"; const writeConfig = { configurable: { thread_id: "1", checkpoint_ns: "" } }; const readConfig = { configurable: { thread_id: "1" } }; // you can optionally pass a configuration object as the second parameter const checkpointer = PostgresSaver.fromConnString("postgresql://...", { schema: "schema_name" // defaults to "public" }); // You must call .setup() the first time you use the checkpointer: await checkpointer.setup(); const checkpoint = { v: 1, ts: "2024-07-31T20:14:19.804150+00:00", id: "1ef4f797-8335-6428-8001-8a1503f9b875", channel_values: { my_key: "meow", node: "node" }, channel_versions: { __start__: 2, my_key: 3, "start:node": 3, node: 3 }, versions_seen: { __input__: {}, __start__: { __start__: 1 }, node: { "start:node": 2 } }, pending_sends: [], } // store checkpoint await checkpointer.put(writeConfig, checkpoint, {}, {}); // load checkpoint await checkpointer.get(readConfig); // list checkpoints for await (const checkpoint of checkpointer.list(readConfig)) { console.log(checkpoint); } ``` ## Usage with existing connection pool ```ts import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres"; import pg from "pg"; // You can use any existing postgres connection pool // we create a new pool here for the sake of the example const pool = new pg.Pool({ connectionString: "postgresql://..." }); const checkpointer = new PostgresSaver(pool, undefined, { schema: "schema_name" }); await checkpointer.setup(); // ... ``` ## Edge & serverless runtimes (Cloudflare Workers, etc.) `PostgresSaver` uses [node-postgres (`pg`)](https://node-postgres.com/) under the hood, which opens a raw TCP/TLS connection via Node's `net`/`tls` modules. Some serverless/edge runtimes, most notably **Cloudflare Workers**, do not support raw outbound TCP connections from arbitrary code, so a direct connection (including the initial `await checkpointer.setup()`) will hang. This is the root cause for issues where the runtime reports that the Worker "had hung and would never generate a response". This is a database-driver/runtime limitation, **not** a persistence-flush problem. LangGraph awaits all pending checkpoint writes before `invoke()`/`stream()` resolves (see the [base checkpoint package README](../checkpoint/README.md#when-are-checkpoints-persisted)), so as long as you `await` the run you do not need `ctx.waitUntil()` to keep the runtime alive for persistence. To use Postgres checkpointing from Cloudflare Workers, route the connection through [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/), which exposes a `pg`-compatible connection string: ```ts // wrangler.toml / wrangler.jsonc must enable `nodejs_compat` and bind a Hyperdrive instance: // compatibility_flags = ["nodejs_compat"] // [[hyperdrive]] // binding = "HYPERDRIVE" // id = "" import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres"; export default { async fetch(request: Request, env: Env): Promise { const checkpointer = PostgresSaver.fromConnString( env.HYPERDRIVE.connectionString ); // ... compile and `await graph.invoke(...)` here ... // Persistence is complete once `invoke`/`stream` resolves. return new Response("ok"); }, }; ``` Alternatively, implement a thin `BaseCheckpointSaver` on top of an HTTP/WebSocket Postgres driver such as [`@neondatabase/serverless`](https://github.com/neondatabase/serverless) that is designed for edge runtimes. > Note: standard Node.js, Deno, and Bun deployments are unaffected — `PostgresSaver` works there out of the box. ## Testing Spin up testing PostgreSQL ```bash docker-compose up -d && docker-compose logs -f ``` Then use the following connection string to initialize your checkpointer: ```ts const testCheckpointer = PostgresSaver.fromConnString( "postgresql://user:password@localhost:5434/testdb" ); ``` --- ### Overview (`libs/checkpoint-redis/README.md`) # @langchain/langgraph-checkpoint-redis Redis checkpoint and store implementation for LangGraph. ## Overview This package provides Redis-based implementations for: 1. **Checkpoint Savers**: Store and manage LangGraph checkpoints using Redis - **RedisSaver**: Standard checkpoint saver that maintains full checkpoint history - **ShallowRedisSaver**: Memory-optimized saver that only keeps the latest checkpoint per thread 2. **RedisStore**: Redis-backed key-value store with optional vector search capabilities ## Installation ```bash npm install @langchain/langgraph-checkpoint-redis ``` ## Dependencies ### Redis Requirements This library requires Redis with the following modules: - **RedisJSON** - For storing and manipulating JSON data - **RediSearch** - For search and indexing capabilities #### Redis 8.0+ If you're using Redis 8.0 or higher, both RedisJSON and RediSearch modules are included by default. #### Redis < 8.0 For Redis versions lower than 8.0, you'll need to: - Use [Redis Stack](https://redis.io/docs/stack/), which bundles Redis with these modules - Or install the modules separately in your Redis instance ## Usage ### Standard Checkpoint Saver ```typescript import { RedisSaver } from "@langchain/langgraph-checkpoint-redis"; const checkpointer = await RedisSaver.fromUrl( "redis://localhost:6379", { defaultTTL: 60, // TTL in minutes refreshOnRead: true } ); // Indices are automatically created by fromUrl() // Use with your graph const config = {configurable: {thread_id: "1"}}; // Metadata must include required fields const metadata = { source: "update", // "update" | "input" | "loop" | "fork" step: 0, parents: {} }; await checkpointer.put(config, checkpoint, metadata, {}); const loaded = await checkpointer.get(config); ``` ### Shallow Checkpoint Saver The `ShallowRedisSaver` is a memory-optimized variant that only keeps the latest checkpoint per thread: ```typescript import { ShallowRedisSaver } from "@langchain/langgraph-checkpoint-redis/shallow"; // Create a shallow saver that only keeps the latest checkpoint const shallowSaver = await ShallowRedisSaver.fromUrl("redis://localhost:6379"); // Use it the same way as RedisSaver const config = { configurable: { thread_id: "my-thread", checkpoint_ns: "my-namespace" } }; const metadata = { source: "update", step: 0, parents: {} }; await shallowSaver.put(config, checkpoint, metadata, versions); // Only the latest checkpoint is kept - older ones are automatically cleaned up const latest = await shallowSaver.getTuple(config); ``` Key differences from RedisSaver: - **Storage**: Only keeps the latest checkpoint per thread (no history) - **Performance**: Reduced storage usage and faster operations - **Inline storage**: Channel values are stored inline (no separate blob storage) - **Automatic cleanup**: Old checkpoints and writes are automatically removed ### RedisStore The `RedisStore` provides a key-value store with optional vector search capabilities: ```typescript import { RedisStore } from "@langchain/langgraph-checkpoint-redis/store"; // Basic key-value store const store = await RedisStore.fromConnString("redis://localhost:6379"); // Store with vector search const vectorStore = await RedisStore.fromConnString("redis://localhost:6379", { index: { dims: 1536, // Embedding dimensions embed: embeddings, // Your embeddings instance distanceType: "cosine", // or "l2", "ip" fields: ["text"], // Fields to embed }, ttl: { defaultTTL: 60, // TTL in minutes refreshOnRead: true, } }); // Put and get items await store.put(["namespace", "nested"], "key1", {text: "Hello world"}); const item = await store.get(["namespace", "nested"], "key1"); // Search with namespace filtering const results = await store.search(["namespace"], { filter: {category: "docs"}, limit: 10, }); // Vector search const semanticResults = await vectorStore.search(["namespace"], { query: "semantic search query", filter: {type: "article"}, limit: 5, }); // Batch operations const ops = [ {type: "get", namespace: ["ns"], key: "key1"}, {type: "put", namespace: ["ns"], key: "key2", value: {data: "value"}}, {type: "search", namespacePrefix: ["ns"], limit: 10}, {type: "list_namespaces", matchConditions: [{matchType: "prefix", path: ["ns"]}], limit: 10}, ]; const results = await store.batch(ops); ``` ## TTL Support Both checkpoint savers and stores support Time-To-Live (TTL) functionality: ```typescript const ttlConfig = { defaultTTL: 60, // Default TTL in minutes refreshOnRead: true, // Refresh TTL when items are read }; const checkpointer = await RedisSaver.fromUrl("redis://localhost:6379", ttlConfig); ``` ## Edge & serverless runtimes (Cloudflare Workers, etc.) The Redis savers and store use [node-redis](https://github.com/redis/node-redis) (`createClient`/`createCluster`), which opens a raw TCP/TLS socket via Node's `net`/`tls` modules. Some serverless/edge runtimes, most notably **Cloudflare Workers**, do not support raw outbound TCP connections, so connecting (and the initial index setup) will hang. This is the root cause for issues where the runtime reports that the Worker "had hung and would never generate a response". This is a client/runtime limitation, **not** a persistence-flush problem. LangGraph awaits all pending checkpoint writes before `invoke()`/`stream()` resolves (see the [base checkpoint package README](../checkpoint/README.md#when-are-checkpoints-persisted)), so as long as you `await` the run you do not need `ctx.waitUntil()` to keep the runtime alive for persistence. Cloudflare Hyperdrive only supports Postgres/MySQL, so it cannot front Redis. To use Redis-backed persistence from Cloudflare Workers, use an HTTP-based Redis service such as [Upstash Redis](https://upstash.com/docs/redis/sdks/ts/overview) (`@upstash/redis`, which speaks REST and works in Workers) behind a small custom `BaseCheckpointSaver` implementation, rather than `RedisSaver`/`ShallowRedisSaver`. > Note: standard Node.js, Deno, and Bun deployments are unaffected — the Redis savers work there out of the box. ## Development ### Running Tests ```bash # Run tests (uses TestContainers) yarn test # Run tests in watch mode yarn test:watch # Run integration tests yarn test:int ``` ## License MIT --- ### Overview (`libs/checkpoint-sqlite/README.md`) # @langchain/langgraph-checkpoint-sqlite Implementation of a [LangGraph.js](https://github.com/langchain-ai/langgraphjs) CheckpointSaver that uses a SQLite DB. ## Usage ```ts import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite"; const writeConfig = { configurable: { thread_id: "1", checkpoint_ns: "" } }; const readConfig = { configurable: { thread_id: "1" } }; const checkpointer = SqliteSaver.fromConnString(":memory:"); const checkpoint = { v: 1, ts: "2024-07-31T20:14:19.804150+00:00", id: "1ef4f797-8335-6428-8001-8a1503f9b875", channel_values: { my_key: "meow", node: "node" }, channel_versions: { __start__: 2, my_key: 3, "start:node": 3, node: 3 }, versions_seen: { __input__: {}, __start__: { __start__: 1 }, node: { "start:node": 2 } }, pending_sends: [], } // store checkpoint await checkpointer.put(writeConfig, checkpoint, {}, {}) // load checkpoint await checkpointer.get(readConfig) // list checkpoints for await (const checkpoint of checkpointer.list(readConfig)) { console.log(checkpoint); } ``` --- ### Overview (`libs/checkpoint-validation/README.md`) # @langchain/langgraph-checkpoint-validation The checkpointer validation tool is used to validate that custom checkpointer implementations conform to LangGraph's requirements. LangGraph uses [checkpointers](https://langchain-ai.github.io/langgraphjs/concepts/persistence/#checkpointer-libraries) for persisting workflow state, providing the ability to "rewind" your workflow to some earlier point in time, and continue execution from there. The tool requires Node.js 20, 22, or 24 and later. The overall process for using this tool is as follows: 1. Write your custom checkpointer implementation. 2. Add a file to your project that defines a [`CheckpointerTestInitializer`](./src/types.ts) as its default export. 3. Run the checkpointer validation tool to test your checkpointer and determine whether it meets LangGraph's requirements. 4. Iterate on your custom checkpointer as required, until tests pass. The tool can be executed from the terminal as a CLI, or you can use it as a library to integrate it into your test suite. ## Writing a CheckpointerTestInitializer The `CheckpointerTestInitializer` interface ([example](./src/tests/postgres_initializer.ts)) is used by the test harness to create instances of your custom checkpointer, and any infrastructure that it requires for testing purposes. If you intend to execute the tool via the CLI, your `CheckpointerTestInitializer` **must** be the default export of the module in which it is defined. **Synchronous vs Asynchronous initializer functions**: You may return promises from any functions defined in your `CheckpointerTestInitializer` according to your needs and the test harness will behave accordingly. **IMPORTANT**: You must take care to write your `CheckpointerTestInitializer` such that instances of your custom checkpointer are isolated from one another with respect to persisted state, or else some tests (particularly the ones that exercise the `list` method) will fail. That is, state written by one instance of your checkpointer MUST NOT be readable by another instance of your checkpointer. That said, there will only ever be one instance of your checkpointer live at any given time, so **you may use shared storage, provided it is cleared when your checkpointer is created or destroyed.** The structure of the `CheckpointerTestInitializer` interface should make this relatively easy to achieve, per the sections below. ### (Required) `checkpointerName`: Define a name for your checkpointer `CheckpointerTestInitializer` requires you to define a `checkpointerName` field (of type `string`) for use in the test output. ### `beforeAll`: Set up required infrastructure If your checkpointer requires some external infrastructure to be provisioned, you may wish to provision this via the **optional** `beforeAll` function. This function executes exactly once, at the very start of the testing lifecycle. If defined, it is the first function that will be called from your `CheckpointerTestInitializer`. **Timeout duration**: If your `beforeAll` function may take longer than 10 seconds to execute, you can assign a custom timeout duration (as milliseconds) to the optional `beforeAllTimeout` field of your `CheckpointerTestInitializer`. **State isolation note**: Depending on the cost/performance/requirements of your checkpointer infrastructure, it **may** make more sense for you to provision it during the `createCheckpointer` step, so you can provide each checkpointer instance with its own isolated storage backend. However as mentioned above, you may also provision a single shared storage backend, provided you clear any stored data during the `createCheckpointer` or `destroyCheckpointer` step. ### `afterAll`: Tear down required infrastructure If you set up infrastructure during the `beforeAll` step, you may need to tear it down once the tests complete their execution. You can define this teardown logic in the optional `afterAll` function. Much like `beforeAll` this function will execute exactly one time, after all tests have finished executing. **IMPORTANT**: If you kill the test runner early this function may not be called. To avoid manual clean-up, give preference to test infrastructure management tools like [TestContainers](https://testcontainers.com/guides/getting-started-with-testcontainers-for-nodejs/), as these tools are designed to detect when this happens and clean up after themselves once the controlling process dies. ### (Required) `createCheckpointer`: Construct your checkpointer `CheckpointerTestInitializer` requires you to define a `createCheckpointer()` function that returns an instance of your custom checkpointer. **State isolation note:** If you're provisioning storage during this step, make sure that it is "fresh" storage for each instance of your checkpointer. Otherwise if you are using a shared storage setup, be sure to clear it either in this function, or in the `destroyCheckpointer` function (described in the section below). ### `destroyCheckpointer`: Destroy your checkpointer If your custom checkpointer requires an explicit teardown step (for example, to clean up database connections), you can define this in the **optional** `destroyCheckpointer(checkpointer: CheckpointerT)` function. **State isolation note:** If you are using a shared storage setup, be sure to clear it either in this function, or in the `createCheckpointer` function (described in the section above). ## CLI usage You may use this tool's CLI either via `npx`, `yarn dlx`, or by installing globally and executing it via the `validate-checkpointer` command. The only required argument to the tool is the import path for your `CheckpointerTestInitializer`. Relative paths must begin with a leading `./` (or `.\`, for Windows), otherwise the path will be interpreted as a module name rather than a relative path. You may optionally pass one or more test filters as positional arguments after the import path argument (separated by spaces). Valid values are `getTuple`, `list`, `put`, and `putWrites`. If present, only the test suites specified in the filter list will be executed. This is useful for working through smaller sets of test failures as you're validating your checkpointer. TypeScript imports **are** supported, so you may pass a path directly to your TypeScript source file. ### NPX & Yarn execution NPX: ```bash npx @langchain/langgraph-checkpoint-validation ./src/my_initializer.ts ``` Yarn: ```bash yarn dlx @langchain/langgraph-checkpoint-validation ./src/my_initializer.ts ``` ### Global install NPM: ```bash npm install @langchain/langgraph-checkpoint-validation validate-checkpointer ./src/my_initializer.ts ``` ## Usage in existing Jest-like test suite This package exports a test definition function that may be used in any Jest-compatible test framework (including Vitest). If you wish to integrate this tooling into your existing test suite, you can simply import and invoke it from within a test file, as shown below. ```ts import { validate } from "@langchain/langgraph-validation"; validate(MyCheckpointerInitializer); ``` --- ### Overview (`libs/checkpoint/README.md`) # @langchain/langgraph-checkpoint This library defines the base interface for [LangGraph.js](https://github.com/langchain-ai/langgraphjs) checkpointers. Checkpointers provide persistence layer for LangGraph. They allow you to interact with and manage the graph's state. When you use a graph with a checkpointer, the checkpointer saves a _checkpoint_ of the graph state at every superstep, enabling several powerful capabilities like human-in-the-loop, "memory" between interactions and more. ## Key concepts ### Checkpoint Checkpoint is a snapshot of the graph state at a given point in time. Checkpoint tuple refers to an object containing checkpoint and the associated config, metadata and pending writes. ### Thread Threads enable the checkpointing of multiple different runs, making them essential for multi-tenant chat applications and other scenarios where maintaining separate states is necessary. A thread is a unique ID assigned to a series of checkpoints saved by a checkpointer. When using a checkpointer, you must specify a `thread_id` and optionally `checkpoint_id` when running the graph. - `thread_id` is simply the ID of a thread. This is always required - `checkpoint_id` can optionally be passed. This identifier refers to a specific checkpoint within a thread. This can be used to kick of a run of a graph from some point halfway through a thread. You must pass these when invoking the graph as part of the configurable part of the config, e.g. ```ts { configurable: { thread_id: "1" } } // valid config { configurable: { thread_id: "1", checkpoint_id: "0c62ca34-ac19-445d-bbb0-5b4984975b2a" } } // also valid config ``` ### Serde `@langchain/langgraph-checkpoint` also defines protocol for serialization/deserialization (serde) and provides an default implementation that handles a range of types. ### Pending writes When a graph node fails mid-execution at a given superstep, LangGraph stores pending checkpoint writes from any other nodes that completed successfully at that superstep, so that whenever we resume graph execution from that superstep we don't re-run the successful nodes. ### When are checkpoints persisted By default (`durability: "async"`) checkpoint writes are dispatched in the background while the graph keeps executing, which keeps runs fast. Regardless of the `durability` mode, LangGraph **awaits all outstanding checkpointer writes before `invoke()` / `stream()` resolves**, `invoke()` fully drains the underlying stream, and the stream awaits every pending checkpointer promise before it completes. In practice this means: - If you `await graph.invoke(...)` (or fully consume `for await (... of graph.stream(...))`), persistence is guaranteed to be complete by the time the call returns. You do **not** need to keep the process/runtime alive for any trailing background writes. - On serverless/edge runtimes (e.g. Cloudflare Workers) you therefore do not need `ctx.waitUntil()` to flush checkpoints, just make sure you `await` the run before returning a response. The only way to orphan writes is to start a stream and never consume it (e.g. piping `graph.stream()` into a detached, un-awaited task). > Note: this guarantees the *write was issued and awaited*, not that your database driver works in a given runtime. See the runtime-compatibility notes in the [Postgres](../checkpoint-postgres/README.md#edge--serverless-runtimes-cloudflare-workers-etc) and [Redis](../checkpoint-redis/README.md#edge--serverless-runtimes-cloudflare-workers-etc) checkpointer READMEs. ## Interface Each checkpointer should conform to `BaseCheckpointSaver` interface and must implement the following methods: - `.put` - Store a checkpoint with its configuration and metadata. - `.putWrites` - Store intermediate writes linked to a checkpoint (i.e. pending writes). - `.getTuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `thread_ts`). - `.list` - List checkpoints that match a given configuration and filter criteria. ## Usage ```ts import { MemorySaver } from "@langchain/langgraph-checkpoint"; const writeConfig = { configurable: { thread_id: "1", checkpoint_ns: "" } }; const readConfig = { configurable: { thread_id: "1" } }; const checkpointer = new MemorySaver(); const checkpoint = { v: 1, ts: "2024-07-31T20:14:19.804150+00:00", id: "1ef4f797-8335-6428-8001-8a1503f9b875", channel_values: { my_key: "meow", node: "node" }, channel_versions: { __start__: 2, my_key: 3, "start:node": 3, node: 3 }, versions_seen: { __input__: {}, __start__: { __start__: 1 }, node: { "start:node": 2 } }, pending_sends: [], } // store checkpoint await checkpointer.put(writeConfig, checkpoint, {}, {}) // load checkpoint await checkpointer.get(readConfig) // list checkpoints for await (const checkpoint of checkpointer.list(readConfig)) { console.log(checkpoint); } ``` --- ### Overview (`libs/create-langgraph/README.md`) # create-langgraph [](https://www.npmjs.com/package/create-langgraph) [](https://opensource.org/licenses/MIT) The official scaffolding tool for [LangGraph.js](https://langchain-ai.github.io/langgraphjs/) projects. Quickly bootstrap new LangGraph applications from curated templates or generate configuration files for existing projects. ## Quick Start Create a new LangGraph project with a single command: ```bash # Using npm npm init langgraph@latest # Using yarn yarn create langgraph # Using pnpm pnpm create langgraph # Using pnpm pnpm create langgraph # Using bun bunx create-langgraph ``` Follow the interactive prompts to select a template and configure your project. ## Templates Choose from a variety of production-ready templates: | Template | Description | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | [**New LangGraph Project**](https://github.com/langchain-ai/new-langgraphjs-project) | A simple, minimal chatbot with memory | | [**ReAct Agent**](https://github.com/langchain-ai/react-agent-js) | A flexible agent that can be extended with many tools | | [**Memory Agent**](https://github.com/langchain-ai/memory-agent-js) | A ReAct-style agent with persistent memory across conversations | | [**Retrieval Agent**](https://github.com/langchain-ai/retrieval-agent-template-js) | An agent with retrieval-based question-answering | | [**Data-enrichment Agent**](https://github.com/langchain-ai/data-enrichment-js) | An agent that performs web searches and organizes findings | ### Using a Specific Template Skip the interactive prompt by specifying a template directly: ```bash npx create-langgraph@latest my-project --template react-agent-js ``` Available template IDs: - `new-langgraph-project-js` - `react-agent-js` - `memory-agent-js` - `retrieval-agent-js` - `data-enrichment-js` ## Commands ### `create-langgraph [path]` Creates a new LangGraph project at the specified path. ```bash npx create-langgraph@latest my-awesome-agent ``` **Options:** - `-t, --template