Menu
Language
Theme
@langchain/langgraph-sdkThe JavaScript / TypeScript SDK for talking to a LangGraph API server. Use it to create and manage assistants, threads, runs, cron schedules, and the KV store — and, most importantly, to stream graph executions in real time.
pnpm add @langchain/langgraph-sdk @langchain/core
# or: npm install @langchain/langgraph-sdk @langchain/core
# or: yarn add @langchain/langgraph-sdk @langchain/coreimport { Client } from "@langchain/langgraph-sdk";
const client = new Client({ apiUrl: "http://localhost:2024" });
// Open a thread-centric stream (the recommended way to stream).
const thread = client.threads.stream({ assistantId: "my-agent" });
await thread.run.start({
input: { messages: [{ role: "user", content: "hello" }] },
});
for await (const message of thread.messages) {
for await (const token of message.text) {
process.stdout.write(token);
}
}
console.log(await thread.output);
await thread.close();With no apiUrl, the SDK points at http://localhost:2024 (the
default langgraph dev URL).
| Sub-client | Purpose | Docs |
|---|---|---|
client.threads |
Create threads, manage state, and stream runs. | Threads · Streaming |
client.assistants |
CRUD for assistants (schemas, graphs, versions). | Assistants |
client.runs |
Trigger / join / cancel runs without streaming. | Runs (legacy) |
client.crons |
Schedule recurring runs. | Crons |
client.store |
Namespaced KV + semantic store. | Store |
client.threads.stream(...) returns a ThreadStream
with typed, lazy projections for every aspect of a run:
thread.messages / thread.toolCalls — assembled chat output.thread.values / thread.output — graph state and final answer.thread.interrupts / thread.interrupted — human-in-the-loop.thread.subgraphs / thread.subagents — nested / deep-agent work.thread.extensions.<name> — typed custom server projections.thread.audio / thread.images / thread.video / thread.files
— media.Deprecated. The generator-based streaming APIs on
client.runs.*(stream,joinStream) andclient.threads.joinStreamare preserved for backwards compatibility only. New code should useclient.threads.stream(...). See Runs (legacy) for migration guidance.
Streaming defaults to Server-Sent Events (SSE) over HTTP. You can
switch to WebSocket per-call or globally, or plug in a custom
AgentServerAdapter:
const thread = client.threads.stream({
assistantId: "my-agent",
transport: "websocket",
});See Transports for full details.
If you're building a UI, use the framework-specific packages that wrap this SDK:
@langchain/langgraph-sdk/react@langchain/langgraph-sdk/vue@langchain/langgraph-sdk/svelte@langchain/langgraph-sdk/angularUse the SDK directly when you need low-level control, run it from a non-browser environment (Node.js server, edge workers, scripts), or integrate into a framework that does not yet have a first-party adapter.
The client code is organized into sub-client modules under
src/client/:
| Path | Module |
|---|---|
client/assistants/ |
AssistantsClient |
client/threads/ |
ThreadsClient (includes the v2 stream(...) primitive) |
client/runs/ |
RunsClient (legacy streaming + CRUD) |
client/crons/ |
CronsClient |
client/store/ |
StoreClient |
client/stream/ |
ThreadStream, assemblers, transports |
client/base.ts |
BaseClient, shared config & helpers |
client/index.ts |
Main Client class & re-exports |
See CHANGELOG.md.
Public v1 name for TransportAdapter plus optional high-level
Typed error thrown through media.stream / rejected from
Incrementally assembles messages events into complete message objects.
Error wrapper for protocol-level error responses returned by the server.
Transport adapter that speaks the thread-centric protocol over HTTP
Transport adapter that speaks the thread-centric protocol over a
Async iterable handle for raw event subscriptions.
High-level wrapper around a protocol connection to a specific thread.
Public v1 name for TransportAdapter plus optional high-level
Typed error thrown through media.stream / rejected from
Incrementally assembles messages events into complete message objects.
Error wrapper for protocol-level error responses returned by the server.
Transport adapter that speaks the thread-centric protocol over HTTP
Transport adapter that speaks the thread-centric protocol over a
Async iterable handle for raw event subscriptions.
High-level wrapper around a protocol connection to a specific thread.
Transport used to stream the thread.
Manages subagent execution state.
Ref-counted, thread-aware projection registry.
Coordinates one thread's protocol-v2 stream and exposes stable
Typed error thrown through media.stream / rejected from
Framework-agnostic orchestrator for custom transport streams.
Transport used to stream the thread.
Tracks pending server-side runs created via multitaskStrategy: "enqueue".
Framework-agnostic orchestrator for LangGraph Platform streams.
Manages subagent execution state.
Check if the provided user was provided by LangGraph Studio.
Maps a protocol event method to its subscription channel.
Returns whether an event should be delivered for a subscription definition.
Resolve the LangGraph SDK Client base URL for hydration and history
Get the API key from the environment.
Resume a headless-tool batch on the v1 commands transport.
Strip headless-tool interrupts from a user-facing interrupt list.
Execute and resume all newly seen headless-tool interrupts from a values
Get the API key from the environment.
Overrides the fetch implementation used for LangSmith calls.
Parses a headless-tool interrupt value from the graph. Accepts both
Coalesce rapid headless-tool flush triggers into one microtask so parallel
Retrieves the global logger instance for LangGraph Platform.
Calculates the depth of a subagent based on its namespace.
Extracts the parent tool call ID from a namespace.
Extracts the tool call ID from a namespace path.
Strip headless-tool interrupts from a user-facing interrupt list.
Execute and resume all newly seen headless-tool interrupts from a values
Checks if a namespace indicates a subagent/subgraph message.
Parses a headless-tool interrupt value from the graph. Accepts both
Helper to send and persist UI messages. Accepts a map of component names to React components
Acquire a side-effect subscription over one or more channels.
Convenience: given the raw assembled message + the role captured
Produce a BaseMessage class instance from an in-progress or
Parse a tool-finished output payload into the tool's return value.
Parse wire-format tool payloads into structured values.
Calculates the depth of a subagent based on its namespace.
Converts plain message objects within each history state's values
Ensures all messages in an array are BaseMessage class instances.
Extracts the parent tool call ID from a namespace.
Extracts the tool call ID from a namespace path.
Checks if a namespace indicates a subagent/subgraph message.
If value looks like a HITL request object, expose both the new camelCase
If value looks like a HITL resume payload from a JS client, expose both
Normalizes HITL interrupt payloads to expose camelCase fields plus deprecated
Applies normalizeInterruptForClient to each interrupt.
Returns true when onFinish declares at least one parameter and therefore
Identity converter that keeps @langchain/core class instances.
Modules exposed by the high-level ThreadStream wrapper.
Public v1 name for TransportAdapter plus optional high-level
Mutable view of a streamed message as message and content-block events are
Shared surface across every media handle returned by
Configuration for BaseClient and the exported LangGraph SDK
Shared surface across every media handle returned by
Shared surface across every media handle returned by
Dispatch callbacks receive a freshly-started handle on its first
Dispatch callbacks receive a freshly-started handle on its first
Shared surface across every media handle returned by
Remote counterpart of an in-process run.extensions.<name> projection.
Options for ThreadStream construction.
Transport abstraction implemented by concrete client transports such as
Shared surface across every media handle returned by
Public v1 name for TransportAdapter plus optional high-level
Mutable view of a streamed message as message and content-block events are
Shared surface across every media handle returned by
Base stream interface shared by all stream types.
Configuration for BaseClient and the exported LangGraph SDK
Shared surface across every media handle returned by
Client-side implementation returned by headlessTool.implement(...).
Represents a headless tool interrupt payload emitted by LangChain's
Resume command produced by headlessToolResumeCommand /
Minimal controller surface for servicing a headless-tool resume on the
Shared surface across every media handle returned by
An interrupt thrown inside a thread.
Dispatch callbacks receive a freshly-started handle on its first
Dispatch callbacks receive a freshly-started handle on its first
Shared surface across every media handle returned by
Remote counterpart of an in-process run.extensions.<name> projection.
Options for ThreadStream construction.
Transport abstraction implemented by concrete client transports such as
Stream interface for ReactAgent instances created with createAgent.
Options for configuring an agent stream.
Stream interface for DeepAgent instances created with createDeepAgent.
Options for configuring a deep agent stream.
Shared surface across every media handle returned by
Base interface for stream-like objects.
Minimal interface matching the structure of AgentTypeConfig from @langchain/langgraph.
Base stream interface shared by all stream types.
Minimal interface matching the structure of a CompiledSubAgent from deepagents.
Minimal interface matching the structure of DeepAgentTypeConfig from deepagents.
Client-side implementation returned by headlessTool.implement(...).
Represents a headless tool interrupt payload emitted by LangChain's
Minimal interface matching the structure of a SubAgent from deepagents.
Base interface for a single subagent stream.
Represents a tool call that initiated a subagent.
Stream interface for ReactAgent instances created with createAgent.
Options for configuring an agent stream.
Stream interface for DeepAgent instances created with createDeepAgent.
Options for configuring a deep agent stream.
Transport used to stream the thread.
Handle returned by ChannelRegistry.acquire. Framework bindings
Agent-server branch: caller points useStream at an assistant on a
Reactive tool handle for framework bindings (stream.toolCalls,
Options for acquireChannelEffect. Extends
Custom-adapter branch: caller brings their own
Metadata tracked per message id. Surfaced to applications via
A projection spec describes a single logical subscription managed
Read-only fan-out of the StreamController's always-on root
Always-on root snapshot surfaced by StreamController.rootStore.
Payload for run-end callbacks.
Payload for run-start callbacks.
Options for StreamController.respondAll / framework
Options for StreamController.respond / framework respond().
Options for StreamController.stop / framework stop().
Lightweight discovery record for a subagent running inside the thread.
Lightweight discovery record for a subgraph running inside the thread.
Queued submission entry mirrored from the server-side run queue.
Options common to both transport branches of framework useStream APIs.
Public v1 name for TransportAdapter plus optional high-level
Minimal interface matching the structure of AgentTypeConfig from @langchain/langgraph.
Shared surface across every media handle returned by
Minimal interface matching the structure of a CompiledSubAgent from deepagents.
Minimal interface matching the structure of DeepAgentTypeConfig from deepagents.
Shared surface across every media handle returned by
Shared surface across every media handle returned by
Dispatch callbacks receive a freshly-started handle on its first
Dispatch callbacks receive a freshly-started handle on its first
Shared surface across every media handle returned by
Minimal interface matching the structure of a SubAgent from deepagents.
Represents a tool call that initiated a subagent.
Transport abstraction implemented by concrete client transports such as
Shared surface across every media handle returned by
Minimal interface to structurally match AgentMiddleware from langchain.
Minimal interface matching the structure of AgentTypeConfig from @langchain/langgraph.
Minimal interface matching the structure of a CompiledSubAgent from deepagents.
Minimal interface matching the structure of DeepAgentTypeConfig from deepagents.
Callbacks for resolving dynamic/reactive option values.
A single queued submission entry representing a server-side pending run.
Reactive interface exposed to framework consumers for observing
Base interface for stream-like objects.
Subagent API surface parameterised by the subagent interface type.
Minimal interface matching the structure of a SubAgent from deepagents.
Base interface for a single subagent stream.
Represents a tool call that initiated a subagent.
Transport used to stream the thread.
Payload for the stream method of the UseStreamTransport interface.
Base stream interface shared by all stream types.
Stream interface for ReactAgent instances created with createAgent.
Options for configuring an agent stream.
Stream interface for DeepAgent instances created with createDeepAgent.
Options for configuring a deep agent stream.
Emitted by MessageAssembler.consume() to describe how a message changed in
Accepted values for ThreadStreamOptions["transport"].
Built-in wire transport used by ThreadStream.
Kinds of failure that can terminate a media handle prematurely.
Block types this assembler knows how to reassemble into media handles.
Keyed map of ThreadExtension handles, typed off a declared
Unwrap a single in-process projection value to its observable payload
AI message type that can be parameterized with custom tool call types.
Template for the bag type.
Streaming custom data from inside the nodes.
Stream event with detailed debug information.
Default tool call type when no specific tool definitions are provided.
Stream event with error information.
Stream event with events occurring during execution.
Stream event with a feedback key to signed URL map. Set feedbackKeys in
Infer the Bag type from an agent, defaulting to the provided Bag.
Infer the node names from a compiled graph.
Infer the per-node return types from a compiled graph.
Infer the state type from an agent, graph, or direct state type.
Infer subagent state map from a DeepAgent.
Infer tool call types from an agent.
Infer the successful return type of a LangChain tool.
Kinds of failure that can terminate a media handle prematurely.
Block types this assembler knows how to reassemble into media handles.
Union of all message types.
Stream event with message chunks coming from LLM invocations inside nodes.
Metadata stream event with information about the run and thread
Resolves the appropriate stream interface based on the agent/graph type.
Resolves the appropriate options interface based on the agent/graph type.
import type { SubgraphCheckpointsStreamEvent } from "./types.stream.subgraph.js";
Keyed map of ThreadExtension handles, typed off a declared
Infer a tool call type from a single tool.
Infer a union of tool call types from an array of tools.
The lifecycle state of a tool call.
Represents a tool call paired with its result.
Unwrap a single in-process projection value to its observable payload
Stream event with updates to the state after each step.
Stream event with values after completion of each step.
Base state type for subagents.
Default subagent state map used when no specific subagent types are provided.
Default tool call type when no specific tool definitions are provided.
Extract the AgentTypeConfig from an agent-like type.
Extract the DeepAgentTypeConfig from a DeepAgent-like type.
Helper type to extract middleware from a SubAgent definition.
Extract the tool call type from a StateType's messages property.
Extract tool calls type from an agent's tools.
Infer the Bag type from an agent, defaulting to the provided Bag.
Extract the Subagents array type from a DeepAgent.
Infer the node names from a compiled graph.
Infer the state type from an agent, graph, or direct state type.
Helper type to extract a subagent by name from a DeepAgent.
Extract all subagent names as a string union from a DeepAgent.
Infer the state type for a specific subagent by extracting and merging
Infer subagent state map from a DeepAgent.
Infer tool call types from an agent.
Check if a type is agent-like (has ~agentTypes phantom property).
Check if a type is a DeepAgent (has ~deepAgentTypes phantom property).
Resolves the appropriate stream interface based on the agent/graph type.
Resolves the appropriate options interface based on the agent/graph type.
Create a map of subagent names to their state types.
The execution status of a subagent.
Represents a single subagent stream.
Infer a tool call type from a single tool.
Infer a union of tool call types from an array of tools.
The lifecycle state of a tool call.
Represents a tool call paired with its result.
Infer the streaming AssembledToolCall handle for a single
Unwrap the state shape from a compiled graph, a create-agent brand,
Infer the subagent → state map from a DeepAgent brand. Non-brands
Infer the discriminated union of AssembledToolCall handles
Read-only map exposed via MessageMetadataTracker.store.
Why a run's active streaming phase ended.
Minimal observable store backing every framework binding.
Read-only snapshot of the queue. The queue store hands this out
Anything with a namespace can be passed to selector hooks as a
High-level outcome of a single tool call.
Options accepted by framework useStream APIs. Discriminated on the
Widen an update type so its messages field also accepts
Default subagent state map used when no specific subagent types are provided.
Default tool call type when no specific tool definitions are provided.
Extract the AgentTypeConfig from an agent-like type.
Extract the DeepAgentTypeConfig from a DeepAgent-like type.
Helper type to extract middleware from a SubAgent definition.
Extract tool calls type from an agent's tools.
Infer the Bag type from an agent, defaulting to the provided Bag.
Extract the Subagents array type from a DeepAgent.
Infer the node names from a compiled graph.
Helper type to extract a subagent by name from a DeepAgent.
Extract all subagent names as a string union from a DeepAgent.
Infer the state type for a specific subagent by extracting and merging
Infer the successful return type of a LangChain tool.
Check if a type is agent-like (has ~agentTypes phantom property).
Check if a type is a DeepAgent (has ~deepAgentTypes phantom property).
Kinds of failure that can terminate a media handle prematurely.
Block types this assembler knows how to reassemble into media handles.
Create a map of subagent names to their state types.
Infer a tool call type from a single tool.
Widens an update type so that its messages field also accepts
Base state type for subagents.
Subagent stream interface with messages typed as BaseMessage[]
Remaps an SDK ToolCallWithResult so that the toolMessage and
Default subagent state map used when no specific subagent types are provided.
Extract the AgentTypeConfig from an agent-like type.
Extract the DeepAgentTypeConfig from a DeepAgent-like type.
Helper type to extract middleware from a SubAgent definition.
Extract the tool call type from a StateType's messages property.
Extract the tool call type from a StateType's messages property.
Maps a ThreadState<StateType>[] so that the messages field inside
Extract tool calls type from an agent's tools.
Extract the Subagents array type from a DeepAgent.
Helper type to extract and merge states from an array of middleware.
Helper type to extract a subagent by name from a DeepAgent.
Extract all subagent names as a string union from a DeepAgent.
Infer the state type for a specific subagent by extracting and merging
Check if a type is agent-like (has ~agentTypes phantom property).
Check if a type is a DeepAgent (has ~deepAgentTypes phantom property).
Create a map of subagent names to their state types.
The execution status of a subagent.
Represents a single subagent stream.
Maps a stream interface to use @langchain/core BaseMessage
Infer the Bag type from an agent, defaulting to the provided Bag.
Infer the node names from a compiled graph.
Infer the per-node return types from a compiled graph.
Infer the state type from an agent, graph, or direct state type.
Infer subagent state map from a DeepAgent.
Infer tool call types from an agent.
Resolves the appropriate stream interface based on the agent/graph type.
Resolves the appropriate options interface based on the agent/graph type.
Message stream event specific to LangGraph Server.