+:::python
+
:::
+
+:::js
+- Start with `generateQueryOrRespond` and determine whether to call the retriever tool.
+- Route to the next step using a conditional edge:
+ - If `generateQueryOrRespond` returned `tool_calls`, call the retriever tool to retrieve context.
+ - Otherwise, respond directly to the user.
+- Grade retrieved document content for relevance to the question (`gradeDocuments`) and route to the next step:
+ - If not relevant, rewrite the question using `rewrite` and then call `generateQueryOrRespond` again.
+ - If relevant, proceed to `generate` and generate the final response using the @[ToolMessage] with the retrieved document context.
+
+
+
+
+The event router is the bridge between the two layers. It receives normalized Pregel events and passes each event through the registered stream transformers. Built-in transformers create standard projections such as `stream.messages`, `stream.values`, `stream.subgraphs`, and `stream.output`. Custom transformers can add application-specific projections under `stream.extensions`.
+
+## What event streaming provides
+
+The run stream exposes typed projections over one underlying event flow:
+
+| Projection | Use |
+| ---------- | --- |
+| `stream` | Iterate every protocol event. |
+| `stream.messages` | Stream chat model messages and token deltas. |
+| `stream.values` | Iterate state snapshots and await the final value. |
+| `stream.output` | Await the final output. |
+| `stream.subgraphs` | Discover and observe nested graph executions. |
+| `stream.interrupts` | Inspect human-in-the-loop interrupt payloads. |
+| `stream.interrupted` | Check whether the run paused for human input. |
+| `stream.extensions` | Consume custom stream transformer projections. |
+
+Multiple consumers can read these projections concurrently. Reading `stream.messages` does not consume events needed by `stream.values`, `stream.subgraphs`, or `stream.output`.
+
+Event streaming sits one level above [streaming](/oss/langgraph/streaming), which exposes raw graph execution events through `stream_mode` modes such as `updates`, `values`, `messages`, `custom`, `checkpoints`, `tasks`, and `debug`. Use streaming when you need low-level access to those modes; use event streaming when application code benefits from typed projections.
+
+## Stream messages
+
+Use `stream.messages` for chat model output:
+
+:::python
+```py
+stream = graph.stream_events(input, version="v3")
+
+for message in stream.messages:
+ text = str(message.text)
+ usage = message.output.usage_metadata
+
+ print(text)
+ print(usage)
+```
+:::
+
+:::js
+```ts
+const stream = await graph.streamEvents(input, { version: "v3" });
+
+for await (const message of stream.messages) {
+ const text = await message.text;
+ const usage = await message.usage;
+
+ console.log(text);
+ console.log(usage);
+}
+```
+:::
+
+:::python
+`message.text` is iterable in synchronous code. Iterate it for token-by-token output, or call `str(message.text)` for the complete text.
+
+`message.reasoning` exposes reasoning deltas, and `message.tool_calls` exposes tool-call argument chunks. If you need text, reasoning, and tool-call chunks in exact arrival order, iterate the message stream's raw events instead of each projection separately.
+:::
+
+:::js
+`message.text` is both an async iterable and a promise-like value. Iterate it for token-by-token output, or await it for the complete text.
+:::
+
+## Stream subgraphs
+
+Use `stream.subgraphs` to observe nested graph work without parsing namespace strings:
+
+:::python
+```py
+stream = graph.stream_events(input, version="v3")
+
+for subgraph in stream.subgraphs:
+ print(subgraph.graph_name, subgraph.path)
+
+ for message in subgraph.messages:
+ print(message.text)
+```
+:::
+
+:::js
+```ts
+const stream = await graph.streamEvents(input, { version: "v3" });
+
+for await (const subgraph of stream.subgraphs) {
+ console.log(subgraph.name, subgraph.path);
+
+ for await (const message of subgraph.messages) {
+ console.log(await message.text);
+ }
+}
+```
+:::
+
+`subgraph.graph_name` is the `name` of the compiled graph or agent. A named agent dispatched from a tool (for example, a `create_agent(name=...)` invoked through the Deep Agents `task` tool) surfaces here under that name, and the `lifecycle` event that opens the scope carries a `cause` linking back to the dispatching tool call. See [Lifecycle](#lifecycle) for more information.
+
+For product-specific streams, see [Deep Agents streaming](/oss/deepagents/event-streaming) for subagent streams and [LangChain agent streaming](/oss/langchain/streaming) for tool calls and middleware events.
+
+## Stream state
+
+Use `stream.values` to stream full state snapshots after each step:
+
+:::python
+```py
+stream = graph.stream_events(input, version="v3")
+
+for snapshot in stream.values:
+ print(snapshot)
+
+final_state = stream.output
+```
+:::
+
+:::js
+```ts
+const stream = await graph.streamEvents(input, { version: "v3" });
+
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
+}
+
+const finalState = await stream.output;
+```
+:::
+
+## Stream multiple projections
+
+:::python
+For concurrent consumption in async code, use `astream_events` with `asyncio.gather`:
+
+```py
+import asyncio
+
+stream = await graph.astream_events(input, version="v3")
+
+async def consume_messages():
+ async for message in stream.messages:
+ print(f"[llm] node={message.node}")
+
+async def consume_subgraphs():
+ async for subgraph in stream.subgraphs:
+ print(f"[subgraph] path={subgraph.path}")
+
+await asyncio.gather(consume_messages(), consume_subgraphs())
+```
+
+For synchronous code, use `stream.interleave(...)` to consume multiple projections in strict arrival order:
+
+```py
+stream = graph.stream_events(input, version="v3")
+
+for name, item in stream.interleave("values", "messages", "subgraphs"):
+ if name == "values":
+ print(f"[state] keys={list(item)}")
+ elif name == "messages":
+ print(f"[llm] node={item.node}")
+ elif name == "subgraphs":
+ print(f"[subgraph] path={item.path}")
+```
+:::
+
+:::js
+Use concurrent consumers when you need multiple projections in JavaScript:
+
+```ts
+await Promise.all([
+ (async () => {
+ for await (const message of stream.messages) {
+ console.log(await message.text);
+ }
+ })(),
+ (async () => {
+ for await (const subgraph of stream.subgraphs) {
+ console.log(subgraph.path);
+ }
+ })(),
+]);
+```
+:::
+
+## Resume after an interrupt
+
+When a graph pauses for human input, inspect `stream.interrupted` and `stream.interrupts`, then resume by calling `stream_events(..., version="v3")` again with `Command`.
+
+Resume requires a graph compiled with a checkpointer and a config carrying a thread ID — see [persistence](/oss/langgraph/persistence).
+
+:::python
+```py
+from langgraph.types import Command
+
+stream = graph.stream_events(input, version="v3")
+
+for message in stream.messages:
+ print(message.text)
+
+if stream.interrupted:
+ print(stream.interrupts)
+
+stream = graph.stream_events(
+ Command(resume={"decisions": [{"type": "approve"}]}),
+ version="v3",
+)
+final_state = stream.output
+```
+:::
+
+:::js
+```ts
+import { Command } from "@langchain/langgraph";
+
+let stream = await graph.streamEvents(input, { version: "v3" });
+
+for await (const message of stream.messages) {
+ console.log(await message.text);
+}
+
+if (stream.interrupted) {
+ console.log(stream.interrupts);
+}
+
+stream = await graph.streamEvents(
+ new Command({ resume: { decisions: [{ type: "approve" }] } }),
+ { version: "v3" }
+);
+const finalState = await stream.output;
+```
+:::
+
+## Stream all protocol events
+
+Use the run object itself when you want the raw protocol event stream:
+
+:::python
+```py
+stream = graph.stream_events({
+ "messages": [{"role": "user", "content": "What is 42 * 17?"}],
+}, version="v3")
+
+for event in stream:
+ namespace = event["params"]["namespace"]
+ print(namespace, event["method"], event["params"]["data"])
+```
+:::
+
+:::js
+```ts
+const stream = await graph.streamEvents(
+ { messages: [{ role: "user", content: "What is 42 * 17?" }] },
+ { version: "v3" }
+);
+
+for await (const event of stream) {
+ const namespace = event.params.namespace;
+ console.log(namespace, event.method, event.params.data);
+}
+```
+:::
+
+Each event is a `ProtocolEvent` envelope wrapping a channel-specific payload. The same shape is what a transformer's `process(event)` receives.
+
+:::python
+```py
+class ProtocolEvent(TypedDict):
+ seq: int # strictly increasing within a run; use for ordering
+ method: str # channel name: "messages", "values", "updates", "custom", "tools", "lifecycle", ...
+ params: ProtocolEventParams
+
+
+class ProtocolEventParams(TypedDict):
+ namespace: list[str] # path of "
+
+
+
+ Pregel engine
+ Runs graph steps
+ emits
+
+
+
+ Raw Pregel events
+ updates, values, messages, custom, checkpoints, tasks, debugsent to
+
+
+ Event router
+ Routes each event through the transformer pipeline
+ cascades through
+
+
+ Stream transformers
+
+
+ ValuesTransformer
+ MessagesTransformer
+ ...
+ Custom transformers
+ produces
+
+
+ Event Stream
+ Projected events for application code
+ including NodeTimeoutError"| retry{retry_policy
matches?} + retry -->|"yes, attempts left"| exec + retry -->|"exhausted or absent"| handler{error_handler?} + handler -->|"yes"| run_handler["Invoke handler
with NodeError"] + run_handler --> route([Update state +
Command goto]) + handler -->|"no"| bubble([Exception
bubbles up]) + + classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710 + classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F + classDef alert fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643 + classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33 + + class exec,run_handler process + class retry,handler decision + class bubble alert + class done,route,start output +``` + +## Retries + +A retry policy automatically re-runs a failed node attempt based on exception type and backoff settings. + +:::python +Pass `retry_policy=` to @[`add_node`]: + +```python +from langgraph.types import RetryPolicy + +builder.add_node( + "call_api", + call_api, + retry_policy=RetryPolicy(max_attempts=3), +) +``` +::: + +:::js +Pass `retryPolicy` to @[`addNode`]: + +```typescript +import { StateGraph } from "@langchain/langgraph"; + +const graph = new StateGraph(State) + .addNode("callApi", callApi, { retryPolicy: { maxAttempts: 3 } }) + .compile(); +``` +::: + +### Default behavior + +:::python +By default, `retry_on` uses `default_retry_on`, which retries on **any** exception except the following (and their subclasses): + +- `ValueError` +- `TypeError` +- `ArithmeticError` +- `ImportError` +- `LookupError` +- `NameError` +- `SyntaxError` +- `RuntimeError` +- `ReferenceError` +- `StopIteration` +- `StopAsyncIteration` +- `OSError` + +For exceptions from popular HTTP libraries such as `requests` and `httpx`, it only retries on 5xx status codes. @[`NodeTimeoutError`] is retryable by default. +::: + +:::js +Retries are opt-in. A node retries only when it has a `retryPolicy` configured, either directly or through graph defaults with [`setNodeDefaults`](#graph-defaults). An empty policy (`{}`) is enough. Without a policy, the first failure ends the attempt and LangGraph does not call `retryOn`. + +If the policy omits `retryOn`, LangGraph uses a built-in handler that retries thrown errors except: + +- Abort and cancellation errors: `error.name === "AbortError"`, or `error.message` starts with `"Cancel"` or `"AbortError"` +- `GraphValueError`, matched by `error.name` +- Aborted connections: `error.code === "ECONNABORTED"` +- HTTP client errors with status 400, 401, 402, 403, 404, 405, 406, 407, or 409, read from `error.response?.status` or `error.status` for clients such as `fetch`, Axios, and similar clients +- OpenAI-style quota errors: `error.error?.code === "insufficient_quota"` + +Other HTTP statuses, including 408 and 5xx responses, are retryable unless you override `retryOn`. @[`NodeTimeoutError`] is not on this blocklist, so it is retryable when a retry policy is configured. + +Some failures bypass `retryOn`. Graph control-flow errors, such as `GraphInterrupt` and `Command` routing, bubble up without retrying. An aborted run signal also stops the retry loop, even if `retryOn` would return `true`. +::: + +### Parameters + +:::python +| Parameter | Type | Default | Description | +| --------- | ---- | ------- | ----------- | +| `max_attempts` | `int` | `3` | Maximum number of attempts, including the first. | +| `initial_interval` | `float` | `0.5` | Seconds before the first retry. | +| `backoff_factor` | `float` | `2.0` | Multiplier applied to the interval after each retry. | +| `max_interval` | `float` | `128.0` | Maximum seconds between retries. | +| `jitter` | `bool` | `True` | Add random jitter to the interval. | +| `retry_on` | `type[Exception] \| Sequence[type[Exception]] \| Callable[[Exception], bool]` | `default_retry_on` | Exceptions to retry on, or a callable returning `True` for retryable exceptions. | +::: + +:::js +| Parameter | Type | Default | Description | +| --------- | ---- | ------- | ----------- | +| `maxAttempts` | `number` | `3` | Maximum number of attempts, including the first. | +| `initialInterval` | `number` | `500` | Milliseconds before the first retry. | +| `backoffFactor` | `number` | `2.0` | Multiplier applied to the interval after each retry. | +| `maxInterval` | `number` | `128000` | Maximum milliseconds between retries. | +| `jitter` | `boolean` | `true` | Add random jitter to the interval. | +| `retryOn` | `(error: unknown) => boolean` | built-in handler (when policy is set) | Callable returning `true` for retryable exceptions. Only used when `retryPolicy` is configured. | +| `logWarning` | `boolean` | `true` | Whether to log a warning when a retry is attempted. | +::: + +### Custom retry logic + +:::python +Pass a callable or exception type to `retry_on`. Import `default_retry_on` to extend the default behavior: + +```python +from langgraph.types import RetryPolicy, default_retry_on + +def custom_retry_on(exc: BaseException) -> bool: + if isinstance(exc, MyCustomError): + return False + return default_retry_on(exc) + +builder.add_node( + "call_api", + call_api, + retry_policy=RetryPolicy(max_attempts=3, retry_on=custom_retry_on), +) +``` +::: + +:::js +Pass a callable to `retryOn`. Unlike Python, there is no exported `defaultRetryOn` helper—implement your own predicate: + +```typescript +import { StateGraph } from "@langchain/langgraph"; + +class MyCustomError extends Error {} + +const graph = new StateGraph(State) + .addNode("callApi", callApi, { + retryPolicy: { + maxAttempts: 3, + retryOn: (error: unknown) => { + if (error instanceof MyCustomError) return false; + // Retry on other errors + return true; + }, + }, + }) + .compile(); +``` +::: + +### Inspect retry state + +Use execution info inside a node to inspect the current attempt number. This is useful for switching to a fallback when the primary call keeps failing: + +:::python +```python +from langgraph.graph import StateGraph, START, END +from langgraph.runtime import Runtime +from langgraph.types import RetryPolicy +from typing_extensions import TypedDict + +class State(TypedDict): + result: str + +def my_node(state: State, runtime: Runtime) -> State: + if runtime.execution_info.node_attempt > 1: # [!code highlight] + return {"result": call_fallback_api()} + return {"result": call_primary_api()} + +builder = StateGraph(State) +builder.add_node("my_node", my_node, retry_policy=RetryPolicy(max_attempts=3)) +builder.add_edge(START, "my_node") +builder.add_edge("my_node", END) +``` + +`execution_info` exposes the following fields: + +| Attribute | Type | Description | +| --------- | ---- | ----------- | +| `node_attempt` | `int` | Current attempt number (1-indexed). `1` on the first try, `2` on the first retry, etc. | +| `node_first_attempt_time` | `float \| None` | Unix timestamp of when the first attempt started. Constant across retries. | +| `thread_id` | `str \| None` | Thread ID for the current execution. `None` without a checkpointer. | +| `run_id` | `str \| None` | Run ID for the current execution. `None` when not provided in config. | +| `checkpoint_id` | `str` | Checkpoint ID for the current execution. | +| `task_id` | `str` | Task ID for the current execution. | + +`execution_info` is available even without a retry policy—`node_attempt` defaults to `1`. +::: + +:::js +```typescript +import { StateGraph, StateSchema, START, END, type Runtime } from "@langchain/langgraph"; +import * as z from "zod"; + +const State = new StateSchema({ + result: z.string(), +}); + +const myNode = async (state: typeof State.State, runtime: Runtime
-
);
}
@@ -113,12 +99,14 @@ const stream = useStream
-
@@ -130,26 +118,25 @@ const stream = useStream
-
```
```ts Angular
-import { Component } from "@angular/core";
-import { useStream } from "@langchain/angular";
+import { Component, computed } from "@angular/core";
+import { injectStream } from "@langchain/angular";
const AGENT_URL = "http://localhost:2024";
@@ -158,86 +145,66 @@ const AGENT_URL = "http://localhost:2024";
template: `
{nodes.map((node, i) => {
- const status = getNodeStatus(node, streamingContent, values);
+ const isRunning =
+ isLoading && node.status !== "complete" && firstIncompleteIdx === i;
const colors = {
- idle: "bg-gray-200 text-gray-500",
- streaming: "bg-blue-400 text-white animate-pulse",
+ pending: "bg-gray-200 text-gray-500",
+ running: "bg-blue-400 text-white animate-pulse",
complete: "bg-green-500 text-white",
+ error: "bg-red-500 text-white",
};
+ const status = isRunning ? "running" : node.status;
return (
-
+
- {node.label}
+ {node.nodeName}
{i < nodes.length - 1 && (
{
+ if (node.status === "running") setOpen(true);
+ if (node.status === "complete") setOpen(false);
+ }, [node.status]);
return (
{content} ;
}
```
@@ -398,30 +348,23 @@ rendering:
```tsx
function NodeCardList({
nodes,
- messages,
- values,
- getMetadata,
+ stream,
+ isLoading,
}: {
- nodes: typeof PIPELINE_NODES;
- messages: BaseMessage[];
- values: Record;
- getMetadata: (msg: BaseMessage) => MessageMetadata | undefined;
+ nodes: SubgraphDiscoverySnapshot[];
+ stream: AnyStream;
+ isLoading: boolean;
}) {
- const streamingContent = getStreamingContent(messages, getMetadata);
+ const firstIncompleteIdx = nodes.findIndex((node) => node.status !== "complete");
return (
If your graph has conditional branching (e.g., skip "Research" for simple
-factual queries), the skipped nodes will never appear in the streaming content
-or state values. Your pipeline progress bar should reflect this by dimming or
-hiding skipped steps.
+factual queries), skipped nodes will not appear in `stream.subgraphs`. Your
+pipeline progress bar can render discovered nodes only or dim expected nodes
+that have no matching snapshot.
## Best practices
-- **Define nodes declaratively**. Keep your `PIPELINE_NODES` array as a single
- source of truth that maps node names, state keys, and display labels.
-- **Prefer streaming content for active nodes**. It gives users immediate
- feedback. Only fall back to committed state values after the node completes.
+- **Discover nodes from the stream**. Render cards from `stream.subgraphs`
+ rather than hardcoding expected nodes; conditional or skipped steps won't
+ appear until they run.
+- **Treat state keys as UI contracts**. Decide which graph outputs should be
+ stable enough for the frontend to render, and keep those keys documented next
+ to the graph definition.
+- **Use scoped messages for node cards**. They work while a node is streaming
+ and after it completes, without coupling UI cards to state key names.
- **Auto-collapse completed nodes**. In long pipelines, auto-collapse finished
cards so users can focus on the currently active step.
- **Show estimated timing**. If you have historical data on how long each node
diff --git a/frontend/overview.md b/frontend/overview.md
index 144013c..52825ab 100644
--- a/frontend/overview.md
+++ b/frontend/overview.md
@@ -3,11 +3,23 @@ title: Overview
description: Render LangGraph agents to the frontend
---
-Build frontends that visualize LangGraph pipelines in real time. These patterns show how to render multi-step graph execution with per-node status and streaming content from custom `StateGraph` workflows.
+Build frontends that visualize LangGraph pipelines in real time. These patterns
+show how to render multi-step graph execution with per-node status and streaming
+content from custom `StateGraph` workflows.
+
+LangGraph's frontend advantage is that the UI can follow the same structure as
+the graph. Nodes, state keys, checkpoints, interrupts, subgraphs, and streamed
+messages are all visible runtime concepts, so you can build interfaces that
+explain what the system is doing instead of hiding execution behind one
+assistant message.
+
+
+These patterns use the v1 frontend SDK packages. If you are using an earlier version, see the migration guides for [React](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-react/docs/v1-migration.md), [Vue](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/docs/v1-migration.md), [Svelte](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/docs/v1-migration.md), and [Angular](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/docs/v1-migration.md).
+
## Architecture
-LangGraph graphs are composed of named nodes connected by edges. Each node executes a step (classify, research, analyze, synthesize) and writes output to a specific state key. On the frontend, `useStream` provides reactive access to node outputs, streaming tokens, and graph metadata so you can map each node to a UI card.
+LangGraph graphs are composed of named nodes connected by edges. Each node executes a step (classify, research, analyze, synthesize) and writes output to a specific state key. On the frontend, the SDK stream handle provides reactive access to node outputs, streaming tokens, and discovered subgraphs so you can map each node to a UI card.
```mermaid
%%{
@@ -48,15 +60,18 @@ class State(MessagesState):
classification: str
research: str
analysis: str
+ synthesis: str
graph = StateGraph(State)
graph.add_node("classify", classify_node)
-graph.add_node("research", research_node)
+graph.add_node("do_research", research_node)
graph.add_node("analyze", analyze_node)
+graph.add_node("synthesize", synthesize_node)
graph.add_edge(START, "classify")
-graph.add_edge("classify", "research")
-graph.add_edge("research", "analyze")
-graph.add_edge("analyze", END)
+graph.add_edge("classify", "do_research")
+graph.add_edge("do_research", "analyze")
+graph.add_edge("analyze", "synthesize")
+graph.add_edge("synthesize", END)
app = graph.compile()
```
@@ -66,30 +81,36 @@ app = graph.compile()
:::js
```ts
-import { StateGraph, StateSchema, MessagesValue, START, END } from "@langchain/langgraph";
-import * as z from "zod";
-
-const State = new StateSchema({
- messages: MessagesValue,
- classification: z.string(),
- research: z.string(),
- analysis: z.string(),
+import { Annotation, MessagesAnnotation, StateGraph, START, END } from "@langchain/langgraph";
+
+const State = Annotation.Root({
+ ...MessagesAnnotation.spec,
+ classification: Annotation(),
+ research: Annotation(),
+ analysis: Annotation(),
+ synthesis: Annotation(),
});
const graph = new StateGraph(State)
.addNode("classify", classifyNode)
- .addNode("research", researchNode)
+ .addNode("do_research", researchNode)
.addNode("analyze", analyzeNode)
+ .addNode("synthesize", synthesizeNode)
.addEdge(START, "classify")
- .addEdge("classify", "research")
- .addEdge("research", "analyze")
- .addEdge("analyze", END)
+ .addEdge("classify", "do_research")
+ .addEdge("do_research", "analyze")
+ .addEdge("analyze", "synthesize")
+ .addEdge("synthesize", END)
.compile();
```
:::
-On the frontend, `useStream` exposes `stream.values` for completed node outputs and `getMessagesMetadata` for identifying which node produced each streaming token.
+On the frontend, @[`useStream`] exposes `stream.subgraphs` for graph-node discovery
+and selector helpers such as `useMessages(stream, node)` for node-scoped
+streaming content. `stream.values` still holds the full graph state when you
+need fields such as the final `synthesis`. Angular uses the same stream API
+shape through @[`injectStream`].
```ts
import { useStream } from "@langchain/react";
@@ -103,17 +124,39 @@ function Pipeline() {
const classification = stream.values?.classification;
const research = stream.values?.research;
const analysis = stream.values?.analysis;
+ const graphNodes = [...stream.subgraphs.values()];
}
```
+## What makes this different from a chat stream
+
+Custom graphs often power product workflows: research pipelines, approval flows,
+data pipelines, data enrichment, code review, planning, and multi-step analysis. The
+frontend SDK lets you render these workflows using graph-native signals:
+
+| Runtime concept | Frontend UX |
+| --- | --- |
+| **Named nodes** | One card, timeline step, or status badge per graph node. |
+| **State keys** | Dedicated UI regions for typed outputs such as classification, sources, analysis, and final synthesis. |
+| **Streaming metadata** | Route partial messages to the node that produced them. |
+| **Checkpoints** | Inspect or resume from prior graph states for debugging and auditability. |
+| **Interrupts** | Pause a node for human input, approval, or correction, then continue. |
+| **Subgraphs** | Reveal nested execution only when the user needs more detail. |
+
+Because the SDK exposes these concepts directly, you can scale from a simple
+chat panel to a full workflow debugger without changing the backend protocol.
+
## Patterns
Visualize multi-step graph pipelines with per-node status and streaming content.
+
+ Stream custom server-side data to the frontend and read it with `useExtension` and `useChannel`.
+
## Related patterns
-The [LangChain frontend patterns](/oss/langchain/frontend/overview)—markdown messages, tool calling, optimistic updates, and more—work with any LangGraph graph. The `useStream` hook provides the same core API whether you use `createAgent`, `createDeepAgent`, or a custom `StateGraph`.
+The [LangChain frontend patterns](/oss/langchain/frontend/overview)—markdown messages, tool calling, human-in-the-loop, resumable streams, and time travel—work with any LangGraph graph. The stream API provides the same core data model whether you use `createAgent`, `createDeepAgent`, or a custom `StateGraph`.
diff --git a/functional-api.mdx b/functional-api.mdx
index db0006a..9cb2faa 100644
--- a/functional-api.mdx
+++ b/functional-api.mdx
@@ -3,7 +3,10 @@ title: Functional API overview
sidebarTitle: Functional API
---
-
+import LanggraphFunctionalApiInterruptStreamPy from '/snippets/code-samples/langgraph-functional-api-interrupt-stream-py.mdx';
+import LanggraphFunctionalApiInterruptResumePy from '/snippets/code-samples/langgraph-functional-api-interrupt-resume-py.mdx';
+import LanggraphFunctionalApiInterruptStreamJs from '/snippets/code-samples/langgraph-functional-api-interrupt-stream-js.mdx';
+import LanggraphFunctionalApiInterruptResumeJs from '/snippets/code-samples/langgraph-functional-api-interrupt-resume-js.mdx';
The **Functional API** allows you to add LangGraph's key features ([persistence](/oss/langgraph/persistence), [memory](/oss/langgraph/add-memory), [human-in-the-loop](/oss/langgraph/interrupts), and [streaming](/oss/langgraph/streaming)) to your applications with minimal changes to your existing code.
@@ -114,157 +117,21 @@ const workflow = entrypoint(
When the workflow is resumed, it executes from the very start, but because the result of the `writeEssay` task was already saved, the task result will be loaded from the checkpoint instead of being recomputed.
:::python
- ```python
- import time
- from langchain_core.utils.uuid import uuid7
- from langgraph.func import entrypoint, task
- from langgraph.types import interrupt
- from langgraph.checkpoint.memory import InMemorySaver
-
-
- @task
- def write_essay(topic: str) -> str:
- """Write an essay about the given topic."""
- time.sleep(1) # This is a placeholder for a long-running task.
- return f"An essay about topic: {topic}"
-
- @entrypoint(checkpointer=InMemorySaver())
- def workflow(topic: str) -> dict:
- """A simple workflow that writes an essay and asks for a review."""
- essay = write_essay("cat").result()
- is_approved = interrupt(
- {
- # Any json-serializable payload provided to interrupt as argument.
- # It will be surfaced on the client side as an Interrupt when streaming data
- # from the workflow.
- "essay": essay, # The essay we want reviewed.
- # We can add any additional information that we need.
- # For example, introduce a key called "action" with some instructions.
- "action": "Please approve/reject the essay",
- }
- )
- return {
- "essay": essay, # The essay that was generated
- "is_approved": is_approved, # Response from HIL
- }
-
-
- thread_id = str(uuid7())
- config = {"configurable": {"thread_id": thread_id}}
- for item in workflow.stream("cat", config):
- print(item)
- # > {'write_essay': 'An essay about topic: cat'}
- # > {
- # > '__interrupt__': (
- # > Interrupt(
- # > value={
- # > 'essay': 'An essay about topic: cat',
- # > 'action': 'Please approve/reject the essay'
- # > },
- # > id='b9b2b9d788f482663ced6dc755c9e981'
- # > ),
- # > )
- # > }
- ```
+
@@ -437,8 +306,10 @@ Using the [`@entrypoint`](#entrypoint) yields a @[`Pregel`][Pregel.stream] objec
}
}
- async for chunk in my_workflow.astream(some_input, config):
- print(chunk)
+ stream = await my_workflow.astream_events(some_input, config, version="v3")
+ async for message in stream.messages:
+ async for token in message.text:
+ print(token, end="", flush=True)
```
@@ -466,8 +337,11 @@ Using the [`entrypoint`](#entrypoint) function will return an object that can be
}
};
- for await (const chunk of myWorkflow.stream(someInput, config)) {
- console.log(chunk);
+ const stream = await myWorkflow.streamEvents(someInput, config, { version: "v3" });
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -516,8 +390,10 @@ Resuming an execution after an @[interrupt][interrupt] can be done by passing a
}
}
- for chunk in my_workflow.stream(Command(resume=some_resume_value), config):
- print(chunk)
+ stream = my_workflow.stream_events(Command(resume=some_resume_value), config, version="v3")
+ for message in stream.messages:
+ for token in message.text:
+ print(token, end="", flush=True)
```
@@ -530,8 +406,10 @@ Resuming an execution after an @[interrupt][interrupt] can be done by passing a
}
}
- async for chunk in my_workflow.astream(Command(resume=some_resume_value), config):
- print(chunk)
+ stream = await my_workflow.astream_events(Command(resume=some_resume_value), config, version="v3")
+ async for message in stream.messages:
+ async for token in message.text:
+ print(token, end="", flush=True)
```
@@ -564,13 +442,16 @@ Resuming an execution after an @[interrupt][interrupt] can be done by passing a
}
};
- const stream = await myWorkflow.stream(
+ const stream = await myWorkflow.streamEvents(
new Command({ resume: someResumableValue }),
config,
- )
+ { version: "v3" },
+ );
- for await (const chunk of stream) {
- console.log(chunk);
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -618,8 +499,10 @@ This assumes that the underlying **error** has been resolved and execution can p
}
}
- for chunk in my_workflow.stream(None, config):
- print(chunk)
+ stream = my_workflow.stream_events(None, config, version="v3")
+ for message in stream.messages:
+ for token in message.text:
+ print(token, end="", flush=True)
```
@@ -631,8 +514,10 @@ This assumes that the underlying **error** has been resolved and execution can p
}
}
- async for chunk in my_workflow.astream(None, config):
- print(chunk)
+ stream = await my_workflow.astream_events(None, config, version="v3")
+ async for message in stream.messages:
+ async for token in message.text:
+ print(token, end="", flush=True)
```
@@ -665,8 +550,11 @@ This assumes that the underlying **error** has been resolved and execution can p
}
};
- for await (const chunk of myWorkflow.stream(null, config)) {
- console.log(chunk);
+ const stream = await myWorkflow.streamEvents(null, config, { version: "v3" });
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -675,7 +563,7 @@ This assumes that the underlying **error** has been resolved and execution can p
### Short-term memory
-When an `entrypoint` is defined with a `checkpointer`, it stores information between successive invocations on the same **thread id** in [checkpoints](/oss/langgraph/persistence#checkpoints).
+When an `entrypoint` is defined with a `checkpointer`, it stores information between successive invocations on the same **thread id** in [checkpoints](/oss/langgraph/checkpointers#checkpoints).
:::python
This allows accessing the state from the previous invocation using the `previous` parameter.
@@ -877,7 +765,7 @@ const myWorkflow = entrypoint(
* **Checkpointing**: When you need to save the result of a long-running operation to a checkpoint, so you don't need to recompute it when resuming the workflow.
* **Human-in-the-loop**: If you're building a workflow that requires human intervention, you MUST use **tasks** to encapsulate any randomness (e.g., API calls) to ensure that the workflow can be resumed correctly. See the [determinism](#determinism) section for more details.
* **Parallel Execution**: For I/O-bound tasks, **tasks** enable parallel execution, allowing multiple operations to run concurrently without blocking (e.g., calling multiple APIs).
-* **Observability**: Wrapping operations in **tasks** provides a way to track the progress of the workflow and monitor the execution of individual operations using [LangSmith](/langsmith/home).
+* **Observability**: Wrapping operations in **tasks** provides a way to track the progress of the workflow and monitor the execution of individual operations using [LangSmith](/langsmith/observability).
* **Retryable Work**: When work needs to be retried to handle failures or inconsistencies, **tasks** provide a way to encapsulate and manage the retry logic.
## Serialization
@@ -901,15 +789,25 @@ Providing non-serializable inputs or outputs will result in a runtime error when
## Determinism
-To utilize features like **human-in-the-loop**, any randomness should be encapsulated inside of **tasks**. This guarantees that when execution is halted (e.g., for human in the loop) and then resumed, it will follow the same _sequence of steps_, even if **task** results are non-deterministic.
+When you resume a workflow run, the code does **NOT** resume from the **same line of code** where execution stopped. Execution returns to a checkpoint boundary, and the workflow **replays** forward until it reaches the pause again.
+
+For the Functional API, replay starts at the beginning of the **entrypoint** while LangGraph restores completed [**task**](/oss/langgraph/functional-api#task) and [**subgraph**](/oss/langgraph/use-subgraphs) results from the checkpointer instead of recomputing them. That preserves the recorded order of steps across pauses, including for long-running or non-deterministic **task** outputs.
+
+To use features like **human-in-the-loop**, you must place non-deterministic work (for example, random values) and side effects (for example, file writes or API calls) in [**tasks**](/oss/langgraph/functional-api#task).
+
+Different runs of a workflow can produce different results, but resuming a **specific** thread should replay the same persisted **task** and **subgraph** results.
-LangGraph achieves this behavior by persisting **task** and [**subgraph**](/oss/langgraph/use-subgraphs) results as they execute. A well-designed workflow ensures that resuming execution follows the _same sequence of steps_, allowing previously computed results to be retrieved correctly without having to re-execute them. This is particularly useful for long-running **tasks** or **tasks** with non-deterministic results, as it avoids repeating previously done work and allows resuming from essentially the same.
+To ensure that your workflow is deterministic and can be consistently replayed, follow these guidelines:
-While different runs of a workflow can produce different results, resuming a **specific** run should always follow the same sequence of recorded steps. This allows LangGraph to efficiently look up **task** and **subgraph** results that were executed prior to the graph being interrupted and avoid recomputing them.
+* **Avoid repeating work**: In an **entrypoint**, if you chain several side effects (for example, logging, file writes, or network calls), give each its own **task** so resume restores their outputs from the checkpointer instead of running them again.
+* **Encapsulate non-deterministic operations**: Keep values that can change between attempts (for example, random numbers or wall-clock reads) inside **tasks**, so replay lines up with what was checkpointed.
+* **Use idempotent operations**: For partial task failures and retries, see [Idempotency](#idempotency).
## Idempotency
-Idempotency ensures that running the same operation multiple times produces the same result. This helps prevent duplicate API calls and redundant processing if a step is rerun due to a failure. Always place API calls inside **tasks** functions for checkpointing, and design them to be idempotent in case of re-execution. Re-execution can occur if a **task** starts, but does not complete successfully. Then, if the workflow is resumed, the **task** will run again. Use idempotency keys or verify existing results to avoid duplication.
+Idempotency ensures that running the same operation multiple times produces the same result. This helps prevent duplicate API calls and redundant processing if a step is rerun due to a failure. Always place API calls inside **tasks** functions for checkpointing, and design them to be idempotent in case of re-execution.
+This is particularly important for operations that result in data writes.
+When a workflow resumes, LangGraph replays completed **task** results from the checkpoint. A **task** that started but did not finish may run again on that resume, so design side effects to be idempotent. Use idempotency keys or verify existing results to avoid unintended duplication.
## Common pitfalls
diff --git a/graph-api.mdx b/graph-api.mdx
index b3a6d2b..7dd3a33 100644
--- a/graph-api.mdx
+++ b/graph-api.mdx
@@ -3,7 +3,23 @@ title: Graph API overview
sidebarTitle: Graph API
---
-
+import GraphApiUsingTasksOriginalJs from '/snippets/code-samples/graph-api-using-tasks-original-js.mdx';
+import GraphApiUsingTasksOriginalPy from '/snippets/code-samples/graph-api-using-tasks-original-py.mdx';
+import GraphApiUsingTasksTaskJs from '/snippets/code-samples/graph-api-using-tasks-task-js.mdx';
+import GraphApiUsingTasksTaskPy from '/snippets/code-samples/graph-api-using-tasks-task-py.mdx';
+import LanggraphGraphApiMultipleSchemasJs from '/snippets/code-samples/langgraph-graph-api-multiple-schemas-js.mdx';
+import LanggraphGraphApiMultipleSchemasPy from '/snippets/code-samples/langgraph-graph-api-multiple-schemas-py.mdx';
+import LanggraphGraphApiResumeV2Py from '/snippets/code-samples/langgraph-graph-api-resume-v2-py.mdx';
+import LanggraphGraphApiStreamPrivateChannelJs from '/snippets/code-samples/langgraph-graph-api-stream-private-channel-js.mdx';
+import LanggraphGraphApiStreamPrivateChannelPy from '/snippets/code-samples/langgraph-graph-api-stream-private-channel-py.mdx';
+import LanggraphGraphApiReducersAppendStringsCallJs from '/snippets/code-samples/langgraph-graph-api-reducers-append-strings-call-js.mdx';
+import LanggraphGraphApiReducersAppendStringsCallPy from '/snippets/code-samples/langgraph-graph-api-reducers-append-strings-call-py.mdx';
+import LanggraphGraphApiReducersAppendStringsJs from '/snippets/code-samples/langgraph-graph-api-reducers-append-strings-js.mdx';
+import LanggraphGraphApiReducersAppendStringsPy from '/snippets/code-samples/langgraph-graph-api-reducers-append-strings-py.mdx';
+import LanggraphGraphApiReducersCustomStateJs from '/snippets/code-samples/langgraph-graph-api-reducers-custom-state-js.mdx';
+import LanggraphGraphApiReducersCustomStatePy from '/snippets/code-samples/langgraph-graph-api-reducers-custom-state-py.mdx';
+import LanggraphGraphApiReducersDefaultStateJs from '/snippets/code-samples/langgraph-graph-api-reducers-default-state-js.mdx';
+import LanggraphGraphApiReducersDefaultStatePy from '/snippets/code-samples/langgraph-graph-api-reducers-default-state-py.mdx';
## Graphs
@@ -149,103 +165,13 @@ Let's look at an example:
:::python
-```python
-class InputState(TypedDict):
- user_input: str
-
-class OutputState(TypedDict):
- graph_output: str
-
-class OverallState(TypedDict):
- foo: str
- user_input: str
- graph_output: str
-
-class PrivateState(TypedDict):
- bar: str
-
-def node_1(state: InputState) -> OverallState:
- # Write to OverallState
- return {"foo": state["user_input"] + " name"}
-
-def node_2(state: OverallState) -> PrivateState:
- # Read from OverallState, write to PrivateState
- return {"bar": state["foo"] + " is"}
-
-def node_3(state: PrivateState) -> OutputState:
- # Read from PrivateState, write to OutputState
- return {"graph_output": state["bar"] + " Lance"}
-
-builder = StateGraph(OverallState,input_schema=InputState,output_schema=OutputState)
-builder.add_node("node_1", node_1)
-builder.add_node("node_2", node_2)
-builder.add_node("node_3", node_3)
-builder.add_edge(START, "node_1")
-builder.add_edge("node_1", "node_2")
-builder.add_edge("node_2", "node_3")
-builder.add_edge("node_3", END)
-
-graph = builder.compile()
-graph.invoke({"user_input":"My"})
-# {'graph_output': 'My name is Lance'}
-```
+
+**Private channels are not redacted when streaming.**
+
+Input, output, and private schemas constrain what each node _reads_ (its input schema) and what `invoke` _returns_ (the output schema). They do **not** hide channels from `stream`.
+
+When you stream with `stream_mode="values"`, the graph emits **all** of its state channels by default, including private ones, because values streaming defaults to the full set of state channels rather than the output schema. This is why a private channel like `bar` is hidden by `invoke` but visible while streaming:
+
+
+:::
+
+:::js
+
+**Private channels are not redacted when streaming.**
+
+Input, output, and private schemas constrain what each node _reads_ (its input schema) and what `invoke` _returns_ (the output schema). They do **not** hide channels from `stream`.
+
+When you stream with `streamMode: "values"`, the graph emits **all** of its state channels by default — including private ones — because values streaming defaults to the full set of state channels rather than the output schema. This is why a private channel like `bar` is hidden by `invoke` but visible while streaming:
+
+
+:::
+
### Reducers
Reducers are key to understanding how updates from nodes are applied to the `State`. Each key in the `State` has its own independent reducer function. If no reducer function is explicitly specified then it is assumed that all updates to that key should override it. There are a few different types of reducers, starting with the default type of reducer:
-#### Default reducer
+#### Reducer arguments
-These two examples show how to use the default reducer:
+Every reducer is a binary function with two positional arguments:
-:::python
+- **Left argument**: The current value already stored in state for that key.
+- **Right argument**: The update for that key returned by a node.
-```python Example A
-from typing_extensions import TypedDict
+When a node returns a partial update, LangGraph calls the reducer for each updated key and saves the return value as the new state value:
-class State(TypedDict):
- foo: int
- bar: list[str]
+:::python
+```python
+new_value = reducer(left=current_state[key], right=node_update[key])
```
+:::
+
+:::js
+```typescript
+const newValue = reducer(currentState[key], nodeUpdate[key]); // left, right
+```
+:::
+
+The left argument always comes from accumulated state. The right argument always comes from the latest node update. The following example names both arguments explicitly:
+
+:::python
+
+
+
+
+
+
+
+:::
+
+:::js
+
+
+
+
+
+
+:::
+
### `START` node
The @[`START`] Node is a special node that represents the node that sends user input to the graph. The main purpose for referencing this node is to determine which nodes should be called first.
@@ -821,6 +873,17 @@ print(graph.invoke({"x": 5}, stream_mode='updates')) # [!code highlight]
# [{'expensive_node': {'result': 10}, '__metadata__': {'cached': True}}]
```
+
+`set_entry_point(node)` defines the first node the graph will execute.
+It is equivalent to `builder.add_edge(START, node)`.
+
+`set_finish_point(node)` defines the last node in the graph.
+It is equivalent to `builder.add_edge(node, END)`.
+
+Both methods are valid but `add_edge(START, ...)` and `add_edge(..., END)`
+are the recommended modern syntax.
+
+
1. First run takes two seconds to run (due to mocked expensive computation).
2. Second run utilizes cache and returns quickly.
:::
@@ -873,6 +936,10 @@ Edges define how the logic is routed and how the graph decides to stop. This is
A node can have multiple outgoing edges. If a node has multiple outgoing edges, **all** of those destination nodes will be executed in parallel as a part of the next superstep.
+
+For each node, choose one routing mechanism: use normal edges for static routing, or use conditional edges / @[`Command`] for dynamic routing. Do not mix normal edges and dynamic routing from the same node, because both paths can execute and make graph behavior harder to reason about.
+
+
### Normal edges
:::python
@@ -1013,6 +1080,8 @@ By default, `Nodes` and `Edges` are defined ahead of time and operate on the sam
To support this design pattern, LangGraph supports returning @[`Send`] objects from conditional edges. `Send` takes two arguments: first is the name of the node, and second is the state to pass to that node.
```python
+from langgraph.types import Send
+
def continue_to_jokes(state: OverallState):
return [Send("generate_joke", {"subject": s}) for s in state['subjects']]
@@ -1131,7 +1200,7 @@ builder.addNode("myNode", myNode, {
-@[`Command`] only adds dynamic edges—static edges defined with `add_edge` / `addEdge` still execute. For example, if `node_a` returns `Command(goto="my_other_node")` and you also have `graph.add_edge("node_a", "node_b")`, both `node_b` and `my_other_node` will run.
+@[`Command`] only adds dynamic edges—static edges defined with `add_edge` / `addEdge` still execute. For example, if `node_a` returns `Command(goto="my_other_node")` and you also have `graph.add_edge("node_a", "node_b")`, both `node_b` and `my_other_node` will run. For each node, use either @[`Command`] or static edges to route to the next nodes, not both.
@@ -1194,7 +1263,7 @@ This is particularly useful when implementing [multi-agent handoffs](/oss/langch
-`Command(resume=...)` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`. Do not use `Command(update=...)` as input to continue multi-turn conversations—because passing any `Command` as input resumes from the latest checkpoint (i.e. the last step that ran, not `__start__`), the graph will appear stuck if it already finished. To continue a conversation on an existing thread, pass a plain input dict:
+`Command(resume=...)` is the **only** `Command` pattern intended as input to `invoke()`/`stream()` (optionally combined with `update=...` to also apply a state change while resuming). Do not use `Command(update=...)` alone as input to continue multi-turn conversations—because passing any `Command` as input resumes from the latest checkpoint (i.e. the last step that ran, not `__start__`), the graph will appear stuck if it already finished. To continue a conversation on an existing thread, pass a plain input dict:
```python
# WRONG - graph resumes from the latest checkpoint
@@ -1217,7 +1286,7 @@ graph.invoke( { # [!code ++]
-`new Command({ resume: ... })` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`. Do not use `new Command({ update: ... })` as input to continue multi-turn conversations—because passing any `Command` as input resumes from the latest checkpoint (i.e. the last step that ran, not `__start__`), the graph will appear stuck if it already finished. To continue a conversation on an existing thread, pass a plain input object:
+`new Command({ resume: ... })` is the **only** `Command` pattern intended as input to `invoke()`/`stream()` (optionally combined with `update` to also apply a state change while resuming). Do not use `new Command({ update: ... })` alone as input to continue multi-turn conversations—because passing any `Command` as input resumes from the latest checkpoint (i.e. the last step that ran, not `__start__`), the graph will appear stuck if it already finished. To continue a conversation on an existing thread, pass a plain input object:
```typescript
// WRONG - graph resumes from the latest checkpoint
@@ -1238,20 +1307,7 @@ await graph.invoke({ messages: [{ role: "user", content: "follow up" }] }, confi
Use `Command(resume=...)` to provide a value and resume graph execution after an [interrupt](/oss/langgraph/interrupts). The value passed to `resume` becomes the return value of the `interrupt()` call inside the paused node:
-```python
-from langgraph.types import Command, interrupt
-
-def human_review(state: State):
- # Pauses the graph and waits for a value
- answer = interrupt("Do you approve?")
- return {"messages": [{"role": "user", "content": answer}]}
-
-# First invocation - hits the interrupt and pauses
-result = graph.invoke({"messages": [...]}, config)
-
-# Resume with a value - the interrupt() call returns "yes"
-result = graph.invoke(Command(resume="yes"), config)
-```
+
-When used inside tools, `goto` adds a dynamic edge—any static edges already defined on the node that called the tool will still execute.
+When used inside tools, `goto` adds a dynamic edge—any static edges already defined on the node that called the tool will still execute. For each node, use either tool-driven dynamic routing or static edges to route to the next nodes, not both.
@@ -1303,6 +1359,10 @@ LangGraph can easily handle migrations of graph definitions (nodes, edges, and s
- State keys that are renamed lose their saved state in existing threads
- State keys whose types change in incompatible ways could currently cause issues in threads with state from before the change -- if this is a blocker please reach out and we can prioritize a solution.
+
+For changes that are technically compatible but alter business logic, such as rewriting the tool set or restructuring conversation flow, see [Business compatibility](/oss/langgraph/backward-compatibility#business-compatibility). That page covers pinning a behavioral version in state so existing threads keep the old path while new threads pick up the latest version.
+
+
## Runtime context
:::python
@@ -1436,13 +1496,13 @@ The current step counter is accessible in `config.metadata.langgraph_step` withi
:::python
-The step counter is stored in `config["metadata"]["langgraph_step"]`. The recursion limit check follows the logic: `step > stop` where `stop = step + recursion_limit + 1`. When the limit is exceeded, LangGraph raises a `GraphRecursionError`.
+The step counter is stored in `config["metadata"]["langgraph_step"]`. LangGraph increments this counter as the graph executes and raises a `GraphRecursionError` once the configured `recursion_limit` is exceeded.
:::
:::js
-The step counter is stored in `config.metadata.langgraph_step`. The recursion limit check follows the logic: `step > stop` where `stop = step + recursionLimit + 1`. When the limit is exceeded, LangGraph raises a `GraphRecursionError`.
+The step counter is stored in `config.metadata.langgraph_step`. LangGraph increments this counter as the graph executes and raises a `GraphRecursionError` once the configured `recursionLimit` is exceeded.
:::
@@ -1785,7 +1845,7 @@ It's often nice to be able to visualize graphs, especially as they get more comp
## Observability and Tracing
-To trace, debug and evaluate your agents, use [LangSmith](/langsmith/home).
+To trace, debug and evaluate your agents, use [LangSmith](/langsmith/observability).
## Learn more
diff --git a/install.mdx b/install.mdx
index aa321a6..dbb0879 100644
--- a/install.mdx
+++ b/install.mdx
@@ -4,7 +4,6 @@ sidebarTitle: Install
---
-
To install the base LangGraph package:
:::python
diff --git a/interrupts.mdx b/interrupts.mdx
index a0b49eb..9bf442a 100644
--- a/interrupts.mdx
+++ b/interrupts.mdx
@@ -2,6 +2,18 @@
title: Interrupts
---
+import LanggraphInterruptsResumeV2Py from '/snippets/code-samples/langgraph-interrupts-resume-v2-py.mdx';
+import LanggraphInterruptsMultiplePy from '/snippets/code-samples/langgraph-interrupts-multiple-py.mdx';
+import LanggraphInterruptsHitlStreamPy from '/snippets/code-samples/langgraph-interrupts-hitl-stream-py.mdx';
+import LanggraphInterruptsHitlStreamJs from '/snippets/code-samples/langgraph-interrupts-hitl-stream-js.mdx';
+import LanggraphInterruptsApprovalPy from '/snippets/code-samples/langgraph-interrupts-approval-py.mdx';
+import LanggraphInterruptsReviewPy from '/snippets/code-samples/langgraph-interrupts-review-py.mdx';
+import LanggraphInterruptsValidatePy from '/snippets/code-samples/langgraph-interrupts-validate-py.mdx';
+import LanggraphInterruptsValidateConditionalEdgePatternPy from '/snippets/code-samples/langgraph-interrupts-validate-conditional-edge-pattern-py.mdx';
+import LanggraphInterruptsValidateConditionalEdgePatternJs from '/snippets/code-samples/langgraph-interrupts-validate-conditional-edge-pattern-js.mdx';
+import LanggraphInterruptsValidateConditionalEdgeJs from '/snippets/code-samples/langgraph-interrupts-validate-conditional-edge-js.mdx';
+import LanggraphInterruptsValidateConditionalEdgePy from '/snippets/code-samples/langgraph-interrupts-validate-conditional-edge-py.mdx';
+
Interrupts allow you to pause graph execution at specific points and wait for external input before continuing. This enables human-in-the-loop patterns where you need external input to proceed. When an interrupt is triggered, LangGraph saves the graph state using its [persistence](/oss/langgraph/persistence) layer and waits indefinitely until you resume execution.
Interrupts work by calling the `interrupt()` function at any point in your graph nodes. The function accepts any JSON-serializable value which is surfaced to the caller. When you're ready to continue, you resume execution by re-invoking the graph using `Command`, which then becomes the return value of the `interrupt()` call from inside the node.
@@ -11,7 +23,7 @@ Unlike static breakpoints (which pause before or after specific nodes), interrup
:::python
- **Checkpointing keeps your place:** the checkpointer writes the exact graph state so you can resume later, even when in an error state.
- **`thread_id` is your pointer:** set `config={"configurable": {"thread_id": ...}}` to tell the checkpointer which state to load.
-- **Interrupt payloads surface via `chunk["interrupts"]`:** when streaming with `version="v2"`, the values you pass to `interrupt()` appear in the `interrupts` field of `values` stream parts so you know what the graph is waiting on.
+- **Interrupt payloads surface via `stream.interrupts`:** when using [event streaming](/oss/langgraph/event-streaming) (`graph.stream_events(..., version="v3")`), the values you pass to `interrupt()` appear on `stream.interrupts`, and `stream.interrupted` is `True` when the run pauses for input.
:::
:::js
- **Checkpointing keeps your place:** the checkpointer writes the exact graph state so you can resume later, even when in an error state.
@@ -61,7 +73,12 @@ When you call @[`interrupt`], here's what happens:
1. **Graph execution gets suspended** at the exact point where @[`interrupt`] is called
2. **State is saved** using the checkpointer so execution can be resumed later, In production, this should be a persistent checkpointer (e.g. backed by a database)
+:::python
+3. **Value is returned** to the caller on `stream.interrupts` when using [event streaming](/oss/langgraph/event-streaming) (`graph.stream_events(..., version="v3")`), or under `__interrupt__` with the default `invoke()` API; it can be any JSON-serializable value (string, object, array, etc.)
+:::
+:::js
3. **Value is returned** to the caller under `__interrupt__`; it can be any JSON-serializable value (string, object, array, etc.)
+:::
4. **Graph waits indefinitely** until you resume execution with a response
5. **Response is passed back** into the node when you resume, becoming the return value of the `interrupt()` call
@@ -70,42 +87,13 @@ When you call @[`interrupt`], here's what happens:
After an interrupt pauses execution, you resume the graph by invoking it again with a `Command` that contains the resume value. The resume value is passed back to the `interrupt` call, allowing the node to continue execution with the external input.
:::python
-
-
- ```python
- from langgraph.types import Command
-
- # Initial run - hits the interrupt and pauses
- # thread_id is the persistent pointer (stores a stable ID in production)
- config = {"configurable": {"thread_id": "thread-1"}}
- result = graph.invoke({"input": "data"}, config=config, version="v2")
+The recommended way to drive a graph that may interrupt is [event streaming](/oss/langgraph/event-streaming) — it surfaces interrupts via `stream.interrupts` and `stream.interrupted`, and exposes the final state through `stream.output`.
- # result is a GraphOutput with .value and .interrupts
- # .interrupts contains the payloads passed to interrupt()
- print(result.interrupts)
- # > (Interrupt(value='Do you approve this action?'),)
+
-
- ```python
- from langgraph.types import Command
-
- config = {"configurable": {"thread_id": "thread-1"}}
- result = graph.invoke({"input": "data"}, config=config)
-
- # __interrupt__ contains the payload that was passed to interrupt()
- print(result["__interrupt__"])
- # > [Interrupt(value='Do you approve this action?')]
-
- # Resume with the human's response
- graph.invoke(Command(resume=True), config=config)
- ```
-
-
+
+The default `graph.invoke(...)` API still works and surfaces interrupts under `result["__interrupt__"]`. Use it when you don't need streamed projections; otherwise prefer `graph.stream_events(..., version="v3")`.
+
**Key points about resuming:**
@@ -116,7 +104,7 @@ After an interrupt pauses execution, you resume the graph by invoking it again w
-`Command(resume=...)` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`. The other `Command` parameters (`update`, `goto`, `graph`) are designed for [returning from node functions](/oss/langgraph/graph-api#command). Do not pass `Command(update=...)` as input to continue multi-turn conversations—pass a plain input dict instead.
+`Command(resume=...)` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`/`stream_events()`. The other `Command` parameters (`update`, `goto`, `graph`) are designed for [returning from node functions](/oss/langgraph/graph-api#command). Do not pass `Command(update=...)` as input to continue multi-turn conversations—pass a plain input dict instead.
@@ -150,7 +138,7 @@ await graph.invoke(new Command({ resume: true }), config);
-`new Command({ resume: ... })` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`. The other `Command` parameters (`update`, `goto`, `graph`) are designed for [returning from node functions](/oss/langgraph/graph-api#command). Do not pass `new Command({ update: ... })` as input to continue multi-turn conversations—pass a plain input object instead.
+`new Command({ resume: ... })` is the **only** `Command` pattern intended as input to `invoke()`/`stream()`/`stream_events()`. The other `Command` parameters (`update`, `goto`, `graph`) are designed for [returning from node functions](/oss/langgraph/graph-api#command). Do not pass `new Command({ update: ... })` as input to continue multi-turn conversations—pass a plain input object instead.
@@ -168,46 +156,31 @@ The key thing that interrupts unlock is the ability to pause execution and wait
### Stream with human-in-the-loop (HITL) interrupts
-When building interactive agents with human-in-the-loop workflows, you can stream both message chunks and node updates simultaneously to provide real-time feedback while handling interrupts.
+When building interactive agents with human-in-the-loop workflows, you can use [event streaming](/oss/langgraph/event-streaming) to consume message chunks and state snapshots concurrently while handling interrupts.
-Use multiple stream modes (`"messages"` and `"updates"`) with `subgraphs=True` (if subgraphs are present) to:
-- Stream AI responses in real-time as they're generated
-- Detect when the graph encounters an interrupt
-- Handle user input and resume execution seamlessly
+Use the typed projections returned by `graph.stream_events(..., version="v3")` in a loop until the run finishes:
+- Stream AI responses token-by-token via `stream.messages`
+- Observe per-step state snapshots via `stream.values`
+- Detect interrupts via `stream.interrupted` and read their payloads from `stream.interrupts`
+- Resume execution by calling `stream_events` again with `Command(resume=...)` and repeat until `stream.interrupted` is false
:::python
-```python
-async for chunk in graph.astream(
- initial_input,
- stream_mode=["messages", "updates"],
- subgraphs=True,
- config=config,
- version="v2",
-):
- if chunk["type"] == "messages":
- # Handle streaming message content
- msg, _ = chunk["data"]
- if isinstance(msg, AIMessageChunk) and msg.content:
- display_streaming_content(msg.content)
-
- elif chunk["type"] == "updates":
- # Check for interrupts in the updates data
- if "__interrupt__" in chunk["data"]:
- interrupt_info = chunk["data"]["__interrupt__"][0].value
- user_response = get_user_input(interrupt_info)
- initial_input = Command(resume=user_response)
- break
- else:
- current_node = list(chunk["data"].keys())[0]
-```
+
:::python
- ```python
- from typing import Literal, Optional, TypedDict
-
- from langgraph.checkpoint.memory import MemorySaver
- from langgraph.graph import StateGraph, START, END
- from langgraph.types import Command, interrupt
-
-
- class ApprovalState(TypedDict):
- action_details: str
- status: Optional[Literal["pending", "approved", "rejected"]]
-
-
- def approval_node(state: ApprovalState) -> Command[Literal["proceed", "cancel"]]:
- # Expose details so the caller can render them in a UI
- decision = interrupt({
- "question": "Approve this action?",
- "details": state["action_details"],
- })
-
- # Route to the appropriate node after resume
- return Command(goto="proceed" if decision else "cancel")
-
-
- def proceed_node(state: ApprovalState):
- return {"status": "approved"}
-
-
- def cancel_node(state: ApprovalState):
- return {"status": "rejected"}
-
-
- builder = StateGraph(ApprovalState)
- builder.add_node("approval", approval_node)
- builder.add_node("proceed", proceed_node)
- builder.add_node("cancel", cancel_node)
- builder.add_edge(START, "approval")
- builder.add_edge("proceed", END)
- builder.add_edge("cancel", END)
-
- # Use a more durable checkpointer in production
- checkpointer = MemorySaver()
- graph = builder.compile(checkpointer=checkpointer)
-
- config = {"configurable": {"thread_id": "approval-123"}}
- initial = graph.invoke(
- {"action_details": "Transfer $500", "status": "pending"},
- config=config,
- )
- print(initial["__interrupt__"]) # -> [Interrupt(value={'question': ..., 'details': ...})]
+
:::python
- ```python
- import sqlite3
- from typing import TypedDict
-
- from langgraph.checkpoint.memory import MemorySaver
- from langgraph.graph import StateGraph, START, END
- from langgraph.types import Command, interrupt
-
-
- class ReviewState(TypedDict):
- generated_text: str
-
-
- def review_node(state: ReviewState):
- # Ask a reviewer to edit the generated content
- updated = interrupt({
- "instruction": "Review and edit this content",
- "content": state["generated_text"],
- })
- return {"generated_text": updated}
-
-
- builder = StateGraph(ReviewState)
- builder.add_node("review", review_node)
- builder.add_edge(START, "review")
- builder.add_edge("review", END)
-
- checkpointer = MemorySaver()
- graph = builder.compile(checkpointer=checkpointer)
-
- config = {"configurable": {"thread_id": "review-42"}}
- initial = graph.invoke({"generated_text": "Initial draft"}, config=config)
- print(initial["__interrupt__"]) # -> [Interrupt(value={'instruction': ..., 'content': ...})]
+
+
+**Avoid `while True` + `interrupt()` loops inside a single node.** Because the node re-runs from the beginning on every resume (see [Rules of interrupts](#rules-of-interrupts)), a loop that calls `interrupt()` multiple times causes each resume to replay all previous iterations: the first resume replays 1 iteration, the second replays 2, and so on. The result is exponential re-execution of any code inside the loop body.
+
+
:::python
-```python
-from langgraph.types import interrupt
+The correct pattern:
-def get_age_node(state: State):
- prompt = "What is your age?"
+1. Store the re-prompt question in state (e.g. `pending_question`).
+2. In the node, call `interrupt()` **exactly once**, passing the current question from state.
+3. If the answer is invalid, return the updated `pending_question` so the next invocation re-prompts.
+4. Use `add_conditional_edges` to route back to the node until a valid value is collected.
- while True:
- answer = interrupt(prompt) # payload surfaces in result["__interrupt__"]
+
:::python
- ```python
- import sqlite3
- from typing import TypedDict
-
- from langgraph.checkpoint.sqlite import SqliteSaver
- from langgraph.graph import StateGraph, START, END
- from langgraph.types import Command, interrupt
-
+
@@ -1778,7 +1572,7 @@ To debug and test a graph, you can use static interrupts as breakpoints to step
-To debug your interrupts, use [LangSmith](/langsmith/home).
+To debug your interrupts, use [LangSmith](/langsmith/observability).
### Using LangSmith Studio
diff --git a/local-server.mdx b/local-server.mdx
index 4d9d3b8..7a6e7c2 100644
--- a/local-server.mdx
+++ b/local-server.mdx
@@ -4,7 +4,6 @@ sidebarTitle: Local server
---
-
This guide shows you how to run a LangGraph application locally.
## Prerequisites
@@ -321,7 +320,7 @@ https://smith.langchain.com/studio/?baseUrl=http://myhost:3000
Now that you have a LangGraph app running locally, take your journey further by exploring deployment and advanced features:
* [Deployment quickstart](/langsmith/deployment-quickstart): Deploy your LangGraph app using LangSmith.
-* [LangSmith](/langsmith/home): Learn about foundational LangSmith concepts.
+* [LangSmith](/langsmith/observability): Learn about foundational LangSmith concepts.
:::python
* [SDK Reference](https://reference.langchain.com/python/langsmith/deployment/sdk/): Explore the SDK API Reference.
diff --git a/memory.mdx b/memory.mdx
deleted file mode 100644
index ac44a23..0000000
--- a/memory.mdx
+++ /dev/null
@@ -1,274 +0,0 @@
----
-title: Memory overview
----
-
-
-
-[Memory](/oss/langgraph/add-memory) is a system that remembers information about previous interactions. For AI agents, memory is crucial because it lets them remember previous interactions, learn from feedback, and adapt to user preferences. As agents tackle more complex tasks with numerous user interactions, this capability becomes essential for both efficiency and user satisfaction.
-
-This conceptual guide covers two types of memory, based on their recall scope:
-
-* [Short-term memory](#short-term-memory), or [thread](/oss/langgraph/persistence#threads)-scoped memory, tracks the ongoing conversation by maintaining message history within a session. LangGraph manages short-term memory as a part of your agent's [state](/oss/langgraph/graph-api#state). State is persisted to a database using a [checkpointer](/oss/langgraph/persistence#checkpoints) so the thread can be resumed at any time. Short-term memory updates when the graph is invoked or a step is completed, and the State is read at the start of each step.
-* [Long-term memory](#long-term-memory) stores user-specific or application-level data across sessions and is shared _across_ conversational threads. It can be recalled _at any time_ and _in any thread_. Memories are scoped to any custom namespace, not just within a single thread ID. LangGraph provides [stores](/oss/langgraph/persistence#memory-store) ([reference doc](https://langchain-ai.github.io/langgraph/reference/store/#langgraph.store.base.BaseStore)) to let you save and recall long-term memories.
-
-
-
-## Short-term memory
-
-[Short-term memory](/oss/langgraph/add-memory#add-short-term-memory) lets your application remember previous interactions within a single [thread](/oss/langgraph/persistence#threads) or conversation. A [thread](/oss/langgraph/persistence#threads) organizes multiple interactions in a session, similar to the way email groups messages in a single conversation.
-
-LangGraph manages short-term memory as part of the agent's state, persisted via thread-scoped checkpoints. This state can normally include the conversation history along with other stateful data, such as uploaded files, retrieved documents, or generated artifacts. By storing these in the graph's state, the bot can access the full context for a given conversation while maintaining separation between different threads.
-
-### Manage short-term memory
-
-Conversation history is the most common form of short-term memory, and long conversations pose a challenge to today's LLMs. A full history may not fit inside an LLM's context window, resulting in an irrecoverable error. Even if your LLM supports the full context length, most LLMs still perform poorly over long contexts. They get "distracted" by stale or off-topic content, all while suffering from slower response times and higher costs.
-
-Chat models accept context using messages, which include developer provided instructions (a system message) and user inputs (human messages). In chat applications, messages alternate between human inputs and model responses, resulting in a list of messages that grows longer over time. Because context windows are limited and token-rich message lists can be costly, many applications can benefit from using techniques to manually remove or forget stale information.
-
-
-
-For more information on common techniques for managing messages, see the [Add and manage memory](/oss/langgraph/add-memory#manage-short-term-memory) guide.
-
-## Long-term memory
-
-[Long-term memory](/oss/langgraph/add-memory#add-long-term-memory) in LangGraph allows systems to retain information across different conversations or sessions. Unlike short-term memory, which is **thread-scoped**, long-term memory is saved within custom "namespaces."
-
-Long-term memory is a complex challenge without a one-size-fits-all solution. However, the following questions provide a framework to help you navigate the different techniques:
-
-* What is the type of memory? Humans use memories to remember facts ([semantic memory](#semantic-memory)), experiences ([episodic memory](#episodic-memory)), and rules ([procedural memory](#procedural-memory)). AI agents can use memory in the same ways. For example, AI agents can use memory to remember specific facts about a user to accomplish a task.
-* [When do you want to update memories?](#writing-memories) Memory can be updated as part of an agent's application logic (e.g., "on the hot path"). In this case, the agent typically decides to remember facts before responding to a user. Alternatively, memory can be updated as a background task (logic that runs in the background / asynchronously and generates memories). We explain the tradeoffs between these approaches in the [section below](#writing-memories).
-
-Different applications require various types of memory. Although the analogy isn't perfect, examining [human memory types](https://www.psychologytoday.com/us/basics/memory/types-of-memory?ref=blog.langchain.dev) can be insightful. Some research (e.g., the [CoALA paper](https://arxiv.org/pdf/2309.02427)) have even mapped these human memory types to those used in AI agents.
-
-| Memory Type | What is Stored | Human Example | Agent Example |
-|-------------|----------------|---------------|---------------|
-| [Semantic](#semantic-memory) | Facts | Things I learned in school | Facts about a user |
-| [Episodic](#episodic-memory) | Experiences | Things I did | Past agent actions |
-| [Procedural](#procedural-memory) | Instructions | Instincts or motor skills | Agent system prompt |
-
-### Semantic memory
-
-[Semantic memory](https://en.wikipedia.org/wiki/Semantic_memory), both in humans and AI agents, involves the retention of specific facts and concepts. In humans, it can include information learned in school and the understanding of concepts and their relationships. For AI agents, semantic memory is often used to personalize applications by remembering facts or concepts from past interactions.
-
-
-Semantic memory is different from "semantic search," which is a technique for finding similar content using "meaning" (usually as embeddings). Semantic memory is a term from psychology, referring to storing facts and knowledge, while semantic search is a method for retrieving information based on meaning rather than exact matches.
-
-
-#### Profile
-
-Semantic memories can be managed in different ways. For example, memories can be a single, continuously updated "profile" of well-scoped and specific information about a user, organization, or other entity (including the agent itself). A profile is generally just a JSON document with various key-value pairs you've selected to represent your domain.
-
-When remembering a profile, you will want to make sure that you are **updating** the profile each time. As a result, you will want to pass in the previous profile and [ask the model to generate a new profile](https://github.com/langchain-ai/memory-template) (or some [JSON patch](https://github.com/hinthornw/trustcall) to apply to the old profile). This can be become error-prone as the profile gets larger, and may benefit from splitting a profile into multiple documents or **strict** decoding when generating documents to ensure the memory schemas remains valid.
-
-
-
-#### Collection
-
-Alternatively, memories can be a collection of documents that are continuously updated and extended over time. Each individual memory can be more narrowly scoped and easier to generate, which means that you're less likely to **lose** information over time. It's easier for an LLM to generate _new_ objects for new information than reconcile new information with an existing profile. As a result, a document collection tends to lead to [higher recall downstream](https://en.wikipedia.org/wiki/Precision_and_recall).
-
-However, this shifts some complexity memory updating. The model must now _delete_ or _update_ existing items in the list, which can be tricky. In addition, some models may default to over-inserting and others may default to over-updating. See the [Trustcall](https://github.com/hinthornw/trustcall) package for one way to manage this and consider evaluation (e.g., with a tool like [LangSmith](/langsmith/evaluate-chatbot-tutorial)) to help you tune the behavior.
-
-Working with document collections also shifts complexity to memory **search** over the list. The `Store` currently supports both [semantic search](https://langchain-ai.github.io/langgraph/reference/store/#langgraph.store.base.SearchOp.query) and [filtering by content](https://langchain-ai.github.io/langgraph/reference/store/#langgraph.store.base.SearchOp.filter).
-
-Finally, using a collection of memories can make it challenging to provide comprehensive context to the model. While individual memories may follow a specific schema, this structure might not capture the full context or relationships between memories. As a result, when using these memories to generate responses, the model may lack important contextual information that would be more readily available in a unified profile approach.
-
-
-
-Regardless of memory management approach, the central point is that the agent will use the semantic memories to [ground its responses](https://python.langchain.com/docs/concepts/rag/), which often leads to more personalized and relevant interactions.
-
-### Episodic memory
-
-[Episodic memory](https://en.wikipedia.org/wiki/Episodic_memory), in both humans and AI agents, involves recalling past events or actions. The [CoALA paper](https://arxiv.org/pdf/2309.02427) frames this well: facts can be written to semantic memory, whereas *experiences* can be written to episodic memory. For AI agents, episodic memory is often used to help an agent remember how to accomplish a task.
-
-:::python
-In practice, episodic memories are often implemented through [few-shot example prompting](/langsmith/create-few-shot-evaluators), where agents learn from past sequences to perform tasks correctly. Sometimes it's easier to "show" than "tell" and LLMs learn well from examples. Few-shot learning lets you ["program"](https://x.com/karpathy/status/1627366413840322562) your LLM by updating the prompt with input-output examples to illustrate the intended behavior. While various [best-practices](https://python.langchain.com/docs/concepts/#1-generating-examples) can be used to generate few-shot examples, often the challenge lies in selecting the most relevant examples based on user input.
-:::
-
-:::js
-In practice, episodic memories are often implemented through few-shot example prompting, where agents learn from past sequences to perform tasks correctly. Sometimes it's easier to "show" than "tell" and LLMs learn well from examples. Few-shot learning lets you ["program"](https://x.com/karpathy/status/1627366413840322562) your LLM by updating the prompt with input-output examples to illustrate the intended behavior. While various best-practices can be used to generate few-shot examples, often the challenge lies in selecting the most relevant examples based on user input.
-:::
-
-:::python
-Note that the memory [store](/oss/langgraph/persistence#memory-store) is just one way to store data as few-shot examples. If you want to have more developer involvement, or tie few-shots more closely to your evaluation harness, you can also use a [LangSmith Dataset](/langsmith/manage-datasets) to store your data and implement your own retrieval logic to select the most relevant examples based on user input.
-
-See this [blog post](https://blog.langchain.dev/few-shot-prompting-to-improve-tool-calling-performance/) showcasing few-shot prompting to improve tool calling performance and this [blog post](https://blog.langchain.dev/aligning-llm-as-a-judge-with-human-preferences/) using few-shot examples to align an LLM to human preferences.
-:::
-
-:::js
-Note that the memory [store](/oss/langgraph/persistence#memory-store) is just one way to store data as few-shot examples. If you want to have more developer involvement, or tie few-shots more closely to your evaluation harness, you can also use a LangSmith Dataset to store your data and implement your own retrieval logic to select the most relevant examples based on user input.
-
-See this [blog post](https://blog.langchain.dev/few-shot-prompting-to-improve-tool-calling-performance/) showcasing few-shot prompting to improve tool calling performance and this [blog post](https://blog.langchain.dev/aligning-llm-as-a-judge-with-human-preferences/) using few-shot examples to align an LLM to human preferences.
-:::
-
-### Procedural memory
-
-[Procedural memory](https://en.wikipedia.org/wiki/Procedural_memory), in both humans and AI agents, involves remembering the rules used to perform tasks. In humans, procedural memory is like the internalized knowledge of how to perform tasks, such as riding a bike via basic motor skills and balance. Episodic memory, on the other hand, involves recalling specific experiences, such as the first time you successfully rode a bike without training wheels or a memorable bike ride through a scenic route. For AI agents, procedural memory is a combination of model weights, agent code, and agent's prompt that collectively determine the agent's functionality.
-
-In practice, it is fairly uncommon for agents to modify their model weights or rewrite their code. However, it is more common for agents to modify their own prompts.
-
-One effective approach to refining an agent's instructions is through ["Reflection"](https://blog.langchain.dev/reflection-agents/) or meta-prompting. This involves prompting the agent with its current instructions (e.g., the system prompt) along with recent conversations or explicit user feedback. The agent then refines its own instructions based on this input. This method is particularly useful for tasks where instructions are challenging to specify upfront, as it allows the agent to learn and adapt from its interactions.
-
-For example, we built a [Tweet generator](https://www.youtube.com/watch?v=Vn8A3BxfplE) using external feedback and prompt re-writing to produce high-quality paper summaries for Twitter. In this case, the specific summarization prompt was difficult to specify *a priori*, but it was fairly easy for a user to critique the generated Tweets and provide feedback on how to improve the summarization process.
-
-The below pseudo-code shows how you might implement this with the LangGraph memory [store](/oss/langgraph/persistence#memory-store), using the store to save a prompt, the `update_instructions` node to get the current prompt (as well as feedback from the conversation with the user captured in `state["messages"]`), update the prompt, and save the new prompt back to the store. Then, the `call_model` get the updated prompt from the store and uses it to generate a response.
-
-:::python
-```python
-# Node that *uses* the instructions
-def call_model(state: State, store: BaseStore):
- namespace = ("agent_instructions", )
- instructions = store.get(namespace, key="agent_a")[0]
- # Application logic
- prompt = prompt_template.format(instructions=instructions.value["instructions"])
- ...
-
-# Node that updates instructions
-def update_instructions(state: State, store: BaseStore):
- namespace = ("instructions",)
- instructions = store.search(namespace)[0]
- # Memory logic
- prompt = prompt_template.format(instructions=instructions.value["instructions"], conversation=state["messages"])
- output = llm.invoke(prompt)
- new_instructions = output['new_instructions']
- store.put(("agent_instructions",), "agent_a", {"instructions": new_instructions})
- ...
-```
-:::
-
-:::js
-```typescript
-// Node that *uses* the instructions
-const callModel: GraphNode = async (state, config) => {
- const namespace = ["agent_instructions"];
- const instructions = await config.store?.get(namespace, "agent_a");
- // Application logic
- const prompt = promptTemplate.format({
- instructions: instructions[0].value.instructions
- });
- // ...
-};
-
-// Node that updates instructions
-const updateInstructions: GraphNode = async (state, config) => {
- const namespace = ["instructions"];
- const currentInstructions = await config.store?.search(namespace);
- // Memory logic
- const prompt = promptTemplate.format({
- instructions: currentInstructions[0].value.instructions,
- conversation: state.messages
- });
- const output = await llm.invoke(prompt);
- const newInstructions = output.new_instructions;
- await store.put(["agent_instructions"], "agent_a", {
- instructions: newInstructions
- });
- // ...
-};
-```
-:::
-
-
-
-### Writing memories
-
-There are two primary methods for agents to write memories: ["in the hot path"](#in-the-hot-path) and ["in the background"](#in-the-background).
-
-
-
-#### In the hot path
-
-Creating memories during runtime offers both advantages and challenges. On the positive side, this approach allows for real-time updates, making new memories immediately available for use in subsequent interactions. It also enables transparency, as users can be notified when memories are created and stored.
-
-However, this method also presents challenges. It may increase complexity if the agent requires a new tool to decide what to commit to memory. In addition, the process of reasoning about what to save to memory can impact agent latency. Finally, the agent must multitask between memory creation and its other responsibilities, potentially affecting the quantity and quality of memories created.
-
-As an example, ChatGPT uses a [save_memories](https://openai.com/index/memory-and-new-controls-for-chatgpt/) tool to upsert memories as content strings, deciding whether and how to use this tool with each user message. See our [memory-agent](https://github.com/langchain-ai/memory-agent) template as an reference implementation.
-
-#### In the background
-
-Creating memories as a separate background task offers several advantages. It eliminates latency in the primary application, separates application logic from memory management, and allows for more focused task completion by the agent. This approach also provides flexibility in timing memory creation to avoid redundant work.
-
-However, this method has its own challenges. Determining the frequency of memory writing becomes crucial, as infrequent updates may leave other threads without new context. Deciding when to trigger memory formation is also important. Common strategies include scheduling after a set time period (with rescheduling if new events occur), using a cron schedule, or allowing manual triggers by users or the application logic.
-
-See our [memory-service](https://github.com/langchain-ai/memory-template) template as an reference implementation.
-
-### Memory storage
-
-LangGraph stores long-term memories as JSON documents in a [store](/oss/langgraph/persistence#memory-store). Each memory is organized under a custom `namespace` (similar to a folder) and a distinct `key` (like a file name). Namespaces often include user or org IDs or other labels that makes it easier to organize information. This structure enables hierarchical organization of memories. Cross-namespace searching is then supported through content filters.
-
-:::python
-```python
-from langgraph.store.memory import InMemoryStore
-
-
-def embed(texts: list[str]) -> list[list[float]]:
- # Replace with an actual embedding function or LangChain embeddings object
- return [[1.0, 2.0] * len(texts)]
-
-
-# InMemoryStore saves data to an in-memory dictionary. Use a DB-backed store in production use.
-store = InMemoryStore(index={"embed": embed, "dims": 2})
-user_id = "my-user"
-application_context = "chitchat"
-namespace = (user_id, application_context)
-store.put(
- namespace,
- "a-memory",
- {
- "rules": [
- "User likes short, direct language",
- "User only speaks English & python",
- ],
- "my-key": "my-value",
- },
-)
-# get the "memory" by ID
-item = store.get(namespace, "a-memory")
-# search for "memories" within this namespace, filtering on content equivalence, sorted by vector similarity
-items = store.search(
- namespace, filter={"my-key": "my-value"}, query="language preferences"
-)
-```
-:::
-
-:::js
-```typescript
-import { InMemoryStore } from "@langchain/langgraph";
-
-const embed = (texts: string[]): number[][] => {
- // Replace with an actual embedding function or LangChain embeddings object
- return texts.map(() => [1.0, 2.0]);
-};
-
-// InMemoryStore saves data to an in-memory dictionary. Use a DB-backed store in production use.
-const store = new InMemoryStore({ index: { embed, dims: 2 } });
-const userId = "my-user";
-const applicationContext = "chitchat";
-const namespace = [userId, applicationContext];
-
-await store.put(
- namespace,
- "a-memory",
- {
- rules: [
- "User likes short, direct language",
- "User only speaks English & TypeScript",
- ],
- "my-key": "my-value",
- }
-);
-
-// get the "memory" by ID
-const item = await store.get(namespace, "a-memory");
-
-// search for "memories" within this namespace, filtering on content equivalence, sorted by vector similarity
-const items = await store.search(
- namespace,
- {
- filter: { "my-key": "my-value" },
- query: "language preferences"
- }
-);
-```
-:::
-
-For more information about the memory store, see the [Persistence](/oss/langgraph/persistence#memory-store) guide.
diff --git a/observability.mdx b/observability.mdx
index 58f7c6c..1a7dd92 100644
--- a/observability.mdx
+++ b/observability.mdx
@@ -2,7 +2,7 @@
title: LangSmith Observability
---
-Traces are a series of steps that your application takes to go from input to output. Each of these individual steps is represented by a run. You can use [LangSmith](https://smith.langchain.com/) to visualize these execution steps. To use it, [enable tracing for your application](/langsmith/trace-with-langgraph). This enables you to do the following:
+Traces are a series of steps that your application takes to go from input to output. Each of these individual steps is represented by a run. You can use [LangSmith](https://smith.langchain.com) to visualize these execution steps. To use it, [enable tracing for your application](/langsmith/trace-with-langgraph). This enables you to do the following:
* [Debug a locally running application](/langsmith/observability-studio#debug-langsmith-traces).
* [Evaluate the application performance](/oss/langchain/test/evals).
@@ -13,13 +13,13 @@ Traces are a series of steps that your application takes to go from input to out
Before you begin, ensure you have the following:
- **A LangSmith account**: Sign up (for free) or log in at [smith.langchain.com](https://smith.langchain.com).
-- **A LangSmith API key**: Follow the [Create an API key](/langsmith/create-account-api-key#create-an-api-key) guide.
+- **A LangSmith API key**: Follow the [Create an API key](/langsmith/create-account-api-key) guide.
## Enable tracing
To enable tracing for your application, set the following environment variables:
-```bash
+```python
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=
```
@@ -150,7 +150,7 @@ await agent.invoke(
{
messages: [{role: "user", content: "Send a test email to alice@example.com"}]
},
- {
+ config: {
tags: ["production", "email-assistant", "v1.0"],
metadata: {
userId: "user123",
@@ -167,7 +167,7 @@ This custom metadata and tags will be attached to the trace in LangSmith.
-To learn more about how to use traces to debug, evaluate, and monitor your agents, see the [LangSmith documentation](/langsmith/home).
+To learn more about how to use traces to debug, evaluate, and monitor your agents, see the [LangSmith documentation](/langsmith/observability).
diff --git a/overview.mdx b/overview.mdx
index eae819a..3efe6ed 100644
--- a/overview.mdx
+++ b/overview.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Overview
description: Gain control with LangGraph to design agents that reliably handle complex tasks
---
-Trusted by companies shaping the future of agents-- including Klarna, Uber, J.P. Morgan, and more-- LangGraph is a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents.
+Trusted by companies shaping the future of agents—including Klarna, Uber, J.P. Morgan, and more—LangGraph is a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents. LangGraph gives you fine-grained control to mix deterministic, hand-coded steps with LLM-driven agentic steps in the same graph, so you can build bespoke agents that behave exactly the way your application requires.
LangGraph is very low-level, and focused entirely on agent **orchestration**. Before using LangGraph, we recommend you familiarize yourself with some of the components used to build agents, starting with [models](/oss/langchain/models) and [tools](/oss/langchain/tools).
@@ -12,6 +12,20 @@ We will commonly use [LangChain](/oss/langchain/overview) components throughout
LangGraph is focused on the underlying capabilities important for agent orchestration: durable execution, streaming, human-in-the-loop, and more.
+One of LangGraph's core strengths is the ability to mix deterministic steps with LLM-driven agentic steps in a single graph. This lets you build bespoke workflows where parts of the logic are fully predictable and auditable while other parts are flexible and model-driven, giving you fine-grained control over exactly where and how AI is applied.
+
+
+
+- [Deep Agents](/oss/deepagents/overview) is an [agent harness](/oss/concepts/products#agent-harnesses-like-the-deep-agents-sdk): planning, subagents, filesystem tools, and context management on top of LangGraph.
+- [LangChain](/oss/langchain/overview) is the agent framework: abstractions and integrations for models, tools, and agent loops.
+- [LangGraph](/oss/langgraph/overview) is the orchestration runtime: durable execution, streaming, human-in-the-loop, and persistence.
+- [LangSmith](/langsmith/observability) is the platform for tracing, evaluation, prompts, and deployment across frameworks.
+- [LangSmith Engine](/langsmith/engine) detects issues in your LangGraph agent traces and proposes fixes. You can open a pull request with the proposed fix directly from the Engine tab.
+- [LangSmith Fleet](/langsmith/fleet/index) is the no-code agent builder for templates, integrations, and routine automation.
+
+Read [Frameworks, runtimes, and harnesses](/oss/concepts/products) for a comparison of the open source stack.
+
+
##
-Use [LangSmith](/langsmith/home) to trace requests, debug agent behavior, and evaluate outputs. Set `LANGSMITH_TRACING=true` and your API key to get started.
+Use [LangSmith](/langsmith/observability) to trace requests, debug agent behavior, and evaluate outputs. Set `LANGSMITH_TRACING=true` and your API key to get started. Follow the [tracing quickstart](/langsmith/trace-with-langchain) to get set up. We recommend you also set up [LangSmith Engine](/langsmith/engine) which monitors your traces, detects issues, and proposes fixes.
## Core benefits
LangGraph provides low-level supporting infrastructure for *any* long-running, stateful workflow or agent. LangGraph does not abstract prompts or architecture, and provides the following central benefits:
-* [Durable execution](/oss/langgraph/durable-execution): Build agents that persist through failures and can run for extended periods, resuming from where they left off.
+* **Mix deterministic and agentic steps**: Combine hand-coded, deterministic logic with LLM-driven decision-making in a single graph. Use deterministic steps where you need reliability and predictability, and agentic steps where you need flexibility—giving you precise control over every part of your agent's behavior.
+* [Persistence](/oss/langgraph/persistence): Build agents that persist through failures and can run for extended periods, resuming from where they left off.
* [Human-in-the-loop](/oss/langgraph/interrupts): Incorporate human oversight by inspecting and modifying agent state at any point.
* [Comprehensive memory](/oss/concepts/memory): Create stateful agents with both short-term working memory for ongoing reasoning and long-term memory across sessions.
-* [Debugging with LangSmith](/langsmith/home): Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics.
+* [Debugging with LangSmith](/langsmith/observability): Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics.
* [Production-ready deployment](/langsmith/deployment): Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows.
## LangGraph ecosystem
diff --git a/persistence.mdx b/persistence.mdx
index 8fd752d..d2839b6 100644
--- a/persistence.mdx
+++ b/persistence.mdx
@@ -1,1172 +1,126 @@
---
title: Persistence
+description: LangGraph's persistence layer gives agents short-term memory through checkpointers and long-term memory through stores.
---
+{/* Anchor stubs for backwards-compatible deep links */}
+
+
+
+
+
+
+Persistence lets LangGraph applications keep useful information beyond a single graph run. It matters when an agent needs to continue a conversation, resume after an interruption, recover from a failure, or remember information across interactions.
-LangGraph has a built-in persistence layer that saves graph state as checkpoints. When you compile a graph with a checkpointer, a snapshot of the graph state is saved at every step of execution, organized into threads. This enables human-in-the-loop workflows, conversational memory, time travel debugging, and fault-tolerant execution.
+LangGraph provides two complementary persistence systems:
-
+- **[Checkpointers](/oss/langgraph/checkpointers)** persist a thread's graph state as checkpoints. Use them for short-term, thread-scoped memory, including conversation continuity, human-in-the-loop workflows, time travel, and fault tolerance.
+- **[Stores](/oss/langgraph/stores)** persist application-defined data outside the graph state. Use them for long-term, cross-thread memory, including user preferences, facts, and shared knowledge.
-
-**Agent Server handles checkpointing automatically**
-When using the [Agent Server](/langsmith/agent-server), you don't need to implement or configure checkpointers manually. The server handles all persistence infrastructure for you behind the scenes.
-
-
-## Why use persistence
-
-Persistence is required for the following features:
-
-- **Human-in-the-loop**: Checkpointers facilitate [human-in-the-loop workflows](/oss/langgraph/interrupts) by allowing humans to inspect, interrupt, and approve graph steps. Checkpointers are needed for these workflows as the person has to be able to view the state of a graph at any point in time, and the graph has to be able to resume execution after the person has made any updates to the state. See [Interrupts](/oss/langgraph/interrupts) for examples.
-- **Memory**: Checkpointers allow for ["memory"](/oss/concepts/memory) between interactions. In the case of repeated human interactions (like conversations) any follow up messages can be sent to that thread, which will retain its memory of previous ones. See [Add memory](/oss/langgraph/add-memory) for information on how to add and manage conversation memory using checkpointers.
-- **Time travel**: Checkpointers allow for ["time travel"](/oss/langgraph/use-time-travel), allowing users to replay prior graph executions to review and / or debug specific graph steps. In addition, checkpointers make it possible to fork the graph state at arbitrary checkpoints to explore alternative trajectories.
-- **Fault-tolerance**: Checkpointing provides fault-tolerance and error recovery: if one or more nodes fail at a given superstep, you can restart your graph from the last successful step.
-
-- **Pending writes**: When a graph node fails mid-execution at a given [super-step](#super-steps), LangGraph stores pending checkpoint writes from any other nodes that completed successfully at that super-step. When you resume graph execution from that super-step you don't re-run the successful nodes.
-
-## Core concepts
-
-### Threads
-
-A thread is a unique ID or thread identifier assigned to each checkpoint saved by a checkpointer. It contains the accumulated state of a sequence of [runs](/langsmith/runs). When a run is executed, the [state](/oss/langgraph/graph-api#state) of the underlying graph of the assistant will be persisted to the thread.
-
-When invoking a graph with a checkpointer, you **must** specify a `thread_id` as part of the `configurable` portion of the config:
-
-:::python
-```python
-{"configurable": {"thread_id": "1"}}
-```
-:::
-
-:::js
-```typescript
-{
- configurable: {
- thread_id: "1";
- }
-}
-```
-:::
-
-A thread's current and historical state can be retrieved. To persist state, a thread must be created prior to executing a run. The LangSmith API provides several endpoints for creating and managing threads and thread state. See the [API reference](https://reference.langchain.com/python/langsmith/) for more details.
+Most applications can use both: a [checkpointer](/oss/langgraph/checkpointers) tracks the current thread, and a [store](/oss/langgraph/stores) tracks durable information across threads.
-The checkpointer uses `thread_id` as the primary key for storing and retrieving checkpoints. Without it, the checkpointer cannot save state or resume execution after an [interrupt](/oss/langgraph/interrupts), since the checkpointer uses `thread_id` to load the saved state.
+## Quickstart
-### Checkpoints
-
-The state of a thread at a particular point in time is called a checkpoint. A checkpoint is a snapshot of the graph state saved at each [super-step](#super-steps) and is represented by a `StateSnapshot` object (see [StateSnapshot fields](#statesnapshot-fields) for the full field reference).
-
-#### Super-steps
-
-LangGraph created a checkpoint at each **super-step** boundary. A super-step is a single "tick" of the graph where all nodes scheduled for that step execute (potentially in parallel). For a sequential graph like `START -> A -> B -> END`, there are separate super-steps for the input, node A, and node B — producing a checkpoint after each one. Understanding super-step boundaries is important for [time travel](/oss/langgraph/use-time-travel), because you can only resume execution from a checkpoint (i.e., a super-step boundary).
-
-Checkpoints are persisted and can be used to restore the state of a thread at a later time.
-
-Let's see what checkpoints are saved when a simple graph is invoked as follows:
+Compile your graph with a checkpointer, a store, or both:
:::python
```python
-from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
-from langchain_core.runnables import RunnableConfig
-from typing import Annotated
-from typing_extensions import TypedDict
-from operator import add
-
-class State(TypedDict):
- foo: str
- bar: Annotated[list[str], add]
-
-def node_a(state: State):
- return {"foo": "a", "bar": ["a"]}
-
-def node_b(state: State):
- return {"foo": "b", "bar": ["b"]}
-
-
-workflow = StateGraph(State)
-workflow.add_node(node_a)
-workflow.add_node(node_b)
-workflow.add_edge(START, "node_a")
-workflow.add_edge("node_a", "node_b")
-workflow.add_edge("node_b", END)
+from langgraph.store.memory import InMemoryStore
checkpointer = InMemorySaver()
-graph = workflow.compile(checkpointer=checkpointer)
-
-config: RunnableConfig = {"configurable": {"thread_id": "1"}}
-graph.invoke({"foo": "", "bar":[]}, config)
-```
-:::
-
-:::js
-```typescript
-import { StateGraph, StateSchema, ReducedValue, START, END, MemorySaver } from "@langchain/langgraph";
-import { z } from "zod/v4";
-
-const State = new StateSchema({
- foo: z.string(),
- bar: new ReducedValue(
- z.array(z.string()).default(() => []),
- {
- inputSchema: z.array(z.string()),
- reducer: (x, y) => x.concat(y),
- }
- ),
-});
-
-const workflow = new StateGraph(State)
- .addNode("nodeA", (state) => {
- return { foo: "a", bar: ["a"] };
- })
- .addNode("nodeB", (state) => {
- return { foo: "b", bar: ["b"] };
- })
- .addEdge(START, "nodeA")
- .addEdge("nodeA", "nodeB")
- .addEdge("nodeB", END);
-
-const checkpointer = new MemorySaver();
-const graph = workflow.compile({ checkpointer });
-
-const config = { configurable: { thread_id: "1" } };
-await graph.invoke({ foo: "", bar: [] }, config);
-```
-:::
-
-:::python
-After we run the graph, we expect to see exactly 4 checkpoints:
-
-* Empty checkpoint with @[`START`] as the next node to be executed
-* Checkpoint with the user input `{'foo': '', 'bar': []}` and `node_a` as the next node to be executed
-* Checkpoint with the outputs of `node_a` `{'foo': 'a', 'bar': ['a']}` and `node_b` as the next node to be executed
-* Checkpoint with the outputs of `node_b` `{'foo': 'b', 'bar': ['a', 'b']}` and no next nodes to be executed
-
-Note that we `bar` channel values contain outputs from both nodes as we have a reducer for `bar` channel.
-:::
-
-:::js
-After we run the graph, we expect to see exactly 4 checkpoints:
-
-* Empty checkpoint with @[`START`] as the next node to be executed
-* Checkpoint with the user input `{'foo': '', 'bar': []}` and `nodeA` as the next node to be executed
-* Checkpoint with the outputs of `nodeA` `{'foo': 'a', 'bar': ['a']}` and `nodeB` as the next node to be executed
-* Checkpoint with the outputs of `nodeB` `{'foo': 'b', 'bar': ['a', 'b']}` and no next nodes to be executed
-
-Note that the `bar` channel values contain outputs from both nodes as we have a reducer for the `bar` channel.
-:::
-
-#### Checkpoint namespace
-
-Each checkpoint has a `checkpoint_ns` (checkpoint namespace) field that identifies which graph or subgraph it belongs to:
-
-- **`""`** (empty string): The checkpoint belongs to the parent (root) graph.
-- **`"node_name:uuid"`**: The checkpoint belongs to a subgraph invoked as the given node. For nested subgraphs, namespaces are joined with `|` separators (e.g., `"outer_node:uuid|inner_node:uuid"`).
-
-You can access the checkpoint namespace from within a node via the config:
-
-:::python
-```python
-from langchain_core.runnables import RunnableConfig
-
-def my_node(state: State, config: RunnableConfig):
- checkpoint_ns = config["configurable"]["checkpoint_ns"]
- # "" for the parent graph, "node_name:uuid" for a subgraph
-```
-:::
-
-:::js
-```typescript
-import { RunnableConfig } from "@langchain/core/runnables";
-
-function myNode(state: typeof State.Type, config: RunnableConfig) {
- const checkpointNs = config.configurable?.checkpoint_ns;
- // "" for the parent graph, "node_name:uuid" for a subgraph
-}
-```
-:::
-
-See [Subgraphs](/oss/langgraph/use-subgraphs) for more details on working with subgraph state and checkpoints.
-
-## Get and update state
-
-### Get state
-
-:::python
-When interacting with the saved graph state, you **must** specify a [thread identifier](#threads). You can view the _latest_ state of the graph by calling `graph.get_state(config)`. This will return a `StateSnapshot` object that corresponds to the latest checkpoint associated with the thread ID provided in the config or a checkpoint associated with a checkpoint ID for the thread, if provided.
-
-```python
-# get the latest state snapshot
-config = {"configurable": {"thread_id": "1"}}
-graph.get_state(config)
-
-# get a state snapshot for a specific checkpoint_id
-config = {"configurable": {"thread_id": "1", "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c"}}
-graph.get_state(config)
-```
-:::
-
-:::js
-When interacting with the saved graph state, you **must** specify a [thread identifier](#threads). You can view the _latest_ state of the graph by calling `graph.getState(config)`. This will return a `StateSnapshot` object that corresponds to the latest checkpoint associated with the thread ID provided in the config or a checkpoint associated with a checkpoint ID for the thread, if provided.
-
-```typescript
-// get the latest state snapshot
-const config = { configurable: { thread_id: "1" } };
-await graph.getState(config);
-
-// get a state snapshot for a specific checkpoint_id
-const config = {
- configurable: {
- thread_id: "1",
- checkpoint_id: "1ef663ba-28fe-6528-8002-5a559208592c",
- },
-};
-await graph.getState(config);
-```
-:::
-
-:::python
-In our example, the output of `get_state` will look like this:
-
-```
-StateSnapshot(
- values={'foo': 'b', 'bar': ['a', 'b']},
- next=(),
- config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28fe-6528-8002-5a559208592c'}},
- metadata={'source': 'loop', 'writes': {'node_b': {'foo': 'b', 'bar': ['b']}}, 'step': 2},
- created_at='2024-08-29T19:19:38.821749+00:00',
- parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}}, tasks=()
-)
-```
-:::
-
-:::js
-In our example, the output of `getState` will look like this:
-
-```
-StateSnapshot {
- values: { foo: 'b', bar: ['a', 'b'] },
- next: [],
- config: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28fe-6528-8002-5a559208592c'
- }
- },
- metadata: {
- source: 'loop',
- writes: { nodeB: { foo: 'b', bar: ['b'] } },
- step: 2
- },
- createdAt: '2024-08-29T19:19:38.821749+00:00',
- parentConfig: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f9-6ec4-8001-31981c2c39f8'
- }
- },
- tasks: []
-}
-```
-:::
-
-#### StateSnapshot fields
-
-:::python
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `values` | `dict` | State channel values at this checkpoint. |
-| `next` | `tuple[str, ...]` | Node names to execute next. Empty `()` means the graph is complete. |
-| `config` | `dict` | Contains `thread_id`, `checkpoint_ns`, and `checkpoint_id`. |
-| `metadata` | `dict` | Execution metadata. Contains `source` (`"input"`, `"loop"`, or `"update"`), `writes` (node outputs), and `step` (super-step counter). |
-| `created_at` | `str` | ISO 8601 timestamp of when this checkpoint was created. |
-| `parent_config` | `dict \| None` | Config of the previous checkpoint. `None` for the first checkpoint. |
-| `tasks` | `tuple[PregelTask, ...]` | Tasks to execute at this step. Each task has `id`, `name`, `error`, `interrupts`, and optionally `state` (subgraph snapshot, when using `subgraphs=True`). |
-
-:::
-
-:::js
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `values` | `object` | State channel values at this checkpoint. |
-| `next` | `string[]` | Node names to execute next. Empty `[]` means the graph is complete. |
-| `config` | `object` | Contains `thread_id`, `checkpoint_ns`, and `checkpoint_id`. |
-| `metadata` | `object` | Execution metadata. Contains `source` (`"input"`, `"loop"`, or `"update"`), `writes` (node outputs), and `step` (super-step counter). |
-| `createdAt` | `string` | ISO 8601 timestamp of when this checkpoint was created. |
-| `parentConfig` | `object \| null` | Config of the previous checkpoint. `null` for the first checkpoint. |
-| `tasks` | `PregelTask[]` | Tasks to execute at this step. Each task has `id`, `name`, `error`, `interrupts`, and optionally `state` (subgraph snapshot, when using `subgraphs: true`). |
-
-:::
-
-### Get state history
-
-:::python
-You can get the full history of the graph execution for a given thread by calling @[`graph.get_state_history(config)`][get_state_history]. This will return a list of `StateSnapshot` objects associated with the thread ID provided in the config. Importantly, the checkpoints will be ordered chronologically with the most recent checkpoint / `StateSnapshot` being the first in the list.
-
-```python
-config = {"configurable": {"thread_id": "1"}}
-list(graph.get_state_history(config))
-```
-:::
-
-:::js
-You can get the full history of the graph execution for a given thread by calling `graph.getStateHistory(config)`. This will return a list of `StateSnapshot` objects associated with the thread ID provided in the config. Importantly, the checkpoints will be ordered chronologically with the most recent checkpoint / `StateSnapshot` being the first in the list.
-
-```typescript
-const config = { configurable: { thread_id: "1" } };
-for await (const state of graph.getStateHistory(config)) {
- console.log(state);
-}
-```
-:::
-
-:::python
-In our example, the output of @[`get_state_history`] will look like this:
-
-```
-[
- StateSnapshot(
- values={'foo': 'b', 'bar': ['a', 'b']},
- next=(),
- config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28fe-6528-8002-5a559208592c'}},
- metadata={'source': 'loop', 'writes': {'node_b': {'foo': 'b', 'bar': ['b']}}, 'step': 2},
- created_at='2024-08-29T19:19:38.821749+00:00',
- parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
- tasks=(),
- ),
- StateSnapshot(
- values={'foo': 'a', 'bar': ['a']},
- next=('node_b',),
- config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
- metadata={'source': 'loop', 'writes': {'node_a': {'foo': 'a', 'bar': ['a']}}, 'step': 1},
- created_at='2024-08-29T19:19:38.819946+00:00',
- parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
- tasks=(PregelTask(id='6fb7314f-f114-5413-a1f3-d37dfe98ff44', name='node_b', error=None, interrupts=()),),
- ),
- StateSnapshot(
- values={'foo': '', 'bar': []},
- next=('node_a',),
- config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
- metadata={'source': 'loop', 'writes': None, 'step': 0},
- created_at='2024-08-29T19:19:38.817813+00:00',
- parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
- tasks=(PregelTask(id='f1b14528-5ee5-579c-949b-23ef9bfbed58', name='node_a', error=None, interrupts=()),),
- ),
- StateSnapshot(
- values={'bar': []},
- next=('__start__',),
- config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
- metadata={'source': 'input', 'writes': {'foo': ''}, 'step': -1},
- created_at='2024-08-29T19:19:38.816205+00:00',
- parent_config=None,
- tasks=(PregelTask(id='6d27aa2e-d72b-5504-a36f-8620e54a76dd', name='__start__', error=None, interrupts=()),),
- )
-]
-```
-:::
-
-:::js
-In our example, the output of `getStateHistory` will look like this:
-
-```
-[
- StateSnapshot {
- values: { foo: 'b', bar: ['a', 'b'] },
- next: [],
- config: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28fe-6528-8002-5a559208592c'
- }
- },
- metadata: {
- source: 'loop',
- writes: { nodeB: { foo: 'b', bar: ['b'] } },
- step: 2
- },
- createdAt: '2024-08-29T19:19:38.821749+00:00',
- parentConfig: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f9-6ec4-8001-31981c2c39f8'
- }
- },
- tasks: []
- },
- StateSnapshot {
- values: { foo: 'a', bar: ['a'] },
- next: ['nodeB'],
- config: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f9-6ec4-8001-31981c2c39f8'
- }
- },
- metadata: {
- source: 'loop',
- writes: { nodeA: { foo: 'a', bar: ['a'] } },
- step: 1
- },
- createdAt: '2024-08-29T19:19:38.819946+00:00',
- parentConfig: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f4-6b4a-8000-ca575a13d36a'
- }
- },
- tasks: [
- PregelTask {
- id: '6fb7314f-f114-5413-a1f3-d37dfe98ff44',
- name: 'nodeB',
- error: null,
- interrupts: []
- }
- ]
- },
- StateSnapshot {
- values: { foo: '', bar: [] },
- next: ['node_a'],
- config: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f4-6b4a-8000-ca575a13d36a'
- }
- },
- metadata: {
- source: 'loop',
- writes: null,
- step: 0
- },
- createdAt: '2024-08-29T19:19:38.817813+00:00',
- parentConfig: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f0-6c66-bfff-6723431e8481'
- }
- },
- tasks: [
- PregelTask {
- id: 'f1b14528-5ee5-579c-949b-23ef9bfbed58',
- name: 'node_a',
- error: null,
- interrupts: []
- }
- ]
- },
- StateSnapshot {
- values: { bar: [] },
- next: ['__start__'],
- config: {
- configurable: {
- thread_id: '1',
- checkpoint_ns: '',
- checkpoint_id: '1ef663ba-28f0-6c66-bfff-6723431e8481'
- }
- },
- metadata: {
- source: 'input',
- writes: { foo: '' },
- step: -1
- },
- createdAt: '2024-08-29T19:19:38.816205+00:00',
- parentConfig: null,
- tasks: [
- PregelTask {
- id: '6d27aa2e-d72b-5504-a36f-8620e54a76dd',
- name: '__start__',
- error: null,
- interrupts: []
- }
- ]
- }
-]
-```
-:::
-
-
-
-#### Find a specific checkpoint
-
-You can filter the state history to find checkpoints matching specific criteria:
-
-:::python
-```python
-history = list(graph.get_state_history(config))
-
-# Find the checkpoint before a specific node executed
-before_node_b = next(s for s in history if s.next == ("node_b",))
-
-# Find a checkpoint by step number
-step_2 = next(s for s in history if s.metadata["step"] == 2)
+store = InMemoryStore()
-# Find checkpoints created by update_state
-forks = [s for s in history if s.metadata["source"] == "update"]
+graph = builder.compile(checkpointer=checkpointer, store=store)
-# Find the checkpoint where an interrupt occurred
-interrupted = next(
- s for s in history
- if s.tasks and any(t.interrupts for t in s.tasks)
+result = graph.invoke(
+ {"messages": [{"role": "user", "content": "Hi, my name is Bob."}]},
+ {"configurable": {"thread_id": "thread-1"}},
)
```
:::
:::js
```typescript
-const history: StateSnapshot[] = [];
-for await (const state of graph.getStateHistory(config)) {
- history.push(state);
-}
-
-// Find the checkpoint before a specific node executed
-const beforeNodeB = history.find((s) => s.next.includes("nodeB"));
+import { MemorySaver, MemoryStore } from "@langchain/langgraph";
-// Find a checkpoint by step number
-const step2 = history.find((s) => s.metadata.step === 2);
+const checkpointer = new MemorySaver();
+const store = new MemoryStore();
-// Find checkpoints created by updateState
-const forks = history.filter((s) => s.metadata.source === "update");
+const graph = builder.compile({ checkpointer, store });
-// Find the checkpoint where an interrupt occurred
-const interrupted = history.find(
- (s) => s.tasks.length > 0 && s.tasks.some((t) => t.interrupts.length > 0)
+const result = await graph.invoke(
+ { messages: [{ role: "user", content: "Hi, my name is Bob." }] },
+ { configurable: { thread_id: "thread-1" } }
);
```
:::
-### Replay
-
-Replay re-executes steps from a prior checkpoint. Invoke the graph with a prior `checkpoint_id` to re-run nodes after that checkpoint. Nodes before the checkpoint are skipped (their results are already saved). Nodes after the checkpoint re-execute, including any LLM calls, API requests, or [interrupts](/oss/langgraph/interrupts) — which are always re-triggered during replay.
-
-See [Time travel](/oss/langgraph/use-time-travel) for full details and code examples on replaying past executions.
-
-
-
-### Update state
-
-:::python
-You can edit the graph state using @[`update_state`]. This creates a new checkpoint with the updated values — it does not modify the original checkpoint. The update is treated the same as a node update: values are passed through [reducer](/oss/langgraph/graph-api#reducers) functions when defined, so channels with reducers _accumulate_ values rather than overwrite them.
-
-You can optionally specify `as_node` to control which node the update is treated as coming from, which affects which node executes next. See [Time travel: `as_node`](/oss/langgraph/use-time-travel#from-a-specific-node) for details.
-:::
-
-:::js
-You can edit the graph state using `graph.updateState()`. This creates a new checkpoint with the updated values — it does not modify the original checkpoint. The update is treated the same as a node update: values are passed through [reducer](/oss/langgraph/graph-api#reducers) functions when defined, so channels with reducers _accumulate_ values rather than overwrite them.
-
-You can optionally specify `asNode` to control which node the update is treated as coming from, which affects which node executes next. See [Time travel: `asNode`](/oss/langgraph/use-time-travel#from-a-specific-node) for details.
-:::
-
-
-
-## Memory store
-
-
-
-A [state schema](/oss/langgraph/graph-api#schema) specifies a set of keys that are populated as a graph is executed. As discussed above, state can be written by a checkpointer to a thread at each graph step, enabling state persistence.
-
-What if we want to retain some information _across threads_? Consider the case of a chatbot where we want to retain specific information about the user across _all_ chat conversations (e.g., threads) with that user!
-
-With checkpointers alone, we cannot share information across threads. This motivates the need for the [`Store`](https://reference.langchain.com/python/langgraph/store/) interface. As an illustration, we can define an `InMemoryStore` to store information about a user across threads. We simply compile our graph with a checkpointer, as before, and pass the store.
-
-**LangGraph API handles stores automatically**
-When using the LangGraph API, you don't need to implement or configure stores manually. The API handles all storage infrastructure for you behind the scenes.
+**Agent Server handles persistence automatically**
+When using the [Agent Server](/langsmith/agent-server), you do not need to implement or configure checkpointers or stores manually. The server handles persistence infrastructure behind the scenes.
-
-@[InMemoryStore] is suitable for development and testing. For production, use a persistent store like `PostgresStore` or `RedisStore`. All implementations extend @[BaseStore], which is the type annotation to use in node function signatures.
-
-
-### Basic usage
-
-First, let's showcase this in isolation without using LangGraph.
-
-:::python
-```python
-from langgraph.store.memory import InMemoryStore
-store = InMemoryStore()
-```
-:::
-
-:::js
-```typescript
-import { MemoryStore } from "@langchain/langgraph";
+## Checkpointer vs. store
-const memoryStore = new MemoryStore();
-```
-:::
+| | Checkpointer | Store |
+| ---- | ---- | ---- |
+| Persists | Graph state snapshots | Application-defined key-value data |
+| Scope | A single thread | Across threads |
+| Memory type | Short-term, thread-scoped memory | Long-term, cross-thread memory |
+| Use for | Conversation continuity, human-in-the-loop, time travel, and fault tolerance | User preferences, facts, and shared knowledge |
+| Access pattern | Pass a `thread_id` in graph config | Read and write items from nodes or application code |
+| Full guide | [Checkpointers](/oss/langgraph/checkpointers) | [Stores](/oss/langgraph/stores) |
-Memories are namespaced by a `tuple`, which in this specific example will be `(, "memories")`. The namespace can be any length and represent anything, does not have to be user specific.
+## Troubleshooting common issues
-:::python
-```python
-user_id = "1"
-namespace_for_memory = (user_id, "memories")
-```
-:::
+### PostgresSaver: `thread_id` too long
-:::js
-```typescript
-const userId = "1";
-const namespaceForMemory = [userId, "memories"];
-```
-:::
+When using `PostgresSaver` (or `AsyncPostgresSaver`), the `thread_id` is stored in a column with limited length. If your `thread_id` exceeds the column size, you will see a database error.
-We use the `store.put` method to save memories to our namespace in the store. When we do this, we specify the namespace, as defined above, and a key-value pair for the memory: the key is simply a unique identifier for the memory (`memory_id`) and the value (a dictionary) is the memory itself.
+**Fix:** Keep `thread_id` values under 255 characters. Use a UUID or hash if you need deterministic IDs:
:::python
```python
-memory_id = str(uuid.uuid4())
-memory = {"food_preference" : "I like pizza"}
-store.put(namespace_for_memory, memory_id, memory)
-```
-:::
+import uuid
-:::js
-```typescript
-import { v4 as uuidv4 } from "uuid";
-
-const memoryId = uuidv4();
-const memory = { food_preference: "I like pizza" };
-await memoryStore.put(namespaceForMemory, memoryId, memory);
+config = {"configurable": {"thread_id": str(uuid.uuid4())[:255]}}
```
:::
-We can read out memories in our namespace using the `store.search` method, which will return all memories for a given user as a list. The most recent memory is the last in the list.
-
-:::python
-```python
-memories = store.search(namespace_for_memory)
-memories[-1].dict()
-{'value': {'food_preference': 'I like pizza'},
- 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
- 'namespace': ['1', 'memories'],
- 'created_at': '2024-10-02T17:22:31.590602+00:00',
- 'updated_at': '2024-10-02T17:22:31.590605+00:00'}
-```
-
-Each memory type is a Python class ([`Item`](https://langchain-ai.github.io/langgraph/reference/store/#langgraph.store.base.Item)) with certain attributes. We can access it as a dictionary by converting via `.dict` as above.
+### `MemorySaver` does not persist between restarts
-The attributes it has are:
+`MemorySaver` and `InMemorySaver` store checkpoints in RAM. When the process restarts, all checkpoints are lost.
-* `value`: The value (itself a dictionary) of this memory
-* `key`: A unique key for this memory in this namespace
-* `namespace`: A tuple of strings, the namespace of this memory type
+**Fix:** Use a persistent checkpointer for production:
-
- While the type is `tuple[str, ...]`, it may be serialized as a list when converted to JSON (for example, `['1', 'memories']`).
-
+- `PostgresSaver`: PostgreSQL with async support
+- `SqliteSaver`: Local file-based storage for development
-* `created_at`: Timestamp for when this memory was created
-* `updated_at`: Timestamp for when this memory was updated
+### Checkpoints growing unboundedly
-:::
+Over long conversations, checkpoints accumulate. This can increase latency and storage costs.
-:::js
-```typescript
-const memories = await memoryStore.search(namespaceForMemory);
-memories[memories.length - 1];
-
-// {
-// value: { food_preference: 'I like pizza' },
-// key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
-// namespace: ['1', 'memories'],
-// createdAt: '2024-10-02T17:22:31.590602+00:00',
-// updatedAt: '2024-10-02T17:22:31.590605+00:00'
-// }
-```
-
-The attributes it has are:
-
-* `value`: The value of this memory
-* `key`: A unique key for this memory in this namespace
-* `namespace`: A tuple of strings, the namespace of this memory type
-
-
- While the type is `tuple`, it may be serialized as a list when converted to JSON (for example, `['1', 'memories']`).
-
-
-* `createdAt`: Timestamp for when this memory was created
-* `updatedAt`: Timestamp for when this memory was updated
-
-:::
-
-### Semantic search
-
-Beyond simple retrieval, the store also supports semantic search, allowing you to find memories based on meaning rather than exact matches. To enable this, configure the store with an embedding model:
-
-:::python
-```python
-from langchain.embeddings import init_embeddings
-
-store = InMemoryStore(
- index={
- "embed": init_embeddings("openai:text-embedding-3-small"), # Embedding provider
- "dims": 1536, # Embedding dimensions
- "fields": ["food_preference", "$"] # Fields to embed
- }
-)
-```
-:::
-
-:::js
-```typescript
-import { OpenAIEmbeddings } from "@langchain/openai";
-
-const store = new InMemoryStore({
- index: {
- embeddings: new OpenAIEmbeddings({ model: "text-embedding-3-small" }),
- dims: 1536,
- fields: ["food_preference", "$"], // Fields to embed
- },
-});
-```
-:::
-
-Now when searching, you can use natural language queries to find relevant memories:
-
-:::python
-```python
-# Find memories about food preferences
-# (This can be done after putting memories into the store)
-memories = store.search(
- namespace_for_memory,
- query="What does the user like to eat?",
- limit=3 # Return top 3 matches
-)
-```
-:::
-
-:::js
-```typescript
-// Find memories about food preferences
-// (This can be done after putting memories into the store)
-const memories = await store.search(namespaceForMemory, {
- query: "What does the user like to eat?",
- limit: 3, // Return top 3 matches
-});
-```
-:::
-
-You can control which parts of your memories get embedded by configuring the `fields` parameter or by specifying the `index` parameter when storing memories:
-
-:::python
-```python
-# Store with specific fields to embed
-store.put(
- namespace_for_memory,
- str(uuid.uuid4()),
- {
- "food_preference": "I love Italian cuisine",
- "context": "Discussing dinner plans"
- },
- index=["food_preference"] # Only embed "food_preferences" field
-)
-
-# Store without embedding (still retrievable, but not searchable)
-store.put(
- namespace_for_memory,
- str(uuid.uuid4()),
- {"system_info": "Last updated: 2024-01-01"},
- index=False
-)
-```
-:::
-
-:::js
-```typescript
-// Store with specific fields to embed
-await store.put(
- namespaceForMemory,
- uuidv4(),
- {
- food_preference: "I love Italian cuisine",
- context: "Discussing dinner plans",
- },
- { index: ["food_preference"] } // Only embed "food_preferences" field
-);
-
-// Store without embedding (still retrievable, but not searchable)
-await store.put(
- namespaceForMemory,
- uuidv4(),
- { system_info: "Last updated: 2024-01-01" },
- { index: false }
-);
-```
-:::
-
-### Using in LangGraph
-
-:::python
-With this all in place, we use the store in LangGraph. The store works hand-in-hand with the checkpointer: the checkpointer saves state to threads, as discussed above, and the store allows us to store arbitrary information for access _across_ threads. We compile the graph with both the checkpointer and the store as follows.
-
-```python
-from dataclasses import dataclass
-from langgraph.checkpoint.memory import InMemorySaver
-
-@dataclass
-class Context:
- user_id: str
-
-# We need this because we want to enable threads (conversations)
-checkpointer = InMemorySaver()
-
-# ... Define the graph ...
-
-# Compile the graph with the checkpointer and store
-builder = StateGraph(MessagesState, context_schema=Context)
-# ... add nodes and edges ...
-graph = builder.compile(checkpointer=checkpointer, store=store)
-```
-:::
-
-:::js
-With this all in place, we use the `memoryStore` in LangGraph. The `memoryStore` works hand-in-hand with the checkpointer: the checkpointer saves state to threads, as discussed above, and the `memoryStore` allows us to store arbitrary information for access _across_ threads. We compile the graph with both the checkpointer and the `memoryStore` as follows.
-
-```typescript
-import { MemorySaver } from "@langchain/langgraph";
-
-// We need this because we want to enable threads (conversations)
-const checkpointer = new MemorySaver();
-
-// ... Define the graph ...
-
-// Compile the graph with the checkpointer and store
-const graph = workflow.compile({ checkpointer, store: memoryStore });
-```
-:::
-
-We invoke the graph with a `thread_id`, as before, and also with a `user_id`, which we'll use to namespace our memories to this particular user as we showed above.
-
-:::python
-```python
-# Invoke the graph
-config = {"configurable": {"thread_id": "1"}}
-
-# First let's just say hi to the AI
-for update in graph.stream(
- {"messages": [{"role": "user", "content": "hi"}]},
- config,
- stream_mode="updates",
- context=Context(user_id="1"),
-):
- print(update)
-```
-:::
-
-:::js
-```typescript
-// Invoke the graph
-const userId = "1";
-const config = { configurable: { thread_id: "1" }, context: { userId } };
-
-// First let's just say hi to the AI
-for await (const update of await graph.stream(
- { messages: [{ role: "user", content: "hi" }] },
- { ...config, streamMode: "updates" }
-)) {
- console.log(update);
-}
-```
-:::
-
-:::python
-You can access the store and the `user_id` in _any node_ by using the `Runtime` object. The `Runtime` is automatically injected by LangGraph when you add it as a parameter to your node function. Here's how you might use it to save memories:
-
-```python
-from langgraph.runtime import Runtime
-from dataclasses import dataclass
-
-@dataclass
-class Context:
- user_id: str
-
-async def update_memory(state: MessagesState, runtime: Runtime[Context]):
-
- # Get the user id from the runtime context
- user_id = runtime.context.user_id
-
- # Namespace the memory
- namespace = (user_id, "memories")
-
- # ... Analyze conversation and create a new memory
-
- # Create a new memory ID
- memory_id = str(uuid.uuid4())
-
- # We create a new memory
- await runtime.store.aput(namespace, memory_id, {"memory": memory})
-
-```
-
-
-:::
-
-:::js
-You can access the store and the `userId` in _any node_ with the `runtime` argument. Here's how you might use it to save memories:
-
-```typescript
-import { StateSchema, MessagesValue, Runtime } from "@langchain/langgraph";
-import { v4 as uuidv4 } from "uuid";
-
-const MessagesState = new StateSchema({
- messages: MessagesValue,
-});
-
-const updateMemory: GraphNode = async (state, runtime) => {
- // Get the user id from the config
- const userId = runtime.context?.user_id;
- if (!userId) throw new Error("User ID is required");
-
- // Namespace the memory
- const namespace = [userId, "memories"];
-
- // ... Analyze conversation and create a new memory
- const memory = "Some memory content";
-
- // Create a new memory ID
- const memoryId = uuidv4();
-
- // We create a new memory
- await runtime.store?.put(namespace, memoryId, { memory });
-};
-```
-:::
-
-As we showed above, we can also access the store in any node and use the `store.search` method to get memories. Recall the memories are returned as a list of objects that can be converted to a dictionary.
+**Fix:** Prune old checkpoints periodically or set a retention policy:
:::python
```python
-memories[-1].dict()
-{'value': {'food_preference': 'I like pizza'},
- 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
- 'namespace': ['1', 'memories'],
- 'created_at': '2024-10-02T17:22:31.590602+00:00',
- 'updated_at': '2024-10-02T17:22:31.590605+00:00'}
-```
-:::
-
-:::js
-```typescript
-memories[memories.length - 1];
-// {
-// value: { food_preference: 'I like pizza' },
-// key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
-// namespace: ['1', 'memories'],
-// createdAt: '2024-10-02T17:22:31.590602+00:00',
-// updatedAt: '2024-10-02T17:22:31.590605+00:00'
-// }
-```
-:::
-
-We can access the memories and use them in our model call.
-
-:::python
-```python
-from dataclasses import dataclass
-from langgraph.runtime import Runtime
-
-@dataclass
-class Context:
- user_id: str
-
-async def call_model(state: MessagesState, runtime: Runtime[Context]):
- # Get the user id from the runtime context
- user_id = runtime.context.user_id
-
- # Namespace the memory
- namespace = (user_id, "memories")
-
- # Search based on the most recent message
- memories = await runtime.store.asearch(
- namespace,
- query=state["messages"][-1].content,
- limit=3
- )
- info = "\n".join([d.value["memory"] for d in memories])
-
- # ... Use memories in the model call
-```
-:::
-
-:::js
-```typescript
-const callModel: GraphNode = async (state, runtime) => {
- // Get the user id from the config
- const userId = runtime.context?.user_id;
-
- // Namespace the memory
- const namespace = [userId, "memories"];
-
- // Search based on the most recent message
- const memories = await runtime.store?.search(namespace, {
- query: state.messages[state.messages.length - 1].content,
- limit: 3,
- });
- const info = memories.map((d) => d.value.memory).join("\n");
-
- // ... Use memories in the model call
-};
-```
-:::
-
-If we create a new thread, we can still access the same memories so long as the `user_id` is the same.
-
-:::python
-```python
-# Invoke the graph on a new thread
-config = {"configurable": {"thread_id": "2"}}
-
-# Let's say hi again
-for update in graph.stream(
- {"messages": [{"role": "user", "content": "hi, tell me about my memories"}]},
- config,
- stream_mode="updates",
- context=Context(user_id="1"),
-):
- print(update)
-```
-:::
-
-:::js
-```typescript
-// Invoke the graph
-const config = { configurable: { thread_id: "2" }, context: { userId: "1" } };
-
-// Let's say hi again
-for await (const update of await graph.stream(
- { messages: [{ role: "user", content: "hi, tell me about my memories" }] },
- { ...config, streamMode: "updates" }
-)) {
- console.log(update);
-}
-```
-:::
-
-When we use the LangSmith, either locally (e.g., in [Studio](/langsmith/studio)) or [hosted with LangSmith](/langsmith/platform-setup), the base store is available to use by default and does not need to be specified during graph compilation. To enable semantic search, however, you **do** need to configure the indexing settings in your `langgraph.json` file. For example:
+from langgraph.checkpoint.postgres import PostgresSaver
-```json
-{
- ...
- "store": {
- "index": {
- "embed": "openai:text-embeddings-3-small",
- "dims": 1536,
- "fields": ["$"]
- }
- }
-}
+checkpointer = PostgresSaver.from_conn_string("postgresql://...")
+checkpointer.setup() # Creates tables with indexes
+# Consider adding a cron job to delete checkpoints older than N days
```
-
-See the [deployment guide](/langsmith/semantic-search) for more details and configuration options.
-
-## Checkpointer libraries
-
-Under the hood, checkpointing is powered by checkpointer objects that conform to @[`BaseCheckpointSaver`] interface. LangGraph provides several checkpointer implementations, all implemented via standalone, installable libraries.
-
-:::python
-
-See [checkpointer integrations](/oss/integrations/checkpointers/index) for available providers.
-
-
-* `langgraph-checkpoint`: The base interface for checkpointer savers (@[`BaseCheckpointSaver`]) and serialization/deserialization interface (@[`SerializerProtocol`]). Includes in-memory checkpointer implementation (@[`InMemorySaver`]) for experimentation. LangGraph comes with `langgraph-checkpoint` included.
-* `langgraph-checkpoint-sqlite`: An implementation of LangGraph checkpointer that uses SQLite database (@[`SqliteSaver`] / @[`AsyncSqliteSaver`]). Ideal for experimentation and local workflows. Needs to be installed separately.
-* `langgraph-checkpoint-postgres`: An advanced checkpointer that uses Postgres database (@[`PostgresSaver`] / @[`AsyncPostgresSaver`]), used in LangSmith. Ideal for using in production. Needs to be installed separately.
-* `langgraph-checkpoint-cosmosdb`: An implementation of LangGraph checkpointer that uses Azure Cosmos DB (`CosmosDBSaver` / `AsyncCosmosDBSaver`). Ideal for using in production with Azure. Supports both sync and async operations. Needs to be installed separately.
-:::
-
-:::js
-* `@langchain/langgraph-checkpoint`: The base interface for checkpointer savers (@[`BaseCheckpointSaver`]) and serialization/deserialization interface (@[`SerializerProtocol`]). Includes in-memory checkpointer implementation (@[`MemorySaver`]) for experimentation. LangGraph comes with `@langchain/langgraph-checkpoint` included.
-* `@langchain/langgraph-checkpoint-sqlite`: An implementation of LangGraph checkpointer that uses SQLite database (@[`SqliteSaver`]). Ideal for experimentation and local workflows. Needs to be installed separately.
-* `@langchain/langgraph-checkpoint-postgres`: An advanced checkpointer that uses Postgres database (@[`PostgresSaver`]), used in LangSmith. Ideal for using in production. Needs to be installed separately.
-* `@langchain/langgraph-checkpoint-mongodb`: An advanced checkpointer that uses MongoDB database (`MongoDBSaver`). Ideal for using in production. Needs to be installed separately.
-* `@langchain/langgraph-checkpoint-redis`: An advanced checkpointer that uses Redis database (`RedisSaver`). Ideal for using in production. Needs to be installed separately.
-:::
-
-### Checkpointer interface
-
-:::python
-Each checkpointer conforms to @[`BaseCheckpointSaver`] interface and implements the following methods:
-
-* `.put` - Store a checkpoint with its configuration and metadata.
-* `.put_writes` - Store intermediate writes linked to a checkpoint (i.e. [pending writes](#pending-writes)).
-* `.get_tuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `checkpoint_id`). This is used to populate `StateSnapshot` in `graph.get_state()`.
-* `.list` - List checkpoints that match a given configuration and filter criteria. This is used to populate state history in `graph.get_state_history()`
-
-If the checkpointer is used with asynchronous graph execution (i.e. executing the graph via `.ainvoke`, `.astream`, `.abatch`), asynchronous versions of the above methods will be used (`.aput`, `.aput_writes`, `.aget_tuple`, `.alist`).
-
-
-For running your graph asynchronously, you can use @[`InMemorySaver`], or async versions of Sqlite/Postgres checkpointers -- @[`AsyncSqliteSaver`] / @[`AsyncPostgresSaver`] checkpointers.
-
-:::
-
-:::js
-Each checkpointer conforms to the @[`BaseCheckpointSaver`] interface and implements the following methods:
-
-* `.put` - Store a checkpoint with its configuration and metadata.
-* `.putWrites` - Store intermediate writes linked to a checkpoint (i.e. [pending writes](#pending-writes)).
-* `.getTuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `checkpoint_id`). This is used to populate `StateSnapshot` in `graph.getState()`.
-* `.list` - List checkpoints that match a given configuration and filter criteria. This is used to populate state history in `graph.getStateHistory()`
:::
-:::python
-
-### Serializer
-
-When checkpointers save the graph state, they need to serialize the channel values in the state. This is done using serializer objects.
-
-`langgraph_checkpoint` defines @[protocol][SerializerProtocol] for implementing serializers provides a default implementation (@[`JsonPlusSerializer`]) that handles a wide variety of types, including LangChain and LangGraph primitives, datetimes, enums and more.
-
-#### Serialization with `pickle`
-
-The default serializer, @[`JsonPlusSerializer`], uses ormsgpack and JSON under the hood, which is not suitable for all types of objects.
+### State access from parent graph to subgraph
-If you want to fallback to pickle for objects not currently supported by our msgpack encoder (such as Pandas dataframes),
-you can use the `pickle_fallback` argument of the @[`JsonPlusSerializer`]:
-
-```python
-from langgraph.checkpoint.memory import InMemorySaver
-from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
-
-# ... Define the graph ...
-graph.compile(
- checkpointer=InMemorySaver(serde=JsonPlusSerializer(pickle_fallback=True))
-)
-```
+When a subgraph updates state, the parent graph may not see the changes immediately. This is because each subgraph manages its own checkpoint namespace.
-#### Encryption
+**Fix:** Use [shared state via Store](/oss/langgraph/stores) for data that needs to cross graph boundaries, or configure your subgraph to write to the parent checkpoint.
-Checkpointers can optionally encrypt all persisted state. To enable this, pass an instance of @[`EncryptedSerializer`] to the `serde` argument of any @[`BaseCheckpointSaver`] implementation. The easiest way to create an encrypted serializer is via @[`from_pycryptodome_aes`], which reads the AES key from the `LANGGRAPH_AES_KEY` environment variable (or accepts a `key` argument):
+## Next steps
-```python
-import sqlite3
-
-from langgraph.checkpoint.serde.encrypted import EncryptedSerializer
-from langgraph.checkpoint.sqlite import SqliteSaver
-
-serde = EncryptedSerializer.from_pycryptodome_aes() # reads LANGGRAPH_AES_KEY
-checkpointer = SqliteSaver(sqlite3.connect("checkpoint.db"), serde=serde)
-```
-
-```python
-from langgraph.checkpoint.serde.encrypted import EncryptedSerializer
-from langgraph.checkpoint.postgres import PostgresSaver
-
-serde = EncryptedSerializer.from_pycryptodome_aes()
-checkpointer = PostgresSaver.from_conn_string("postgresql://...", serde=serde)
-checkpointer.setup()
-```
-
-When running on LangSmith, encryption is automatically enabled whenever `LANGGRAPH_AES_KEY` is present, so you only need to provide the environment variable. Other encryption schemes can be used by implementing @[`CipherProtocol`] and supplying it to @[`EncryptedSerializer`].
-
-:::
+- [Use checkpointers](/oss/langgraph/checkpointers) to persist and inspect thread state.
+- [Use stores](/oss/langgraph/stores) to persist durable data across threads.
diff --git a/pregel.mdx b/pregel.mdx
index 3923876..0722584 100644
--- a/pregel.mdx
+++ b/pregel.mdx
@@ -4,7 +4,6 @@ sidebarTitle: Runtime
---
-
:::python
@[`Pregel`] implements LangGraph's runtime, managing the execution of LangGraph applications.
@@ -45,18 +44,174 @@ An **actor** is a `PregelNode`. It subscribes to channels, reads data from them,
## Channels
-Channels are used to communicate between actors (PregelNodes). Each channel has a value type, an update type, and an update function—which takes a sequence of updates and modifies the stored value. Channels can be used to send data from one chain to another, or to send data from a chain to itself in a future step. LangGraph provides a number of built-in channels:
+Channels are used to communicate between actors (PregelNodes). Each channel has a value type, an update type, and an update function—which takes a sequence of updates and modifies the stored value. Channels can be used to send data from one chain to another, or to send data from a chain to itself in a future step.
+
+### LastValue
+
+@[`LastValue`] is the default channel type. It stores the last value written to it, overwriting any previous value. Use it for input and output values, or for passing data from one step to the next.
+
+:::python
+```python
+from langgraph.channels import LastValue
+
+channel: LastValue[int] = LastValue(int)
+```
+:::
+
+:::js
+```typescript
+import { LastValue } from "@langchain/langgraph/channels";
+
+const channel = new LastValue();
+```
+:::
+
+### Topic
+
+@[`Topic`] is a configurable PubSub channel useful for sending multiple values between actors or accumulating output across steps. It can be configured to deduplicate values or to accumulate all values written during a run.
:::python
-* @[`LastValue`]: The default channel, stores the last value sent to the channel, useful for input and output values, or for sending data from one step to the next.
-* @[`Topic`]: A configurable PubSub Topic, useful for sending multiple values between **actors**, or for accumulating output. Can be configured to deduplicate values or to accumulate values over the course of multiple steps.
-* @[`BinaryOperatorAggregate`]: stores a persistent value, updated by applying a binary operator to the current value and each update sent to the channel, useful for computing aggregates over multiple steps; e.g.,`total = BinaryOperatorAggregate(int, operator.add)`
+```python
+from langgraph.channels import Topic
+
+# Accumulate all values written across steps
+channel: Topic[str] = Topic(str, accumulate=True)
+```
:::
:::js
-* @[`LastValue`]: The default channel, stores the last value sent to the channel, useful for input and output values, or for sending data from one step to the next.
-* @[`Topic`]: A configurable PubSub Topic, useful for sending multiple values between **actors**, or for accumulating output. Can be configured to deduplicate values or to accumulate values over the course of multiple steps.
-* @[`BinaryOperatorAggregate`]: stores a persistent value, updated by applying a binary operator to the current value and each update sent to the channel, useful for computing aggregates over multiple steps; e.g.,`total = BinaryOperatorAggregate(int, operator.add)`
+```typescript
+import { Topic } from "@langchain/langgraph/channels";
+
+// Accumulate all values written across steps
+const channel = new Topic({ accumulate: true });
+```
+:::
+
+### BinaryOperatorAggregate
+
+@[`BinaryOperatorAggregate`] stores a persistent value that is updated by applying a binary operator to the current value and each new update. Use it to compute running aggregates across steps.
+
+:::python
+```python
+import operator
+from langgraph.channels import BinaryOperatorAggregate
+
+# Running total: each write adds to the current value
+total = BinaryOperatorAggregate(int, operator.add)
+```
+:::
+
+:::js
+```typescript
+import { BinaryOperatorAggregate } from "@langchain/langgraph/channels";
+
+// Running total: each write adds to the current value
+const total = new BinaryOperatorAggregate({ operator: (a, b) => a + b });
+```
+:::
+
+:::python
+### DeltaChannel
+
+
+`DeltaChannel` requires `langgraph>=1.2` and is currently in **beta**. The API may change in future releases.
+
+
+@[`DeltaChannel`] stores only the incremental delta at each step rather than the full accumulated value. This is most useful for channels that are written frequently and accumulate large values over time—for example, a conversation message list in a long-running thread. Without delta storage, the full list is re-serialized into every checkpoint; with `DeltaChannel`, only the new messages written at each step are stored.
+
+
+Consider `DeltaChannel` when a channel is both written to frequently and grows large over time. A good signal: if you notice checkpoint sizes growing linearly with thread length for a particular channel, `DeltaChannel` is likely a good fit.
+
+
+Use `DeltaChannel` in an `Annotated` type annotation the same way you would use a plain reducer:
+
+```python
+from typing import Annotated, Sequence
+from typing_extensions import TypedDict
+from langgraph.channels import DeltaChannel
+
+
+def my_reducer(state: list[str], writes: Sequence[list[str]]) -> list[str]:
+ result = list(state)
+ for write in writes:
+ result.extend(write)
+ return result
+
+
+class State(TypedDict):
+ messages: Annotated[list[str], DeltaChannel(my_reducer)]
+```
+
+#### Bulk reducer requirement
+
+The `reducer` passed to `DeltaChannel` is a **bulk reducer**: it receives the current state and a *sequence* of all writes from the current step in a single call—not pairwise like a standard reducer. This differs from the per-key reducers used with `Annotated` in a `StateGraph`, where the reducer is called once per update.
+
+
+The bulk reducer **must be associative** (batching-invariant):
+
+```
+reducer(reducer(state, [xs]), [ys]) == reducer(state, [xs, ys])
+```
+
+If your reducer is not associative, the reconstructed state may differ depending on how LangGraph batches writes across steps, producing inconsistent behavior.
+
+
+
+**The reducer runs on reconstruction, not on write.** Unlike a @[`BinaryOperatorAggregate`], whose reducer is invoked at write time so the combined value is what gets serialized into the checkpoint, a `DeltaChannel` reducer is invoked when the channel value is *rebuilt* from its persisted writes. The raw per-step writes are what get serialized; the reducer is only called when the value is materialized—on the next read, on the next step's actors, or when replaying history.
+
+Practical consequences when designing a reducer:
+
+- **Make it a pure function of `(state, writes)`.** Any side effects, randomness, or wall-clock reads (e.g., `uuid.uuid4()`, `datetime.now()`) execute every time the value is reconstructed and produce different results on each replay. They are *not* baked into the persisted writes.
+- **Do not rely on mutations to incoming writes being persisted.** If your reducer mutates a write object (for example, assigning a stable ID to an item that arrived without one), that mutation lives only in the reconstructed value. The stored write still has the original shape, so the next reconstruction will see the un-mutated input again.
+- **Attach identity and other stable metadata upstream.** If downstream code needs to reference an item by ID across turns (e.g., to update or remove it later), assign that ID before the value is written to the channel—not inside the reducer.
+
+
+Here are bulk reducers for the two most common cases:
+
+```python
+from typing import Any, Sequence
+
+
+# List: append all writes in order
+def list_reducer(state: list[Any], writes: Sequence[list[Any]]) -> list[Any]:
+ result = list(state)
+ for write in writes:
+ result.extend(write)
+ return result
+
+
+# Dict: merge all writes, last write wins on key conflicts
+def dict_reducer(
+ state: dict[str, Any], writes: Sequence[dict[str, Any]]
+) -> dict[str, Any]:
+ result = dict(state)
+ for write in writes:
+ result.update(write)
+ return result
+```
+
+Both are associative: applying batches one at a time produces the same result as applying them together.
+
+#### Use snapshot_frequency for bounded read latency
+
+Without snapshots, reading a `DeltaChannel` value requires replaying the full write history—O(N) for a thread with N steps. Setting `snapshot_frequency=K` writes a full snapshot every K pregel steps, bounding read depth to at most K steps:
+
+```python
+class State(TypedDict):
+ messages: Annotated[
+ list[str],
+ DeltaChannel(my_reducer, snapshot_frequency=5),
+ ]
+```
+
+Higher values of `snapshot_frequency` reduce storage overhead but increase read latency. Lower values bound latency more tightly at the cost of larger checkpoints. `None` (the default) skips snapshots entirely—appropriate when reads are rare or threads are short.
+
+#### Version compatibility and rollbacks
+
+
+**Rolling back to a version without `DeltaChannel` support is not supported.** `langgraph>=1.2` writes delta channel checkpoints in a new format that earlier versions cannot read. Once a thread has used `DeltaChannel`, downgrading LangGraph leaves those checkpoints unreadable as older runtimes do not understand the delta format and cannot reconstruct channel state. If you need to roll back, use the [delta-channel-dump recovery script](https://github.com/langchain-ai/langgraph/tree/main/examples/delta-channel-dump) to migrate affected threads, or discard them, before downgrading.
+
:::
## Examples
@@ -313,6 +468,10 @@ Below are a few different examples to give you a sense of the Pregel API.
app.invoke({"a": "foo"})
```
+
+ ```console
+ { 'c': 'foofoo | foofoofoofoo' }
+ ```
:::
:::js
diff --git a/quickstart.mdx b/quickstart.mdx
index 90da63e..0775d36 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -3,7 +3,6 @@ title: Quickstart
---
-
This quickstart demonstrates how to build a calculator agent using the LangGraph Graph API or the Functional API.
@@ -19,7 +18,7 @@ This quickstart demonstrates how to build a calculator agent using the LangGraph
For conceptual information, see [Graph API overview](/oss/langgraph/graph-api) and [Functional API overview](/oss/langgraph/functional-api).
-For this example, you will need to set up a [Claude (Anthropic)](https://www.anthropic.com/) account and get an API key. Then, set the `ANTHROPIC_API_KEY` environment variable in your terminal.
+For this example, you will need to set up a [Claude (Anthropic)](https://www.anthropic.com/) account and get an API key. Then, set the `ANTHROPIC_API_KEY` environment variable in your terminal. See [chat model integrations](/oss/integrations/chat) for all available providers. If you use [LangSmith Gateway](/langsmith/llm-gateway), you can [bring your own provider keys](/langsmith/llm-gateway-quickstart) or use [Gateway Credits](/langsmith/llm-gateway-credits) to access models without a provider key.
@@ -27,7 +26,7 @@ For this example, you will need to set up a [Claude (Anthropic)](https://www.ant
## 1. Define tools and model
-In this example, we'll use the Claude Sonnet 4.6 model and define tools for addition, multiplication, and division.
+In this example, we'll use the Claude Sonnet 4.5 model and define tools for addition, multiplication, and division.
:::python
```python
@@ -400,7 +399,9 @@ for (const message of result.messages) {
:::
- To learn how to trace your agent with LangSmith, see the [LangSmith documentation](/langsmith/trace-with-langgraph).
+Trace and debug your agent with [LangSmith](https://smith.langchain.com). Follow the [tracing quickstart](/langsmith/trace-with-langgraph) to get set up. When ready for production, see [Deploy](/langsmith/deployment) for hosting options.
+
+We recommend you also set up [LangSmith Engine](/langsmith/engine) which monitors your traces, detects issues, and proposes fixes.
Congratulations! You've built your first agent using the LangGraph Graph API.
@@ -475,7 +476,7 @@ class MessagesState(TypedDict):
from langchain.messages import SystemMessage
-def llm_call(state: dict):
+def llm_call(state: MessagesState):
"""LLM decides whether to call a tool or not"""
return {
@@ -498,7 +499,7 @@ def llm_call(state: dict):
from langchain.messages import ToolMessage
-def tool_node(state: dict):
+def tool_node(state: MessagesState):
"""Performs the tool call"""
result = []
@@ -724,7 +725,7 @@ for (const message of result.messages) {
## 1. Define tools and model
-In this example, we'll use the Claude Sonnet 4.6 model and define tools for addition, multiplication, and division.
+In this example, we'll use the Claude Sonnet 4.5 model and define tools for addition, multiplication, and division.
:::python
@@ -940,8 +941,9 @@ def agent(messages: list[BaseMessage]):
# Invoke
messages = [HumanMessage(content="Add 3 and 4.")]
-for chunk in agent.stream(messages, stream_mode="updates"):
- print(chunk)
+stream = agent.stream_events(messages, version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
:::
@@ -982,7 +984,9 @@ for (const message of result) {
:::
- To learn how to trace your agent with LangSmith, see the [LangSmith documentation](/langsmith/trace-with-langgraph).
+Trace and debug your agent with [LangSmith](https://smith.langchain.com). Follow the [tracing quickstart](/langsmith/trace-with-langgraph) to get set up. When ready for production, see [Deploy](/langsmith/deployment) for hosting options.
+
+We recommend you also set up [LangSmith Engine](/langsmith/engine) which monitors your traces, detects issues, and proposes fixes.
Congratulations! You've built your first agent using the LangGraph Functional API.
@@ -1099,8 +1103,9 @@ def agent(messages: list[BaseMessage]):
# Invoke
messages = [HumanMessage(content="Add 3 and 4.")]
-for chunk in agent.stream(messages, stream_mode="updates"):
- print(chunk)
+stream = agent.stream_events(messages, version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
:::
diff --git a/sql-agent.mdx b/sql-agent.mdx
index 177f60e..1cc05d8 100644
--- a/sql-agent.mdx
+++ b/sql-agent.mdx
@@ -5,7 +5,28 @@ sidebarTitle: Custom SQL agent
import ChatModelTabsPy from '/snippets/chat-model-tabs.mdx';
import ChatModelTabsJS from '/snippets/chat-model-tabs-js.mdx';
-
+import SqlAgentDownloadChinookPy from '/snippets/code-samples/sql-agent-download-chinook-py.mdx';
+import SqlAgentExploreDatabasePy from '/snippets/code-samples/sql-agent-explore-database-py.mdx';
+import LanggraphSqlAgentToolsPy from '/snippets/code-samples/langgraph-sql-agent-tools-py.mdx';
+import LanggraphSqlAgentDefineStepsPy from '/snippets/code-samples/langgraph-sql-agent-define-steps-py.mdx';
+import LanggraphSqlAgentAssembleAgentPy from '/snippets/code-samples/langgraph-sql-agent-assemble-agent-py.mdx';
+import LanggraphSqlAgentVisualizeGraphPy from '/snippets/code-samples/langgraph-sql-agent-visualize-graph-py.mdx';
+import LanggraphSqlAgentStreamAgentPy from '/snippets/code-samples/langgraph-sql-agent-stream-agent-py.mdx';
+import LanggraphSqlAgentHitlInterruptPy from '/snippets/code-samples/langgraph-sql-agent-hitl-interrupt-py.mdx';
+import LanggraphSqlAgentHitlAssemblePy from '/snippets/code-samples/langgraph-sql-agent-hitl-assemble-py.mdx';
+import LanggraphSqlAgentHitlStreamPy from '/snippets/code-samples/langgraph-sql-agent-hitl-stream-py.mdx';
+import LanggraphSqlAgentHitlResumePy from '/snippets/code-samples/langgraph-sql-agent-hitl-resume-py.mdx';
+import LanggraphSqlAgentDownloadChinookJs from '/snippets/code-samples/langgraph-sql-agent-download-chinook-js.mdx';
+import LanggraphSqlAgentExploreDatabaseJs from '/snippets/code-samples/langgraph-sql-agent-explore-database-js.mdx';
+import LanggraphSqlAgentToolsJs from '/snippets/code-samples/langgraph-sql-agent-tools-js.mdx';
+import LanggraphSqlAgentDefineStepsJs from '/snippets/code-samples/langgraph-sql-agent-define-steps-js.mdx';
+import LanggraphSqlAgentAssembleAgentJs from '/snippets/code-samples/langgraph-sql-agent-assemble-agent-js.mdx';
+import LanggraphSqlAgentVisualizeGraphJs from '/snippets/code-samples/langgraph-sql-agent-visualize-graph-js.mdx';
+import LanggraphSqlAgentStreamAgentJs from '/snippets/code-samples/langgraph-sql-agent-stream-agent-js.mdx';
+import LanggraphSqlAgentHitlInterruptJs from '/snippets/code-samples/langgraph-sql-agent-hitl-interrupt-js.mdx';
+import LanggraphSqlAgentHitlAssembleJs from '/snippets/code-samples/langgraph-sql-agent-hitl-assemble-js.mdx';
+import LanggraphSqlAgentHitlStreamJs from '/snippets/code-samples/langgraph-sql-agent-hitl-stream-js.mdx';
+import LanggraphSqlAgentHitlResumeJs from '/snippets/code-samples/langgraph-sql-agent-hitl-resume-js.mdx';
In this tutorial we will build a custom agent that can answer questions about a SQL database using LangGraph.
@@ -34,20 +55,20 @@ We will cover the following concepts:
:::python
```bash pip
- pip install langchain langgraph langchain-community
+ pip install langchain langgraph
```
:::
:::js
```bash npm
- npm i langchain @langchain/core @langchain/classic @langchain/langgraph @langchain/openai typeorm sqlite3 zod
+ npm i langchain @langchain/core @langchain/langgraph @langchain/openai sqlite3 zod
```
```bash yarn
- yarn add langchain @langchain/core @langchain/classic @langchain/langgraph @langchain/openai typeorm sqlite3 zod
+ yarn add langchain @langchain/core @langchain/langgraph @langchain/openai sqlite3 zod
```
```bash pnpm
- pnpm add langchain @langchain/core @langchain/classic @langchain/langgraph @langchain/openai typeorm sqlite3 zod
+ pnpm add langchain @langchain/core @langchain/langgraph @langchain/openai sqlite3 zod
```
:::
@@ -80,34 +101,12 @@ You will be creating a [SQLite database](https://www.sqlitetutorial.net/sqlite-s
For convenience, we have hosted the database (`Chinook.db`) on a public GCS bucket.
:::python
-```python
-import requests, pathlib
-
-url = "https://storage.googleapis.com/benchmarks-artifacts/chinook/Chinook.db"
-local_path = pathlib.Path("Chinook.db")
-
-if local_path.exists():
- print(f"{local_path} already exists, skipping download.")
-else:
- response = requests.get(url)
- if response.status_code == 200:
- local_path.write_bytes(response.content)
- print(f"File downloaded and saved as {local_path}")
- else:
- print(f"Failed to download the file. Status code: {response.status_code}")
-```
-
-We will use a handy SQL database wrapper available in the `langchain_community` package to interact with the database. The wrapper provides a simple interface to execute SQL queries and fetch results:
-```python
-from langchain_community.utilities import SQLDatabase
+
+The following database tools are minimal wrappers for demonstration purposes only. They are not intended to be secure or used in production. Use narrowly scoped database permissions and add application-specific validation before executing model-generated SQL.
+
-tools = toolkit.get_tools()
+:::python
+We can implement database [tools](/oss/langchain/tools) as thin wrappers using the `@tool` decorator from `langchain.tools`:
-for tool in tools:
- print(f"{tool.name}: {tool.description}\n")
-```
+`.
- llm_with_tools = model.bind_tools([get_schema_tool], tool_choice="any")
- response = llm_with_tools.invoke(state["messages"])
+ = async (state) => {
- const toolCall = {
- name: "sql_db_list_tables",
- args: {},
- id: "abc123",
- type: "tool_call" as const,
- };
- const toolCallMessage = new AIMessage({
- content: "",
- tool_calls: [toolCall],
- });
-
- const toolMessage = await listTablesTool.invoke({});
- const response = new AIMessage(`Available tables: ${toolMessage}`);
-
- return { messages: [toolCallMessage, new ToolMessage({ content: toolMessage, tool_call_id: "abc123" }), response] };
-};
-
-// Example: force a model to create a tool call
-const callGetSchema: GraphNode = async (state) => {
- const llmWithTools = model.bindTools([getSchemaTool], {
- tool_choice: "any",
- });
- const response = await llmWithTools.invoke(state.messages);
-
- return { messages: [response] };
-};
-
-const topK = 5;
-
-const generateQuerySystemPrompt = `
-You are an agent designed to interact with a SQL database.
-Given an input question, create a syntactically correct ${dialect}
-query to run, then look at the results of the query and return the answer. Unless
-the user specifies a specific number of examples they wish to obtain, always limit
-your query to at most ${topK} results.
-
-You can order the results by a relevant column to return the most interesting
-examples in the database. Never query for all the columns from a specific table,
-only ask for the relevant columns given the question.
-
-DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the database.
-`;
-
-const generateQuery: GraphNode = async (state) => {
- const systemMessage = new SystemMessage(generateQuerySystemPrompt);
- // We do not force a tool call here, to allow the model to
- // respond naturally when it obtains the solution.
- const llmWithTools = model.bindTools([queryTool]);
- const response = await llmWithTools.invoke([systemMessage, ...state.messages]);
-
- return { messages: [response] };
-};
-
-const checkQuerySystemPrompt = `
-You are a SQL expert with a strong attention to detail.
-Double check the ${dialect} query for common mistakes, including:
-- Using NOT IN with NULL values
-- Using UNION when UNION ALL should have been used
-- Using BETWEEN for exclusive ranges
-- Data type mismatch in predicates
-- Properly quoting identifiers
-- Using the correct number of arguments for functions
-- Casting to the correct data type
-- Using the proper columns for joins
-
-If there are any of the above mistakes, rewrite the query. If there are no mistakes,
-just reproduce the original query.
-
-You will call the appropriate tool to execute the query after running this check.
-`;
-
-const checkQuery: GraphNode = async (state) => {
- const systemMessage = new SystemMessage(checkQuerySystemPrompt);
-
- // Generate an artificial user message to check
- const lastMessage = state.messages[state.messages.length - 1];
- if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {
- throw new Error("No tool calls found in the last message");
- }
- const toolCall = lastMessage.tool_calls[0];
- const userMessage = new HumanMessage(toolCall.args.query);
- const llmWithTools = model.bindTools([queryTool], {
- tool_choice: "any",
- });
- const response = await llmWithTools.invoke([systemMessage, userMessage]);
- // Preserve the original message ID
- response.id = lastMessage.id;
-
- return { messages: [response] };
-};
-```
+
+ = async (state) => {
We can now assemble these steps into a workflow using the [Graph API](/oss/langgraph/graph-api). We define a [conditional edge](/oss/langgraph/graph-api#conditional-edges) at the query generation step that will route to the query checker if a query is generated, or end if there are no tool calls present, such that the LLM has delivered a response to the query.
:::python
-```python
-def should_continue(state: MessagesState) -> Literal[END, "check_query"]:
- messages = state["messages"]
- last_message = messages[-1]
- if not last_message.tool_calls:
- return END
- else:
- return "check_query"
-
-
-builder = StateGraph(MessagesState)
-builder.add_node(list_tables)
-builder.add_node(call_get_schema)
-builder.add_node(get_schema_node, "get_schema")
-builder.add_node(generate_query)
-builder.add_node(check_query)
-builder.add_node(run_query_node, "run_query")
-
-builder.add_edge(START, "list_tables")
-builder.add_edge("list_tables", "call_get_schema")
-builder.add_edge("call_get_schema", "get_schema")
-builder.add_edge("get_schema", "generate_query")
-builder.add_conditional_edges(
- "generate_query",
- should_continue,
-)
-builder.add_edge("check_query", "run_query")
-builder.add_edge("run_query", "generate_query")
-agent = builder.compile()
-```
+ = (state) => {
- const messages = state.messages;
- const lastMessage = messages[messages.length - 1];
- if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {
- return END;
- } else {
- return "check_query";
- }
-};
-
-const builder = new StateGraph(MessagesState)
- .addNode("list_tables", listTables)
- .addNode("call_get_schema", callGetSchema)
- .addNode("get_schema", getSchemaNode)
- .addNode("generate_query", generateQuery)
- .addNode("check_query", checkQuery)
- .addNode("run_query", runQueryNode)
- .addEdge(START, "list_tables")
- .addEdge("list_tables", "call_get_schema")
- .addEdge("call_get_schema", "get_schema")
- .addEdge("get_schema", "generate_query")
- .addConditionalEdges("generate_query", shouldContinue)
- .addEdge("check_query", "run_query")
- .addEdge("run_query", "generate_query");
-
-const agent = builder.compile();
-```
+
+
+
:::
:::js
-```typescript
-const question = "Which genre on average has the longest tracks?";
-
-const stream = await agent.stream(
- { messages: [{ role: "user", content: question }] },
- { streamMode: "values" }
-);
-
-for await (const step of stream) {
- if (step.messages && step.messages.length > 0) {
- const lastMessage = step.messages[step.messages.length - 1];
- console.log(lastMessage.toFormattedString());
- }
-}
-```
+
+
@@ -790,123 +336,27 @@ The above implementation follows the [tool interrupt example](/oss/langgraph/int
Let's now re-assemble our graph. We will replace the programmatic check with human review. Note that we now include a [checkpointer](/oss/langgraph/persistence); this is required to pause and resume the run.
:::python
-```python
-from langgraph.checkpoint.memory import InMemorySaver
-
-def should_continue(state: MessagesState) -> Literal[END, "run_query"]:
- messages = state["messages"]
- last_message = messages[-1]
- if not last_message.tool_calls:
- return END
- else:
- return "run_query"
-
-builder = StateGraph(MessagesState)
-builder.add_node(list_tables)
-builder.add_node(call_get_schema)
-builder.add_node(get_schema_node, "get_schema")
-builder.add_node(generate_query)
-builder.add_node(run_query_node, "run_query")
-
-builder.add_edge(START, "list_tables")
-builder.add_edge("list_tables", "call_get_schema")
-builder.add_edge("call_get_schema", "get_schema")
-builder.add_edge("get_schema", "generate_query")
-builder.add_conditional_edges(
- "generate_query",
- should_continue,
-)
-builder.add_edge("run_query", "generate_query")
-checkpointer = InMemorySaver() # [!code highlight]
-agent = builder.compile(checkpointer=checkpointer) # [!code highlight]
-```
+ = (state) => {
- const messages = state.messages;
- const lastMessage = messages[messages.length - 1];
- if (!lastMessage.tool_calls || lastMessage.tool_calls.length === 0) {
- return END;
- } else {
- return "run_query";
- }
-};
-
-const runQueryNodeWithInterrupt = new ToolNode([queryToolWithInterrupt]);
-
-const builderWithHuman = new StateGraph(MessagesState)
- .addNode("list_tables", listTables)
- .addNode("call_get_schema", callGetSchema)
- .addNode("get_schema", getSchemaNode)
- .addNode("generate_query", generateQuery)
- .addNode("run_query", runQueryNodeWithInterrupt)
- .addEdge(START, "list_tables")
- .addEdge("list_tables", "call_get_schema")
- .addEdge("call_get_schema", "get_schema")
- .addEdge("get_schema", "generate_query")
- .addConditionalEdges("generate_query", shouldContinueWithHuman)
- .addEdge("run_query", "generate_query");
-
-const checkpointer = new MemorySaver(); // [!code highlight]
-const agentWithHuman = builderWithHuman.compile({ checkpointer }); // [!code highlight]
-```
+
+
+**Agent Server handles stores automatically**
+When using the [Agent Server](/langsmith/agent-server), you do not need to implement or configure stores manually. The API handles all storage infrastructure for you behind the scenes.
+
+
+
+@[InMemoryStore] is suitable for development and testing. For production, use a persistent store like `PostgresStore`, `MongoDBStore`, or `RedisStore`. All implementations extend @[BaseStore], which is the type annotation to use in node function signatures.
+
+
+## Basic usage
+
+The following code snippet shows the @[InMemoryStore] in isolation without using LangGraph:
+
+:::python
+```python
+from langgraph.store.memory import InMemoryStore
+store = InMemoryStore()
+```
+:::
+
+:::js
+```typescript
+import { MemoryStore } from "@langchain/langgraph";
+
+const memoryStore = new MemoryStore();
+```
+:::
+
+Memories are namespaced by a `tuple`, which is `(, "memories")` in the following example. The namespace can be any length and represent anything, does not have to be user specific.
+
+:::python
+```python
+user_id = "1"
+namespace_for_memory = (user_id, "memories")
+```
+:::
+
+:::js
+```typescript
+const userId = "1";
+const namespaceForMemory = [userId, "memories"];
+```
+:::
+
+Use the `store.put` method to save memories to the namespace in the store. Specify the namespace, as defined above, and a key-value pair for the memory: the key is simply a unique identifier for the memory (`memory_id`) and the value (a dictionary) is the memory itself.
+
+:::python
+```python
+memory_id = str(uuid.uuid4())
+memory = {"food_preference" : "I like pizza"}
+store.put(namespace_for_memory, memory_id, memory)
+```
+:::
+
+:::js
+```typescript
+const memoryId = crypto.randomUUID();
+const memory = { food_preference: "I like pizza" };
+await memoryStore.put(namespaceForMemory, memoryId, memory);
+```
+:::
+
+Read out memories from your namespace using the `store.search` method, which returns memories for a given user as a list, up to the `limit` argument (default `10`). With `InMemoryStore`, items are returned in insertion order, so the most recent memory is last in the list; other backends may order memories differently (see [Listing items in a namespace](#listing-items-in-a-namespace)).
+
+:::python
+```python
+memories = store.search(namespace_for_memory)
+memories[-1].dict()
+{'value': {'food_preference': 'I like pizza'},
+ 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
+ 'namespace': ['1', 'memories'],
+ 'created_at': '2024-10-02T17:22:31.590602+00:00',
+ 'updated_at': '2024-10-02T17:22:31.590605+00:00'}
+```
+
+Each memory type is a Python class ([`Item`](https://langchain-ai.github.io/langgraph/reference/store/#langgraph.store.base.Item)) with certain attributes. We can access it as a dictionary by converting with `.dict`.
+
+The attributes it has are:
+
+* `value`: The value (itself a dictionary) of this memory
+* `key`: A unique key for this memory in this namespace
+* `namespace`: A tuple of strings, the namespace of this memory type
+
+
+ While the type is `tuple[str, ...]`, it may be serialized as a list when converted to JSON (for example, `['1', 'memories']`).
+
+
+* `created_at`: Timestamp for when this memory was created
+* `updated_at`: Timestamp for when this memory was updated
+
+:::
+
+:::js
+```typescript
+const memories = await memoryStore.search(namespaceForMemory);
+memories[memories.length - 1];
+
+// {
+// value: { food_preference: 'I like pizza' },
+// key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
+// namespace: ['1', 'memories'],
+// createdAt: '2024-10-02T17:22:31.590602+00:00',
+// updatedAt: '2024-10-02T17:22:31.590605+00:00'
+// }
+```
+
+The attributes it has are:
+
+* `value`: The value of this memory
+* `key`: A unique key for this memory in this namespace
+* `namespace`: A tuple of strings, the namespace of this memory type
+
+
+ While the type is `tuple`, it may be serialized as a list when converted to JSON (for example, `['1', 'memories']`).
+
+
+* `createdAt`: Timestamp for when this memory was created
+* `updatedAt`: Timestamp for when this memory was updated
+
+:::
+
+## Listing items in a namespace
+
+:::python
+Calling [`store.search`](https://reference.langchain.com/python/langgraph/store/#langgraph.store.base.BaseStore.search) (or the async [`store.asearch`](https://reference.langchain.com/python/langgraph/store/#langgraph.store.base.BaseStore.asearch)) with no `query` and no `filter` returns the items stored under `namespace_prefix`, up to `limit`. Use this to enumerate everything in a namespace when you don't need semantic ranking.
+:::
+
+:::js
+Calling `store.search` with no `query` and no `filter` returns the items stored under the namespace prefix, up to `limit`. Use this to enumerate everything in a namespace when you don't need semantic ranking.
+:::
+
+:::python
+
+ = async (state, runtime) => {
+ // Get the user id from the config
+ const userId = runtime.context?.user_id;
+ if (!userId) throw new Error("User ID is required");
+
+ // Namespace the memory
+ const namespace = [userId, "memories"];
+
+ // ... Analyze conversation and create a new memory
+ const memory = "Some memory content";
+
+ // Create a new memory ID
+ const memoryId = crypto.randomUUID();
+
+ // We create a new memory
+ await runtime.store?.put(namespace, memoryId, { memory });
+};
+```
+:::
+
+You can also access the store from any node and use the `store.search` method to get memories. Memories are returned as a list of objects that can be converted to a dictionary.
+
+:::python
+```python
+memories[-1].dict()
+{'value': {'food_preference': 'I like pizza'},
+ 'key': '07e0caf4-1631-47b7-b15f-65515d4c1843',
+ 'namespace': ['1', 'memories'],
+ 'created_at': '2024-10-02T17:22:31.590602+00:00',
+ 'updated_at': '2024-10-02T17:22:31.590605+00:00'}
+```
+:::
+
+:::js
+```typescript
+memories[memories.length - 1];
+// {
+// value: { food_preference: 'I like pizza' },
+// key: '07e0caf4-1631-47b7-b15f-65515d4c1843',
+// namespace: ['1', 'memories'],
+// createdAt: '2024-10-02T17:22:31.590602+00:00',
+// updatedAt: '2024-10-02T17:22:31.590605+00:00'
+// }
+```
+:::
+
+You access the memories and use them in model calls.
+
+:::python
+```python
+from dataclasses import dataclass
+from langgraph.runtime import Runtime
+
+@dataclass
+class Context:
+ user_id: str
+
+async def call_model(state: MessagesState, runtime: Runtime[Context]):
+ # Get the user id from the runtime context
+ user_id = runtime.context.user_id
+
+ # Namespace the memory
+ namespace = (user_id, "memories")
+
+ # Search based on the most recent message
+ memories = await runtime.store.asearch(
+ namespace,
+ query=state["messages"][-1].content,
+ limit=3
+ )
+ info = "\n".join([d.value["memory"] for d in memories])
+
+ # ... Use memories in the model call
+```
+:::
+
+:::js
+```typescript
+const callModel: GraphNode = async (state, runtime) => {
+ // Get the user id from the config
+ const userId = runtime.context?.user_id;
+
+ // Namespace the memory
+ const namespace = [userId, "memories"];
+
+ // Search based on the most recent message
+ const memories = await runtime.store?.search(namespace, {
+ query: state.messages[state.messages.length - 1].content,
+ limit: 3,
+ });
+ const info = memories.map((d) => d.value.memory).join("\n");
+
+ // ... Use memories in the model call
+};
+```
+:::
+
+If you create a new thread, you can still access the same memories so long as the `user_id` is the same.
+
+:::python
+```python
+# Invoke the graph on a new thread
+config = {"configurable": {"thread_id": "2"}}
+
+# Let's say hi again
+for update in graph.stream(
+ {"messages": [{"role": "user", "content": "hi, tell me about my memories"}]},
+ config,
+ stream_mode="updates",
+ context=Context(user_id="1"),
+):
+ print(update)
+```
+:::
+
+:::js
+```typescript
+// Invoke the graph
+const config = { configurable: { thread_id: "2" }, context: { userId: "1" } };
+
+// Let's say hi again
+for await (const update of await graph.stream(
+ { messages: [{ role: "user", content: "hi, tell me about my memories" }] },
+ { ...config, streamMode: "updates" }
+)) {
+ console.log(update);
+}
+```
+:::
+
+When you use LangSmith locally (e.g., in [Studio](/langsmith/studio)) or [hosted](/langsmith/platform-setup), the base store is available to use by default and you do not need to specify it during graph compilation. To enable semantic search, however, you **do** need to configure the indexing settings in your `langgraph.json` file. For example:
+
+```json
+{
+ ...
+ "store": {
+ "index": {
+ "embed": "openai:text-embeddings-3-small",
+ "dims": 1536,
+ "fields": ["$"]
+ }
+ }
+}
+```
+
+See the [deployment guide](/langsmith/semantic-search) for more details and configuration options.
+
+:::python
+## Build a custom store
+
+
+To use a storage backend other than the built-in implementations, subclass @[BaseStore] and implement its required methods. The built-in @[InMemoryStore] is the simplest reference implementation.
+
+### Base contract
+
+All five async methods are required. Sync counterparts (`put`, `get`, `delete`, `search`, `list_namespaces`) are optional but recommended for compatibility with sync graph execution.
+
+| Method | Description |
+|--------|-------------|
+| `aput(namespace, key, value, index=None)` | Store or overwrite a single item |
+| `aget(namespace, key)` | Retrieve a single item by key; return `None` if missing |
+| `adelete(namespace, key)` | Delete a single item |
+| `asearch(namespace_prefix, *, query=None, filter=None, limit=10, offset=0)` | Search items under a namespace prefix; optionally by semantic query |
+| `alist_namespaces(*, prefix=None, suffix=None, max_depth=None, limit=100, offset=0)` | List namespaces matching a prefix/suffix pattern |
+
+Look up exact signatures before implementing:
+
+```python
+import inspect
+from langgraph.store.base import BaseStore
+print(inspect.getsource(BaseStore))
+```
+
+### Namespace design
+
+Namespaces are tuples of strings, e.g. `("user_id", "memories")`. Store implementations must support:
+
+- **Prefix matching**: `asearch(("alice",))` returns items under `("alice",)`, `("alice", "memories")`, and any other sub-namespace.
+- **Exact key lookup**: `aget(("alice", "memories"), "some-key")` must be O(1) or close to it.
+
+For SQL backends, a common schema:
+
+```sql
+CREATE TABLE store_items (
+ namespace TEXT[] NOT NULL,
+ key TEXT NOT NULL,
+ value JSONB NOT NULL,
+ created_at TIMESTAMPTZ DEFAULT now(),
+ updated_at TIMESTAMPTZ DEFAULT now(),
+ PRIMARY KEY (namespace, key)
+);
+
+CREATE INDEX ON store_items USING gin(namespace);
+```
+
+### Serialization
+
+Store values are plain Python dicts — no special serializer is required. Serialize with `json.dumps` / `json.loads` or a JSONB column directly. Do not store raw Python objects that are not JSON-serializable.
+
+### Semantic search support
+
+If your backend supports vector search, implement the `query` parameter on `asearch`:
+
+- Accept a `query: str | None` argument.
+- When `query` is not `None`, embed it and rank results by cosine similarity.
+- Results should include a `score` field on each `Item` when `query` is provided.
+
+If your backend does not support vector search, raise `NotImplementedError` when `query` is passed.
+
+### Testing
+
+There is currently no conformance suite for custom stores. Test against @[InMemoryStore] as the reference:
+
+```python
+import pytest
+from langgraph.store.memory import InMemoryStore
+from your_module import YourStore
+
+@pytest.fixture
+async def store():
+ async with YourStore.create() as s:
+ yield s
+
+@pytest.fixture
+def reference():
+ return InMemoryStore()
+
+async def test_put_and_get(store, reference):
+ ns = ("test", "ns")
+ for s in [store, reference]:
+ await s.aput(ns, "k1", {"val": 1})
+ item = await s.aget(ns, "k1")
+ assert item is not None
+ assert item.value == {"val": 1}
+
+async def test_delete(store, reference):
+ ns = ("test", "ns")
+ for s in [store, reference]:
+ await s.aput(ns, "k1", {"val": 1})
+ await s.adelete(ns, "k1")
+ assert await s.aget(ns, "k1") is None
+
+async def test_search_prefix(store, reference):
+ for s in [store, reference]:
+ await s.aput(("user", "memories"), "m1", {"text": "likes pizza"})
+ results = await s.asearch(("user",))
+ assert any(r.key == "m1" for r in results)
+```
+:::
+
+### Next steps
+
+- [Add a custom store to Agent Server](/langsmith/custom-store) — deploying your implementation
+- [Checkpointers](/oss/langgraph/checkpointers) — thread-scoped state persistence
diff --git a/streaming.mdx b/streaming.mdx
index 8e33c37..dbb5c4e 100644
--- a/streaming.mdx
+++ b/streaming.mdx
@@ -5,7 +5,11 @@ title: Streaming
import NostreamTagPy from '/snippets/code-samples/nostream-tag-py.mdx';
import NostreamTagJs from '/snippets/code-samples/nostream-tag-js.mdx';
-LangGraph implements a streaming system to surface real-time updates. Streaming is crucial for enhancing the responsiveness of applications built on LLMs. By displaying output progressively, even before a complete response is ready, streaming significantly improves user experience (UX), particularly when dealing with the latency of LLMs.
+
+For new applications, we recommend [event streaming](/oss/langgraph/event-streaming)—the typed-projection API introduced in LangGraph v1.2. Event streaming gives you separate iterators per projection (messages, values, subgraphs, output) so you can consume them independently instead of branching on `stream_mode` chunks.
+
+
+This page covers LangGraph's stream-mode API. It exposes graph execution through stream modes such as `updates`, `values`, `messages`, `custom`, `checkpoints`, `tasks`, and `debug`. Use it when you need direct access to graph-runtime events or specific stream-mode output.
## Get started
@@ -88,6 +92,10 @@ for await (const chunk of await graph.stream(inputs, {
```
:::
+
+Debug streaming events, inspect token-by-token LLM output, and monitor latency with [LangSmith](https://smith.langchain.com). Follow the [tracing quickstart](/langsmith/trace-with-langgraph) to get set up.
+
+
:::python
### Stream output format (v2)
@@ -338,7 +346,7 @@ class MyState:
joke: str = ""
-model = init_chat_model(model="gpt-4.1-mini")
+model = init_chat_model(model="gpt-5.4-mini")
def call_model(state: MyState):
"""Call the LLM to generate a joke about a topic"""
@@ -389,7 +397,7 @@ const MyState = new StateSchema({
joke: z.string().default(""),
});
-const model = new ChatOpenAI({ model: "gpt-4.1-mini" });
+const model = new ChatOpenAI({ model: "gpt-5.4-mini" });
const callModel: GraphNode = async (state) => {
// Call the LLM to generate a joke about a topic
@@ -428,9 +436,9 @@ You can associate `tags` with LLM invocations to filter the streamed tokens by L
from langchain.chat_models import init_chat_model
# model_1 is tagged with "joke"
-model_1 = init_chat_model(model="gpt-4.1-mini", tags=['joke'])
+model_1 = init_chat_model(model="gpt-5.4-mini", tags=['joke'])
# model_2 is tagged with "poem"
-model_2 = init_chat_model(model="gpt-4.1-mini", tags=['poem'])
+model_2 = init_chat_model(model="gpt-5.4-mini", tags=['poem'])
graph = ... # define a graph that uses these LLMs
@@ -456,12 +464,12 @@ import { ChatOpenAI } from "@langchain/openai";
// model1 is tagged with "joke"
const model1 = new ChatOpenAI({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tags: ['joke']
});
// model2 is tagged with "poem"
const model2 = new ChatOpenAI({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tags: ['poem']
});
@@ -491,9 +499,9 @@ for await (const [msg, metadata] of await graph.stream(
from langgraph.graph import START, StateGraph
# The joke_model is tagged with "joke"
- joke_model = init_chat_model(model="gpt-4.1-mini", tags=["joke"])
+ joke_model = init_chat_model(model="gpt-5.4-mini", tags=["joke"])
# The poem_model is tagged with "poem"
- poem_model = init_chat_model(model="gpt-4.1-mini", tags=["poem"])
+ poem_model = init_chat_model(model="gpt-5.4-mini", tags=["poem"])
class State(TypedDict):
@@ -550,12 +558,12 @@ for await (const [msg, metadata] of await graph.stream(
// The jokeModel is tagged with "joke"
const jokeModel = new ChatOpenAI({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tags: ["joke"]
});
// The poemModel is tagged with "poem"
const poemModel = new ChatOpenAI({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tags: ["poem"]
});
@@ -673,7 +681,7 @@ for await (const [msg, metadata] of await graph.stream(
from langgraph.graph import START, StateGraph
from langchain_openai import ChatOpenAI
- model = ChatOpenAI(model="gpt-4.1-mini")
+ model = ChatOpenAI(model="gpt-5.4-mini")
class State(TypedDict):
@@ -730,7 +738,7 @@ for await (const [msg, metadata] of await graph.stream(
import { StateGraph, StateSchema, GraphNode, START } from "@langchain/langgraph";
import * as z from "zod";
- const model = new ChatOpenAI({ model: "gpt-4.1-mini" });
+ const model = new ChatOpenAI({ model: "gpt-5.4-mini" });
const State = new StateSchema({
topic: z.string(),
@@ -1020,7 +1028,7 @@ for await (const [mode, chunk] of await graph.stream(
#### Use tool progress in React with `useStream`
-The `useStream` hook from `@langchain/langgraph-sdk/react` exposes a `toolProgress` array when you include `"tools"` in your stream modes. Each entry is a `ToolProgress` object that tracks the current state of a running tool:
+The @[`useStream`] hook from `@langchain/langgraph-sdk/react` exposes a `toolProgress` array when you include `"tools"` in your stream modes. Each entry is a `ToolProgress` object that tracks the current state of a running tool:
| Field | Description |
|-------|-------------|
@@ -1145,7 +1153,7 @@ const checkHotels = tool(
);
export const agent = createAgent({
- model: new ChatOpenAI({ model: "gpt-4o-mini" }),
+ model: new ChatOpenAI({ model: "gpt-5.4-mini" }),
tools: [searchFlights, checkHotels],
checkpointer: new MemorySaver(),
});
@@ -1272,6 +1280,65 @@ for await (const chunk of await graph.stream(
```
:::
+:::python
+
+ This applies to every `stream_mode`, including `"messages"`. Agent builders like @[`create_agent`] return a **compiled graph**, so adding one as a node turns it into a subgraph. Without `subgraphs=True`, `stream_mode="messages"` on the parent graph will not emit token chunks from the inner agent's LLM calls. Invoking `agent.stream(...)` directly will, which is why this often shows up only after wrapping.
+
+ ```python
+ from langchain.agents import create_agent
+ from langgraph.graph import END, START, StateGraph
+
+ graph = (
+ StateGraph(State)
+ .add_node("agent", create_agent(model, tools, state_schema=State))
+ .add_edge(START, "agent")
+ .add_edge("agent", END)
+ .compile()
+ )
+
+ for chunk in graph.stream(
+ {"messages": [{"role": "user", "content": "..."}]},
+ stream_mode="messages",
+ subgraphs=True, # [!code highlight]
+ version="v2",
+ ):
+ print(chunk["type"]) # "messages"
+ print(chunk["ns"]) # () for root, ("agent:",) for subgraph
+ print(chunk["data"]) # (token, metadata)
+ ```
+
+:::
+
+:::js
+
+ This applies to every `streamMode`, including `"messages"`. @[`createAgent`] returns a `ReactAgent` wrapper; pass `agent.graph` when adding it as a node so the parent treats it as a subgraph. With `subgraphs: true`, message chunks are `[namespace, [token, metadata]]`, so you can tell which subgraph emitted them.
+
+ ```typescript
+ import { createAgent } from "langchain";
+ import { END, START, StateGraph } from "@langchain/langgraph";
+
+ const agent = createAgent({ model, tools, stateSchema: State });
+
+ const graph = new StateGraph(State)
+ .addNode("agent", agent.graph)
+ .addEdge(START, "agent")
+ .addEdge("agent", END)
+ .compile();
+
+ for await (const [ns, data] of await graph.stream(
+ { messages: [{ role: "user", content: "..." }] },
+ {
+ streamMode: "messages",
+ subgraphs: true, // [!code highlight]
+ }
+ )) {
+ const [token, metadata] = data;
+ console.log(ns, token, metadata);
+ }
+ ```
+
+:::
+
:::python
```python
@@ -1618,7 +1685,7 @@ for await (const chunk of await graph.stream(
from openai import AsyncOpenAI
openai_client = AsyncOpenAI()
- model_name = "gpt-4.1-mini"
+ model_name = "gpt-5.4-mini"
async def stream_tokens(model_name: str, messages: list[dict]):
@@ -1735,7 +1802,7 @@ for await (const chunk of await graph.stream(
import OpenAI from "openai";
const openaiClient = new OpenAI();
- const modelName = "gpt-4.1-mini";
+ const modelName = "gpt-5.4-mini";
async function* streamTokens(modelName: string, messages: any[]) {
const response = await openaiClient.chat.completions.create({
@@ -1875,7 +1942,7 @@ Set `streaming=False` when initializing the model.
from langchain_openai import ChatOpenAI
# Set streaming=False to disable streaming for the chat model
- model = ChatOpenAI(model="o1-preview", streaming=False)
+ model = ChatOpenAI(model="gpt-5.5", streaming=False)
```
@@ -1888,7 +1955,7 @@ Set `streaming: false` when initializing the model.
import { ChatOpenAI } from "@langchain/openai";
const model = new ChatOpenAI({
- model: "o1-preview",
+ model: "gpt-5.5",
// Set streaming: false to disable streaming for the chat model
streaming: false,
});
@@ -2000,7 +2067,7 @@ This limits LangGraph ability to automatically propagate context, and affects La
from langgraph.graph import START, StateGraph
from langchain.chat_models import init_chat_model
- model = init_chat_model(model="gpt-4.1-mini")
+ model = init_chat_model(model="gpt-5.4-mini")
class State(TypedDict):
topic: str
diff --git a/studio.mdx b/studio.mdx
index 435dbc8..a9a7600 100644
--- a/studio.mdx
+++ b/studio.mdx
@@ -6,14 +6,14 @@ When building agents with LangChain locally, it's helpful to visualize what's ha
Studio connects to your locally running agent to show you each step your agent takes: the prompts sent to the model, tool calls and their results, and the final output. You can test different inputs, inspect intermediate states, and iterate on your agent's behavior without additional code or deployment.
-This page describes how to set up Studio with your local LangChain agent.
+This pages describes how to set up Studio with your local LangChain agent.
## Prerequisites
Before you begin, ensure you have the following:
- **A LangSmith account**: Sign up (for free) or log in at [smith.langchain.com](https://smith.langchain.com).
-- **A LangSmith API key**: Follow the [Create an API key](/langsmith/create-account-api-key#create-an-api-key) guide.
+- **A LangSmith API key**: Follow the [Create an API key](/langsmith/create-account-api-key) guide.
- If you don't want data [traced](/langsmith/observability-concepts#traces) to LangSmith, set `LANGSMITH_TRACING=false` in your application's `.env` file. With tracing disabled, no data leaves your local server.
## Set up local Agent server
@@ -55,7 +55,7 @@ def send_email(to: str, subject: str, body: str):
return f"Email sent to {to}"
agent = create_agent(
- "gpt-4.1",
+ "gpt-5.5",
tools=[send_email],
system_prompt="You are an email assistant. Always use the send_email tool.",
)
@@ -79,7 +79,7 @@ function sendEmail(to: string, subject: string, body: string): string {
}
const agent = createAgent({
- model: "gpt-4.1",
+ model: "gpt-5.5",
tools: [sendEmail],
systemPrompt: "You are an email assistant. Always use the sendEmail tool.",
});
@@ -214,7 +214,7 @@ With Studio connected to your local agent, you can iterate quickly on your agent
The development server supports hot-reloading—make changes to prompts or tool signatures in your code, and Studio reflects them immediately. Re-run conversation threads from any step to test your changes without starting over. This workflow scales from simple single-tool agents to complex multi-node graphs.
-For more information on how to run Studio, refer to the following guides in the [LangSmith docs](/langsmith/home):
+For more information on how to run Studio, refer to the following guides in the [LangSmith docs](/langsmith/observability):
- [Run application](/langsmith/use-studio#run-application)
- [Manage assistants](/langsmith/use-studio#manage-assistants)
diff --git a/test.mdx b/test.mdx
index 5fc5a75..891835e 100644
--- a/test.mdx
+++ b/test.mdx
@@ -3,7 +3,6 @@ title: Test
---
-
After you've prototyped your LangGraph agent, a natural next step is to add tests. This guide covers some useful patterns you can use when writing unit tests.
:::python
diff --git a/thinking-in-langgraph.mdx b/thinking-in-langgraph.mdx
index b763243..dacf984 100644
--- a/thinking-in-langgraph.mdx
+++ b/thinking-in-langgraph.mdx
@@ -3,6 +3,8 @@ title: Thinking in LangGraph
description: Learn how to think about building agents with LangGraph
---
+import LanggraphThinkingHitlV2Py from '/snippets/code-samples/langgraph-thinking-hitl-v2-py.mdx';
+
When you build an agent with LangGraph, you will first break it apart into discrete steps called **nodes**. Then, you will describe the different decisions and transitions from each of your nodes. Finally, you connect nodes together through a shared **state** that each node can read from and write to.
In this walkthrough, we'll guide you through the thought process of building a customer support email agent with LangGraph.
@@ -55,7 +57,7 @@ flowchart TD
H --> J[END]
I --> J[END]
- classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
+ classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
class A,B,C,D,E,F,G,H,I,J process
```
@@ -295,14 +297,17 @@ Different errors need different handling strategies:
| Transient errors (network issues, rate limits) | System (automatic) | Retry policy | Temporary failures that usually resolve on retry |
| LLM-recoverable errors (tool failures, parsing issues) | LLM | Store error in state and loop back | LLM can see the error and adjust its approach |
| User-fixable errors (missing information, unclear instructions) | Human | Pause with `interrupt()` | Need user input to proceed |
+| Recoverable failure after retries | Developer (declarative) | `error_handler` | Run a compensation/recovery branch after retry exhaustion |
| Unexpected errors | Developer | Let them bubble up | Unknown issues that need debugging |
- Add a retry policy to automatically retry network issues and rate limits:
+ Add a retry policy to automatically retry network issues and rate limits.
:::python
+ Combine with `timeout=` to cap each attempt. See [Fault tolerance](/oss/langgraph/fault-tolerance) for the full lifecycle.
+
```python
from langgraph.types import RetryPolicy
@@ -391,7 +396,9 @@ Different errors need different handling strategies:
from langgraph.types import Command
- def lookup_customer_history(state: State) -> Command[Literal["draft_response"]]:
+ def lookup_customer_history(
+ state: State
+ ) -> Command[Literal["lookup_customer_history", "draft_response"]]:
if not state.get('customer_id'):
user_input = interrupt({
"message": "Customer ID needed",
@@ -469,6 +476,41 @@ Different errors need different handling strategies:
:::
+
+
+ After retries are exhausted, run a recovery function that updates state and routes to a compensation branch.
+
+ :::python
+
+ See [Fault tolerance](/oss/langgraph/fault-tolerance#error-handling) for the full pattern.
+
+
+ `error_handler` requires `langgraph>=1.2`.
+
+
+ ```python
+ from langgraph.errors import NodeError
+ from langgraph.types import Command, RetryPolicy
+
+ def payment_error_handler(state: State, error: NodeError) -> Command:
+ return Command(
+ update={"status": f"compensated: {error.error}"},
+ goto="finalize",
+ )
+
+ workflow.add_node(
+ "charge_payment",
+ charge_payment,
+ retry_policy=RetryPolicy(max_attempts=3, retry_on=ConnectionError),
+ error_handler=payment_error_handler,
+ )
+ ```
+
+ To apply the same `retry_policy`, `timeout`, or `error_handler` to every node in a graph without repeating them on each `add_node`, use `StateGraph.set_node_defaults(...)`. Per-node values still take precedence. See [Fault tolerance](/oss/langgraph/fault-tolerance#graph-defaults).
+
+ :::
+
+
@@ -967,35 +1009,7 @@ Let's run our agent with an urgent billing issue that needs human review:
:::python
-```python
-# Test with an urgent billing issue
-initial_state = {
- "email_content": "I was charged twice for my subscription! This is urgent!",
- "sender_email": "customer@example.com",
- "email_id": "email_123",
- "messages": []
-}
-
-# Run with a thread_id for persistence
-config = {"configurable": {"thread_id": "customer_123"}}
-result = app.invoke(initial_state, config)
-# The graph will pause at human_review
-print(f"human review interrupt:{result['__interrupt__']}")
-
-# When ready, provide human input to resume
-from langgraph.types import Command
-
-human_response = Command(
- resume={
- "approved": True,
- "edited_response": "We sincerely apologize for the double charge. I've initiated an immediate refund..."
- }
-)
-
-# Resume execution
-final_result = app.invoke(human_response, config)
-print(f"Email sent successfully!")
-```
+
### Where to go from here
diff --git a/ui.mdx b/ui.mdx
index b7c0ee2..b4d631b 100644
--- a/ui.mdx
+++ b/ui.mdx
@@ -2,9 +2,9 @@
title: Agent Chat UI
---
-import AgentChatUi from '/snippets/oss/agent-chat-ui.mdx';
+import agent_chat_ui from '/snippets/oss/agent-chat-ui.mdx';
-
**Async with Python < 3.11**
@@ -583,51 +554,12 @@ async def main(inputs: dict, writer: StreamWriter) -> int: # [!code highlight]
:::
:::js
-```typescript
-import {
- entrypoint,
- MemorySaver,
- LangGraphRunnableConfig,
-} from "@langchain/langgraph";
-
-const checkpointer = new MemorySaver();
-
-const main = entrypoint(
- { checkpointer, name: "main" },
- async (
- inputs: { x: number },
- config: LangGraphRunnableConfig
- ): Promise => {
- config.writer?.("Started processing"); // [!code highlight]
- const result = inputs.x * 2;
- config.writer?.(`Result is ${result}`); // [!code highlight]
- return result;
- }
-);
-
-const config = { configurable: { thread_id: "abc" } };
-
- // [!code highlight]
-for await (const [mode, chunk] of await main.stream(
- { x: 5 },
- { streamMode: ["custom", "updates"], ...config } // [!code highlight]
-)) {
- console.log(`${mode}: ${JSON.stringify(chunk)}`);
-}
-```
+ = async (state, config) => {
@@ -1292,7 +1290,7 @@ console.log(await graph.invoke({}, { context: { myRuntimeValue: "b" } })); // [
```
claude-haiku-4-5-20251001
- gpt-4.1-mini-2025-04-14
+ gpt-5.4-mini
```
:::
@@ -1316,7 +1314,7 @@ console.log(await graph.invoke({}, { context: { myRuntimeValue: "b" } })); // [
MODELS = {
"anthropic": init_chat_model("claude-haiku-4-5-20251001"),
- "openai": init_chat_model("gpt-4.1-mini"),
+ "openai": init_chat_model("gpt-5.4-mini"),
}
def call_model(state: MessagesState, runtime: Runtime[ContextSchema]):
@@ -1372,7 +1370,7 @@ console.log(await graph.invoke({}, { context: { myRuntimeValue: "b" } })); // [
const MODELS = {
anthropic: new ChatAnthropic({ model: "claude-haiku-4-5-20251001" }),
- openai: new ChatOpenAI({ model: "gpt-4.1-mini" }),
+ openai: new ChatOpenAI({ model: "gpt-5.4-mini" }),
};
const callModel: GraphNode = async (state, config) => {
@@ -1483,14 +1481,15 @@ By default, the retry policy retries on any exception except for the following:
from langchain.chat_models import init_chat_model
from langgraph.graph import END, MessagesState, StateGraph, START
from langgraph.types import RetryPolicy
- from langchain_community.utilities import SQLDatabase
from langchain.messages import AIMessage
- db = SQLDatabase.from_uri("sqlite:///:memory:")
+ con = sqlite3.connect(":memory:")
model = init_chat_model("claude-haiku-4-5-20251001")
def query_database(state: MessagesState):
- query_result = db.run("SELECT * FROM Artist LIMIT 10;")
+ cursor = con.cursor()
+ cursor.execute("SELECT * FROM Artist LIMIT 10;")
+ query_result = str(cursor.fetchall())
return {"messages": [AIMessage(content=query_result)]}
def call_model(state: MessagesState):
@@ -1528,7 +1527,7 @@ By default, the retry policy retries on any exception except for the following:
// Create an in-memory database
const db: typeof Database.prototype = new Database(":memory:");
- const model = new ChatAnthropic({ model: "claude-3-5-sonnet-20240620" });
+ const model = new ChatAnthropic({ model: "claude-sonnet-4-6" });
const callModel: GraphNode = async (state) => {
const response = await model.invoke(state.messages);
@@ -1568,6 +1567,126 @@ By default, the retry policy retries on any exception except for the following:
:::python
+## Set node timeouts
+
+Use the `timeout` parameter with @[`add_node`] to limit how long a single async node invocation can run. Provide the timeout in seconds or as a `datetime.timedelta`.
+
+```python
+import asyncio
+from typing_extensions import TypedDict
+
+from langgraph.errors import NodeTimeoutError
+from langgraph.graph import END, START, StateGraph
+
+
+class State(TypedDict):
+ value: str
+
+
+async def call_model(state: State) -> State:
+ await asyncio.sleep(2)
+ return {"value": "done"}
+
+
+builder = StateGraph(State)
+builder.add_node("model", call_model, timeout=1.0)
+builder.add_edge(START, "model")
+builder.add_edge("model", END)
+graph = builder.compile()
+
+try:
+ await graph.ainvoke({"value": "start"})
+except NodeTimeoutError:
+ print("Node timed out")
+```
+
+Node timeouts are supported only for async nodes. If you set `timeout` on a sync node, LangGraph raises an error when the graph is compiled because sync Python execution cannot be safely canceled in-process.
+
+When a node exceeds its timeout, LangGraph raises `NodeTimeoutError`, which subclasses Python's built-in `TimeoutError`. If the node has a `retry_policy` that retries `TimeoutError` or `NodeTimeoutError`, the timed-out attempt is retried. The timeout applies to each attempt independently, so the timer resets for every retry.
+
+Timed-out attempts do not commit their buffered writes. This prevents state updates or child-task scheduling from leaking out after the timeout boundary.
+
+## Configure node timeouts
+
+The `timeout=` parameter on @[`add_node`] caps how long a single async node attempt may run. Pass a number (seconds), a `timedelta`, or a @[`TimeoutPolicy`] for finer control over run and idle timeouts. When the limit is exceeded, LangGraph raises @[`NodeTimeoutError`] and lets the retry policy decide whether to retry.
+
+
+Per-node timeouts require `langgraph>=1.2`.
+
+
+```python
+from langgraph.types import TimeoutPolicy
+
+builder.add_node(
+ "call_model",
+ call_model,
+ timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30),
+)
+```
+
+See [Fault tolerance](/oss/langgraph/fault-tolerance#timeouts) for the full timeout lifecycle, idle-timeout refresh sources, and `runtime.heartbeat()`.
+
+## Handle node errors
+
+The `error_handler=` parameter on @[`add_node`] registers a function that runs after a node fails and all retries are exhausted. The handler receives the current state and a typed @[`NodeError`] with failure context, and can route to a recovery branch via @[`Command`]:
+
+
+Node-level error handlers require `langgraph>=1.2`.
+
+
+```python
+from langgraph.errors import NodeError
+from langgraph.types import Command, RetryPolicy
+
+def payment_error_handler(state: State, error: NodeError) -> Command:
+ return Command(
+ update={"status": f"compensated: {error.error}"},
+ goto="finalize",
+ )
+
+builder.add_node(
+ "charge_payment",
+ charge_payment,
+ retry_policy=RetryPolicy(max_attempts=3, retry_on=ConnectionError),
+ error_handler=payment_error_handler,
+)
+```
+
+See [Fault tolerance](/oss/langgraph/fault-tolerance#error-handling) for compensation patterns and `Command` routing.
+
+## Set graph-wide node defaults
+
+
+Requires `langgraph>=1.2`.
+
+
+Use @[`set_node_defaults`] to set `retry_policy`, `timeout`, `cache_policy`, or `error_handler` once for every node in a graph, instead of repeating them on each @[`add_node`] call. Per-node values always win, and defaults are applied at @[`StateGraph.compile`] time:
+
+```python
+from langgraph.types import RetryPolicy, TimeoutPolicy
+
+graph = (
+ StateGraph(State)
+ .set_node_defaults(
+ retry_policy=RetryPolicy(max_attempts=3),
+ timeout=TimeoutPolicy(run_timeout=30),
+ error_handler=fallback_handler,
+ )
+ .add_node("a", node_a)
+ .add_node("b", node_b, retry_policy=RetryPolicy(max_attempts=5)) # overrides default
+ .add_edge(START, "a")
+ .compile()
+)
+```
+
+`retry_policy` and `timeout` defaults apply to every node, including error-handler nodes. `cache_policy` and `error_handler` defaults apply only to regular nodes—handlers never catch themselves, and caching a handler result is unsafe. Defaults are not inherited by subgraphs.
+
+See [Fault tolerance](/oss/langgraph/fault-tolerance#graph-defaults) for the full precedence rules and applicability table.
+
+:::
+
+:::python
+
### Access execution info inside a node
You can access execution identity and retry information via `runtime.execution_info`. This surfaces thread, run, and checkpoint identifiers as well as retry state, without needing to read from `config` directly.
@@ -1674,6 +1793,28 @@ graph = builder.compile()
Requires `deepagents>=0.5.0` (or `langgraph>=1.1.5`) for `runtime.execution_info` and `runtime.server_info`.
+### Access drain state inside a node
+
+When a [graceful shutdown](/oss/langgraph/fault-tolerance#graceful-shutdown) has been requested, `runtime.drain_requested` is `True`. Read this inside a node to skip expensive work before the next superstep boundary:
+
+```python
+from langgraph.runtime import Runtime
+
+def my_node(state: State, runtime: Runtime) -> State:
+ if runtime.drain_requested: # [!code highlight]
+ return {"status": "skipped", "reason": runtime.drain_reason}
+ return {"status": do_work()}
+```
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `drain_requested` | `bool` | `True` if `RunControl.request_drain()` has been called for this run. |
+| `drain_reason` | `str \| None` | The reason string passed to `request_drain()`, or `None` if drain was not requested. |
+
+
+Requires `langgraph>=1.2`. See [Graceful shutdown](/oss/langgraph/fault-tolerance#graceful-shutdown) for the full `RunControl` API.
+
+
:::
:::js
@@ -2586,8 +2727,10 @@ display(Image(graph.get_graph().draw_mermaid_png()))
```python
# Call the graph: here we call it to generate a list of jokes
-for step in graph.stream({"topic": "animals"}):
- print(step)
+stream = graph.stream_events({"topic": "animals"}, version="v3")
+for message in stream.messages:
+ for token in message.text:
+ print(token, end="", flush=True)
```
```
@@ -2658,8 +2801,11 @@ await fs.writeFile("graph.png", imageBuffer);
```typescript
// Call the graph: here we call it to generate a list of jokes
-for await (const step of await graph.stream({ topic: "animals" })) {
- console.log(step);
+const stream = await graph.streamEvents({ topic: "animals" }, { version: "v3" });
+for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -2725,9 +2871,8 @@ const graph = new StateGraph(State)
```
:::
-To control the recursion limit, specify `"recursionLimit"` in the config. This will raise a `GraphRecursionError`, which you can catch and handle:
-
:::python
+To control the recursion limit, specify `"recursion_limit"` in the config. This will raise a `GraphRecursionError`, which you can catch and handle:
```python
from langgraph.errors import GraphRecursionError
@@ -2739,6 +2884,7 @@ except GraphRecursionError:
:::
:::js
+To control the recursion limit, specify `"recursionLimit"` in the config. This will raise a `GraphRecursionError`, which you can catch and handle:
```typescript
import { GraphRecursionError } from "@langchain/langgraph";
@@ -3336,7 +3482,7 @@ If you are using [subgraphs](/oss/langgraph/use-subgraphs), you might want to na
:::python
```python
-def my_node(state: State) -> Command[Literal["my_other_node"]]:
+def my_node(state: State) -> Command[Literal["other_subgraph"]]:
return Command(
update={"foo": "bar"},
goto="other_subgraph", # where `other_subgraph` is a node in the parent graph
diff --git a/use-subgraphs.mdx b/use-subgraphs.mdx
index ff625c1..57b1bcf 100644
--- a/use-subgraphs.mdx
+++ b/use-subgraphs.mdx
@@ -3,6 +3,8 @@ title: Subgraphs
sidebarTitle: Subgraphs
---
+import LanggraphSubgraphsInterruptV2Py from '/snippets/code-samples/langgraph-subgraphs-interrupt-v2-py.mdx';
+
This guide explains the mechanics of using subgraphs. A subgraph is a [graph](/oss/langgraph/graph-api#graphs) that is used as a [node](/oss/langgraph/graph-api#nodes) in another graph.
Subgraphs are useful for:
@@ -169,16 +171,17 @@ const graph = builder.compile();
builder.add_edge("node_1", "node_2")
graph = builder.compile()
- for chunk in graph.stream({"foo": "foo"}, subgraphs=True, version="v2"):
- if chunk["type"] == "updates":
- print(chunk["ns"], chunk["data"])
+ stream = graph.stream_events({"foo": "foo"}, version="v3")
+ for event in stream:
+ if event["method"] == "updates":
+ print(event["params"]["namespace"], event["params"]["data"])
```
```
- () {'node_1': {'foo': 'hi! foo'}}
- ('node_2:577b710b-64ae-31fb-9455-6a4d4cc2b0b9',) {'subgraph_node_1': {'baz': 'baz'}}
- ('node_2:577b710b-64ae-31fb-9455-6a4d4cc2b0b9',) {'subgraph_node_2': {'bar': 'hi! foobaz'}}
- () {'node_2': {'foo': 'hi! foobaz'}}
+ [] {'node_1': {'foo': 'hi! foo'}}
+ ['node_2:577b710b-64ae-31fb-9455-6a4d4cc2b0b9'] {'subgraph_node_1': {'baz': 'baz'}}
+ ['node_2:577b710b-64ae-31fb-9455-6a4d4cc2b0b9'] {'subgraph_node_2': {'bar': 'hi! foobaz'}}
+ [] {'node_2': {'foo': 'hi! foobaz'}}
```
:::
@@ -224,11 +227,14 @@ const graph = builder.compile();
const graph = builder.compile();
- for await (const chunk of await graph.stream(
+ const stream = await graph.streamEvents(
{ foo: "foo" },
- { subgraphs: true }
- )) {
- console.log(chunk);
+ { subgraphs: true, version: "v3" }
+ );
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -315,17 +321,18 @@ const graph = builder.compile();
parent_graph = parent.compile()
- for chunk in parent_graph.stream({"my_key": "Bob"}, subgraphs=True, version="v2"):
- if chunk["type"] == "updates":
- print(chunk["ns"], chunk["data"])
+ stream = parent_graph.stream_events({"my_key": "Bob"}, version="v3")
+ for event in stream:
+ if event["method"] == "updates":
+ print(event["params"]["namespace"], event["params"]["data"])
```
```
- () {'parent_1': {'my_key': 'hi Bob'}}
- ('child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b', 'child_1:781bb3b1-3971-84ce-810b-acf819a03f9c') {'grandchild_1': {'my_grandchild_key': 'hi Bob, how are you'}}
- ('child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b',) {'child_1': {'my_child_key': 'hi Bob, how are you today?'}}
- () {'child': {'my_key': 'hi Bob, how are you today?'}}
- () {'parent_2': {'my_key': 'hi Bob, how are you today? bye!'}}
+ [] {'parent_1': {'my_key': 'hi Bob'}}
+ ['child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b', 'child_1:781bb3b1-3971-84ce-810b-acf819a03f9c'] {'grandchild_1': {'my_grandchild_key': 'hi Bob, how are you'}}
+ ['child:2e26e9ce-602f-862c-aa66-1ea5a4655e3b'] {'child_1': {'my_child_key': 'hi Bob, how are you today?'}}
+ [] {'child': {'my_key': 'hi Bob, how are you today?'}}
+ [] {'parent_2': {'my_key': 'hi Bob, how are you today? bye!'}}
```
:::
@@ -391,11 +398,14 @@ const graph = builder.compile();
const parentGraph = parent.compile();
- for await (const chunk of await parentGraph.stream(
+ const stream = await parentGraph.streamEvents(
{ myKey: "Bob" },
- { subgraphs: true }
- )) {
- console.log(chunk);
+ { subgraphs: true, version: "v3" }
+ );
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -529,9 +539,10 @@ const graph = builder.compile();
builder.add_edge("node_1", "node_2")
graph = builder.compile()
- for chunk in graph.stream({"foo": "foo"}, version="v2"):
- if chunk["type"] == "updates":
- print(chunk["data"])
+ stream = graph.stream_events({"foo": "foo"}, version="v3")
+ for event in stream:
+ if event["method"] == "updates" and not event["params"]["namespace"]:
+ print(event["params"]["data"])
```
```
@@ -580,8 +591,11 @@ const graph = builder.compile();
const graph = builder.compile();
- for await (const chunk of await graph.stream({ foo: "foo" })) {
- console.log(chunk);
+ const stream = await graph.streamEvents({ foo: "foo" }, { version: "v3" });
+ for await (const message of stream.messages) {
+ for await (const token of message.text) {
+ process.stdout.write(token);
+ }
}
```
@@ -603,7 +617,7 @@ The `checkpointer` parameter on `.compile()` controls subgraph persistence:
| Mode | `checkpointer=` | Behavior |
|------|-----------------|----------|
-| [Per-invocation](#per-invocation-default) | `None` (default) | Each call starts fresh and inherits the parent's checkpointer to support [interrupts](/oss/langgraph/interrupts) and [durable execution](/oss/langgraph/durable-execution) within a single call. |
+| [Per-invocation](#per-invocation-default) | `None` (default) | Each call starts fresh and inherits the parent's checkpointer to support [interrupts](/oss/langgraph/interrupts) and [durable execution](/oss/langgraph/persistence) within a single call. |
| [Per-thread](#per-thread) | `True` | State accumulates across calls on the same thread. Each call picks up where the last one left off. |
| [Stateless](#stateless) | `False` | No checkpointing at all—runs like a plain function call. No interrupts or durable execution. |
@@ -619,12 +633,12 @@ The examples below use LangChain's @[`create_agent`], which is a common way to b
### Stateful
-Stateful subgraphs inherit the parent graph's checkpointer, which enables [interrupts](/oss/langgraph/interrupts), [durable execution](/oss/langgraph/durable-execution), and state inspection. The two stateful modes differ in how long state is retained.
+Stateful subgraphs inherit the parent graph's checkpointer, which enables [interrupts](/oss/langgraph/interrupts), [persistence](/oss/langgraph/persistence), and state inspection. The two stateful modes differ in how long state is retained.
#### Per-invocation (default)
-This is the recommended mode for most applications, including [multi-agent](/oss/langchain/multi-agent) systems where subagents are invoked as tools. It supports interrupts, [durable execution](/oss/langgraph/durable-execution), and parallel calls while keeping each invocation isolated.
+This is the recommended mode for most applications, including [multi-agent](/oss/langchain/multi-agent) systems where subagents are invoked as tools. It supports [interrupts](/oss/langgraph/interrupts), [persistence](/oss/langgraph/persistence), and parallel calls while keeping each invocation isolated.
Use per-invocation persistence when each call to the subgraph is independent and the subagent doesn't need to remember anything from previous calls. This is the most common pattern, especially for [multi-agent](/oss/langchain/multi-agent) systems where subagents handle one-off requests like "look up this customer's order" or "summarize this document."
@@ -653,13 +667,13 @@ def veggie_info(veggie_name: str) -> str:
# Subagents - no checkpointer setting (inherits parent)
fruit_agent = create_agent(
- model="gpt-4.1-mini",
+ model="gpt-5.4-mini",
tools=[fruit_info],
prompt="You are a fruit expert. Use the fruit_info tool. Respond in one sentence.",
)
veggie_agent = create_agent(
- model="gpt-4.1-mini",
+ model="gpt-5.4-mini",
tools=[veggie_info],
prompt="You are a veggie expert. Use the veggie_info tool. Respond in one sentence.",
)
@@ -683,7 +697,7 @@ def ask_veggie_expert(question: str) -> str:
# Outer agent with checkpointer
agent = create_agent(
- model="gpt-4.1-mini",
+ model="gpt-5.4-mini",
tools=[ask_fruit_expert, ask_veggie_expert],
prompt=(
"You have two experts: ask_fruit_expert and ask_veggie_expert. "
@@ -705,20 +719,7 @@ agent = create_agent(
return f"Info about {fruit_name}"
```
- ```python
- config = {"configurable": {"thread_id": "1"}}
-
- # Invoke - the subagent's tool calls interrupt()
- response = agent.invoke(
- {"messages": [{"role": "user", "content": "Tell me about apples"}]},
- config=config,
- )
- # response contains __interrupt__
-
- # Resume - approve the interrupt
- response = agent.invoke(Command(resume=True), config=config) # [!code highlight]
- # Subagent message count: 4
- ```
+
Each invocation starts with a fresh subagent state. The subagent does not remember previous calls:
@@ -786,13 +787,13 @@ const veggieInfo = tool(
// Subagents - no checkpointer setting (inherits parent)
const fruitAgent = createAgent({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tools: [fruitInfo],
prompt: "You are a fruit expert. Use the fruit_info tool. Respond in one sentence.",
});
const veggieAgent = createAgent({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tools: [veggieInfo],
prompt: "You are a veggie expert. Use the veggie_info tool. Respond in one sentence.",
});
@@ -828,7 +829,7 @@ const askVeggieExpert = tool(
// Outer agent with checkpointer
const agent = createAgent({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tools: [askFruitExpert, askVeggieExpert],
prompt:
"You have two experts: ask_fruit_expert and ask_veggie_expert. " +
@@ -939,7 +940,7 @@ def fruit_info(fruit_name: str) -> str:
# Subagent with checkpointer=True for persistent state
fruit_agent = create_agent(
- model="gpt-4.1-mini",
+ model="gpt-5.4-mini",
tools=[fruit_info],
prompt="You are a fruit expert. Use the fruit_info tool. Respond in one sentence.",
checkpointer=True, # [!code highlight]
@@ -958,7 +959,7 @@ def ask_fruit_expert(question: str) -> str:
# Use ToolCallLimitMiddleware to prevent parallel calls to per-thread subagents,
# which would cause checkpoint conflicts.
agent = create_agent(
- model="gpt-4.1-mini",
+ model="gpt-5.4-mini",
tools=[ask_fruit_expert],
prompt="You have a fruit expert. ALWAYS delegate fruit questions to ask_fruit_expert.",
middleware=[ # [!code highlight]
@@ -980,20 +981,7 @@ agent = create_agent(
return f"Info about {fruit_name}"
```
- ```python
- config = {"configurable": {"thread_id": "1"}}
-
- # Invoke - the subagent's tool calls interrupt()
- response = agent.invoke(
- {"messages": [{"role": "user", "content": "Tell me about apples"}]},
- config=config,
- )
- # response contains __interrupt__
-
- # Resume - approve the interrupt
- response = agent.invoke(Command(resume=True), config=config) # [!code highlight]
- # Subagent message count: 4
- ```
+
State accumulates across invocations—the subagent remembers past conversations:
@@ -1036,11 +1024,11 @@ agent = create_agent(
)
fruit_agent = create_sub_agent(
- "gpt-4.1-mini", name="fruit_agent",
+ "gpt-5.4-mini", name="fruit_agent",
tools=[fruit_info], prompt="...", checkpointer=True,
)
veggie_agent = create_sub_agent(
- "gpt-4.1-mini", name="veggie_agent",
+ "gpt-5.4-mini", name="veggie_agent",
tools=[veggie_info], prompt="...", checkpointer=True,
)
@@ -1086,7 +1074,7 @@ const fruitInfo = tool(
// Subagent with checkpointer=true for persistent state
const fruitAgent = createAgent({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tools: [fruitInfo],
prompt: "You are a fruit expert. Use the fruit_info tool. Respond in one sentence.",
checkpointer: true, // [!code highlight]
@@ -1111,7 +1099,7 @@ const askFruitExpert = tool(
// Use toolCallLimitMiddleware to prevent parallel calls to per-thread subagents,
// which would cause checkpoint conflicts.
const agent = createAgent({
- model: "gpt-4.1-mini",
+ model: "gpt-5.4-mini",
tools: [askFruitExpert],
prompt: "You have a fruit expert. ALWAYS delegate fruit questions to ask_fruit_expert.",
middleware: [ // [!code highlight]
@@ -1192,10 +1180,10 @@ const agent = createAgent({
.compile();
}
- const fruitAgent = createSubAgent("gpt-4.1-mini", {
+ const fruitAgent = createSubAgent("gpt-5.4-mini", {
name: "fruit_agent", tools: [fruitInfo], prompt: "...", checkpointer: true,
});
- const veggieAgent = createSubAgent("gpt-4.1-mini", {
+ const veggieAgent = createSubAgent("gpt-5.4-mini", {
name: "veggie_agent", tools: [veggieInfo], prompt: "...", checkpointer: true,
});
const config = { configurable: { thread_id: "1" } };
@@ -1270,7 +1258,7 @@ const subgraph = builder.compile({ checkpointer: false }); // or true, or null
| State inspection | ⚠️ | ✅ | ❌ |
- **Interrupts (HITL)**: The subgraph can use [interrupt()](/oss/langgraph/interrupts) to pause execution and wait for user input, then resume where it left off.
-- **Multi-turn memory**: The subgraph retains its state across multiple invocations within the same [thread](/oss/langgraph/persistence#threads). Each call picks up where the last one left off rather than starting fresh.
+- **Multi-turn memory**: The subgraph retains its state across multiple invocations within the same [thread](/oss/langgraph/checkpointers#threads). Each call picks up where the last one left off rather than starting fresh.
- **Multiple calls (different subgraphs)**: Multiple different subgraph instances can be invoked within a single node without checkpoint namespace conflicts.
- **Multiple calls (same subgraph)**: The same subgraph instance can be invoked multiple times within a single node. With stateful persistence, these calls write to the same checkpoint namespace and conflict—use per-invocation persistence instead.
- **State inspection**: The subgraph's state is available via `get_state(config, subgraphs=True)` for debugging and monitoring.
@@ -1437,48 +1425,40 @@ Viewing subgraph state requires that LangGraph can **statically discover** the s
## Stream subgraph outputs
-To include outputs from subgraphs in the streamed outputs, you can set the subgraphs option in the stream method of the parent graph. This will stream outputs from both the parent graph and any subgraphs.
+To observe nested graph executions, we recommend [event streaming](/oss/langgraph/event-streaming): the `stream.subgraphs` projection discovers each nested run and exposes its `path`, `messages`, and `values` without parsing namespace strings.
:::python
-
-
- With `version="v2"`, subgraph events use the same `StreamPart` format. The `ns` field identifies the source graph:
-
- ```python
- for chunk in graph.stream(
- {"foo": "foo"},
- subgraphs=True, # [!code highlight]
- stream_mode="updates",
- version="v2", # [!code highlight]
- ):
- print(chunk["type"]) # "updates"
- print(chunk["ns"]) # () for root, ("node_2:",) for subgraph
- print(chunk["data"]) # {"node_name": {"key": "value"}}
- ```
-
-
- ```python
- for chunk in graph.stream(
- {"foo": "foo"},
- subgraphs=True, # [!code highlight]
- stream_mode="updates",
- ):
- print(chunk)
- ```
-
-
+```python
+stream = graph.stream_events({"foo": "foo"}, version="v3") # [!code highlight]
+
+for subgraph in stream.subgraphs:
+ print(subgraph.graph_name, subgraph.path)
+
+ for snapshot in subgraph.values:
+ print(subgraph.path, snapshot)
+```
+
+If you need the raw protocol events, iterate the stream directly and filter on `event["method"]` and `event["params"]["namespace"]`:
+
+```python
+stream = graph.stream_events({"foo": "foo"}, version="v3")
+for event in stream:
+ if event["method"] == "updates":
+ print(event["params"]["namespace"], event["params"]["data"])
+```
:::
:::js
```typescript
-for await (const chunk of await graph.stream(
+const stream = await graph.streamEvents(
{ foo: "foo" },
{
subgraphs: true, // [!code highlight]
- streamMode: "updates",
+ version: "v3",
}
-)) {
- console.log(chunk);
+);
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
@@ -1525,21 +1505,17 @@ for await (const chunk of await graph.stream(
builder.add_edge("node_1", "node_2")
graph = builder.compile()
- for chunk in graph.stream(
- {"foo": "foo"},
- stream_mode="updates",
- subgraphs=True, # [!code highlight]
- version="v2", # [!code highlight]
- ):
- if chunk["type"] == "updates":
- print(chunk["ns"], chunk["data"])
+ stream = graph.stream_events({"foo": "foo"}, version="v3") # [!code highlight]
+ for event in stream:
+ if event["method"] == "updates":
+ print(event["params"]["namespace"], event["params"]["data"])
```
```
- () {'node_1': {'foo': 'hi! foo'}}
- ('node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7',) {'subgraph_node_1': {'bar': 'bar'}}
- ('node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7',) {'subgraph_node_2': {'foo': 'hi! foobar'}}
- () {'node_2': {'foo': 'hi! foobar'}}
+ [] {'node_1': {'foo': 'hi! foo'}}
+ ['node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7'] {'subgraph_node_1': {'bar': 'bar'}}
+ ['node_2:e58e5673-a661-ebb0-70d4-e298a7fc28b7'] {'subgraph_node_2': {'foo': 'hi! foobar'}}
+ [] {'node_2': {'foo': 'hi! foobar'}}
```
:::
@@ -1583,14 +1559,15 @@ for await (const chunk of await graph.stream(
const graph = builder.compile();
- for await (const chunk of await graph.stream(
+ const stream = await graph.streamEvents(
{ foo: "foo" },
{
- streamMode: "updates",
subgraphs: true, // [!code highlight]
+ version: "v3",
}
- )) {
- console.log(chunk);
+ );
+ for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
diff --git a/use-time-travel.mdx b/use-time-travel.mdx
index 69cfd38..c544374 100644
--- a/use-time-travel.mdx
+++ b/use-time-travel.mdx
@@ -6,7 +6,7 @@ description: Replay past executions and fork to explore alternative paths in Lan
## Overview
-LangGraph supports time travel through [checkpoints](/oss/langgraph/persistence#checkpoints):
+LangGraph supports time travel through [checkpoints](/oss/langgraph/checkpointers#checkpoints):
- **[Replay](#replay)**: Retry from a prior checkpoint.
- **[Fork](#fork)**: Branch from a prior checkpoint with modified state to explore an alternative path.
diff --git a/workflows-agents.mdx b/workflows-agents.mdx
index 4def587..a29a467 100644
--- a/workflows-agents.mdx
+++ b/workflows-agents.mdx
@@ -3,7 +3,8 @@ title: Workflows and agents
sidebarTitle: Workflows + agents
---
-
+import WorkflowsAgentsToolRuntimeStateContextPy from "/snippets/code-samples/workflows-agents-tool-runtime-state-context-py.mdx";
+import WorkflowsAgentsToolRuntimeStateContextJs from "/snippets/code-samples/workflows-agents-tool-runtime-state-context-js.mdx";
This guide reviews common workflow and agent patterns.
@@ -14,6 +15,10 @@ This guide reviews common workflow and agent patterns.
LangGraph offers several benefits when building agents and workflows, including [persistence](/oss/langgraph/persistence), [streaming](/oss/langgraph/streaming), and support for debugging as well as [deployment](/oss/langgraph/deploy).
+
+Trace and compare these workflow patterns with [LangSmith](https://smith.langchain.com). Follow the [tracing quickstart](/langsmith/trace-with-langgraph) to see how data flows through each step. We recommend you also set up [LangSmith Engine](/langsmith/engine) which monitors your traces, detects issues, and proposes fixes.
+
+
## Setup
To build a workflow or agent, you can use [any chat model](/oss/integrations/chat) that supports structured outputs and tool calling. The following example uses Anthropic:
@@ -300,8 +305,9 @@ def prompt_chaining_workflow(topic: str):
return polish_joke(improved_joke).result()
# Invoke
-for step in prompt_chaining_workflow.stream("cats", stream_mode="updates"):
- print(step)
+stream = prompt_chaining_workflow.stream_events("cats", version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
@@ -433,12 +439,9 @@ const workflow = entrypoint(
}
);
-const stream = await workflow.stream("cats", {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await workflow.streamEvents("cats", { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
@@ -572,8 +575,9 @@ def parallel_workflow(topic: str):
).result()
# Invoke
-for step in parallel_workflow.stream("cats", stream_mode="updates"):
- print(step)
+stream = parallel_workflow.stream_events("cats", version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
@@ -693,12 +697,9 @@ const workflow = entrypoint(
);
// Invoke
-const stream = await workflow.stream("cats", {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await workflow.streamEvents("cats", { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
@@ -884,8 +885,9 @@ def router_workflow(input_: str):
return llm_call(input_).result()
# Invoke
-for step in router_workflow.stream("Write me a joke about cats", stream_mode="updates"):
- print(step)
+stream = router_workflow.stream_events("Write me a joke about cats", version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
@@ -1089,12 +1091,9 @@ const workflow = entrypoint(
);
// Invoke
-const stream = await workflow.stream("Write me a joke about cats", {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await workflow.streamEvents("Write me a joke about cats", { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
@@ -1297,12 +1296,9 @@ const workflow = entrypoint(
);
// Invoke
-const stream = await workflow.stream("Create a report on LLM scaling laws", {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await workflow.streamEvents("Create a report on LLM scaling laws", { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
@@ -1650,8 +1646,9 @@ def optimizer_workflow(topic: str):
return joke
# Invoke
-for step in optimizer_workflow.stream("Cats", stream_mode="updates"):
- print(step)
+stream = optimizer_workflow.stream_events("Cats", version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
@@ -1792,12 +1789,9 @@ const workflow = entrypoint(
);
// Invoke
-const stream = await workflow.stream("Cats", {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await workflow.streamEvents("Cats", { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
console.log("\n");
}
```
@@ -1883,7 +1877,7 @@ def llm_call(state: MessagesState):
}
-def tool_node(state: dict):
+def tool_node(state: MessagesState):
"""Performs the tool call"""
result = []
@@ -1988,8 +1982,9 @@ def agent(messages: list[BaseMessage]):
# Invoke
messages = [HumanMessage(content="Add 3 and 4.")]
-for chunk in agent.stream(messages, stream_mode="updates"):
- print(chunk)
+stream = agent.stream_events(messages, version="v3")
+for snapshot in stream.values:
+ print(snapshot)
print("\n")
```
@@ -2167,13 +2162,104 @@ const messages = [{
content: "Add 3 and 4."
}];
-const stream = await agent.stream([messages], {
- streamMode: "updates",
-});
-
-for await (const step of stream) {
- console.log(step);
+const stream = await agent.streamEvents([messages], { version: "v3" });
+for await (const snapshot of stream.values) {
+ console.log(snapshot);
}
```
:::
+
+### ToolNode
+
+@[`ToolNode`] is a prebuilt node that executes tools in LangGraph workflows. It handles parallel tool execution, error handling, and state injection automatically.
+
+Use @[`ToolNode`] when you need fine-grained control over how your graph executes tools. This is the building block that powers tool execution in many LangGraph agent patterns.
+
+:::python
+
+```python
+from langchain.tools import tool
+from langgraph.prebuilt import ToolNode
+from langgraph.graph import MessagesState, StateGraph
+
+@tool
+def search(query: str) -> str:
+ """Search for information."""
+ return f"Results for: {query}"
+
+@tool
+def calculator(expression: str) -> str:
+ """Evaluate a math expression."""
+ return str(eval(expression))
+
+builder = StateGraph(MessagesState)
+builder.add_node("tools", ToolNode([search, calculator]))
+# ... add other nodes and edges
+graph = builder.compile()
+```
+
+:::
+
+:::js
+
+```typescript
+import { ToolNode } from "@langchain/langgraph/prebuilt";
+import { tool } from "@langchain/core/tools";
+import * as z from "zod";
+
+const search = tool(
+ ({ query }) => `Results for: ${query}`,
+ {
+ name: "search",
+ description: "Search for information.",
+ schema: z.object({ query: z.string() }),
+ }
+);
+
+const calculator = tool(
+ ({ expression }) => String(eval(expression)),
+ {
+ name: "calculator",
+ description: "Evaluate a math expression.",
+ schema: z.object({ expression: z.string() }),
+ }
+);
+
+const toolNode = new ToolNode([search, calculator]);
+```
+
+:::
+
+#### Access graph state and context from tools
+
+Tools executed by `ToolNode` receive the arguments generated by the model as
+their first argument. To read graph-side data that was not generated by the
+model, use one of these options:
+
+- In Python, read state and run-scoped context from the injected
+ @[`ToolRuntime`] argument.
+- In JavaScript, read state and run-scoped context from the tool's second
+ argument, typed as @[`ToolRuntime`].
+
+
+Tools can only access the state values passed to the `ToolNode`. When
+`ToolNode` is added directly as a `StateGraph` node, that input is the current
+graph state. If you invoke a `ToolNode` manually from another node, pass the
+full state when tools need custom state fields. For example, `tool_node.invoke(state)`
+or `toolNode.invoke(state, config)` exposes the full state, while passing only
+`{"messages": state["messages"]}` or `{ messages: state.messages }` only exposes
+`messages`.
+
+
+:::python
+
+
- {!collapsed && displayContent && (
+ {open && (
)}
);
}
-
-function formatContent(value: unknown): string {
- if (typeof value === "string") return value;
- if (value == null) return "";
- return JSON.stringify(value, null, 2);
-}
```
## Streaming vs. completed content
-There are two sources of content for each node, and picking the right one
-matters for a smooth UX:
+The node card reads scoped messages for both streaming and final content. This
+avoids assuming that a graph node name matches the state key it writes to (for
+example, `do_research` writes to `research` in the playground graph):
| Source | When to use |
| --- | --- |
-| `streamingContent[node.name]` | While the node is actively streaming, this contains tokens as they arrive |
-| `stream.values[node.stateKey]` | After the node completes, this contains the final, committed output |
+| `useMessages(stream, node)` | Render node-scoped streaming and final messages |
+| `stream.values` | Read whole-graph state such as the final `synthesis` field, using the actual state key |
+
+The pattern is: show the most recent scoped AI message in the node card, and
+use `stream.values` only when you intentionally need a graph state field.
-The pattern is: show streaming content for live updates, fall back to the
-committed state value once the node is done.
+Because scoped messages are tied to the producing node, the UI can support
+parallel graph paths without guessing from message order. Each card updates from
+the stream events that belong to its node, and completed values remain available
+through `stream.values`.
```ts
-for (const node of PIPELINE_NODES) {
- const status = getNodeStatus(node, streamingContent, stream.values);
+function NodeContent({ stream, node }: { stream: AnyStream; node: SubgraphDiscoverySnapshot }) {
+ const messages = useMessages(stream, node);
+ const content = messages.find(AIMessage.isInstance)?.text ?? "";
- const content =
- status === "streaming"
- ? streamingContent[node.name]
- : stream.values?.[node.stateKey];
+ return
- {displayContent}
- {status === "streaming" && (
-
- )}
+ {lastAIMessage?.text?.trim()
+ ? {lastAIMessage.text}
+ :
Processing...
}
- {nodes.map((node) => {
- const status = getNodeStatus(node, streamingContent, values);
- return (
-
);
@@ -445,16 +388,11 @@ matters:
## Handling dynamic pipelines
Not all graphs have a fixed set of nodes. Some pipelines add or skip nodes
-based on the input. Handle this by checking which state keys actually have
-values:
+based on the input. The discovery map contains only nodes observed for the
+current thread:
```ts
-const activeNodes = PIPELINE_NODES.filter(
- (node) =>
- streamingContent[node.name] ||
- values?.[node.stateKey] ||
- node.name === currentNode
-);
+const activeNodes = [...stream.subgraphs.values()];
```
This ensures your UI only shows cards for nodes that are relevant to the
@@ -462,17 +400,21 @@ current execution, avoiding empty placeholder cards.
+
:::
:::js
-```typescript
-const question = "Which genre on average has the longest tracks?";
-
-const stream = await agent.stream(
- { messages: [{ role: "user", content: question }] },
- { streamMode: "values" }
-);
-
-for await (const step of stream) {
- if (step.messages && step.messages.length > 0) {
- const lastMessage = step.messages[step.messages.length - 1];
- console.log(lastMessage.toFormattedString());
- }
-}
-```
+
+