Looking for the JS/TS version? Check out LangGraph.js.
To help you ship LangGraph apps to production faster, check out LangSmith. LangSmith is a unified developer platform for building, testing, and monitoring LLM applications.
uv add langgraphLangGraph is a low-level orchestration framework for building, managing, and deploying long-running, stateful agents. LangGraph provides the infrastructure for durable execution, streaming, human-in-the-loop, persistence, memory, and more.
We recommend you use LangGraph when you have advanced needs that require a combination of deterministic and agentic workflows, heavy customization, and carefully controlled latency. Use LangChain when you want to quickly build agents and applications powered by LLMs using pre-built agent architectures and model integrations.
LangChain agents are built on top of LangGraph in order to provide durable execution, streaming, human-in-the-loop, persistence, and more. (You do not need to know LangGraph for basic LangChain agent usage.)
Trusted by companies shaping the future of agents – including Klarna, Replit, Elastic, and more – LangGraph is used to ship AI applications at scale.
For full documentation, see the API reference. For conceptual guides, tutorials, and examples on using LangGraph, see the LangGraph Docs. Get started with the LangGraph Quickstart.
See our Releases and Versioning policies.
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
LangGraph is inspired by Pregel and Apache Beam. The public interface draws inspiration from NetworkX. LangGraph is built by LangChain Inc, the creators of LangChain, but can be used without LangChain.
Graph lifecycle event emitted when execution pauses for interrupts.
Graph lifecycle event emitted when execution resumes from a checkpoint.
Base class for graph-level lifecycle callbacks.
Subclass this handler to observe graph lifecycle transitions that are specific to LangGraph execution, rather than generic LangChain runnable callbacks
A LangGraph specific deprecation warning.
A specific LangGraphDeprecationWarning subclass defining functionality deprecated since LangGraph v0.5.0
A specific LangGraphDeprecationWarning subclass defining functionality deprecated since LangGraph v1.0.0
A specific LangGraphDeprecationWarning subclass defining functionality deprecated since LangGraph v1.1.0
Payload for a task start event.
Payload for a task result event.
A task entry within a CheckpointPayload.
The keys present depend on the task's state:
id, name, error, stateid, name, result, interrupts, statePayload for a checkpoint event.
Stream part emitted for stream_mode="values".
data contains the full state after each step, as returned by read_channels().
Stream part emitted for stream_mode="updates".
data maps node names to their outputs. May also contain
__interrupt__ (tuple of Interrupt dicts) and __metadata__ keys.
Stream part emitted for stream_mode="messages".
data is a 2-tuple of (message, metadata) where message is a
BaseMessage (e.g. AIMessageChunk) and metadata is a dict containing
keys like
Stream part emitted for stream_mode="custom".
data is whatever value was passed to StreamWriter inside a node.
Stream part emitted for stream_mode="checkpoints".
Stream part emitted for stream_mode="tasks".
For task start events, data is a TaskPayload with id, name,
input, and triggers keys.
For task result events, data is a `TaskResultPayloa
Stream part emitted for stream_mode="debug".
Typed container returned by invoke() / ainvoke() with version="v2".
Configuration for retrying nodes.
Configuration for timing out node attempts.
Timeouts rely on asyncio cancellation. If your node uses synchronous time.sleep() or other CPU-bound work that
Configuration for caching nodes.
Configuration for how a node's run is traced.
Scope: this only transforms what the node's own run records. Child runs created
by a traced bound runnable and the root graph run are not affected. P
Information about an interrupt that occurred in a node.
interrupt_id was introduced as a propertyA Pregel task.
Cache key for a task.
Snapshot of the state of the graph at the beginning of a step.
A message or packet to send to a specific node in the graph.
The Send class is used within a StateGraph's conditional edges to
dynamically invoke a node with a custom state at the next step.
Imp
One or more commands to update the graph's state and send messages to nodes.
Bypass a reducer and write the wrapped value directly to a BinaryOperatorAggregate channel.
Receiving multiple Overwrite values for the same channel in a single super-step
will raise an `InvalidU
Read-only execution info/metadata for the execution of current thread/run/node.
Metadata injected by LangGraph Server. None when running open-source LangGraph without LangSmith deployments.
Run-scoped control surface for cooperative draining.
Intended for a single graph run. Create a fresh RunControl per run;
reusing a control after request_drain() leaves it drained.
Safe to call f
Convenience class that bundles run-scoped context and other runtime utilities.
This class is injected into graph nodes and middleware. It provides access to
context, store, stream_writer, `prev
Raised when a graph run exits early due to a drain request.
This indicates the graph stopped cooperatively at a superstep boundary
because RunControl.request_drain() was called (e.g., in response t
Raised when the graph has exhausted the maximum number of steps.
This prevents infinite loops. To increase the maximum number of steps, run your graph with a config specifying a higher `recursion_lim
Raised when attempting to update a channel with an invalid set of updates.
Troubleshooting guides:
INVALID_CONCURRENT_GRAPH_UPDATE](https://docs.langchain.com/oss/python/langgraph/INVALID_CONCURaised when a subgraph is interrupted, suppressed by the root graph. Never raised directly, or surfaced to the user.
Raised when graph receives an empty input.
Raised when the executor is unable to find a task (for distributed mode).
Failure context passed to a node-level error handler.
Inject by adding a parameter typed NodeError to a handler registered via
StateGraph.add_node(..., error_handler=...):
def handler(
Raised when a node body raises asyncio.CancelledError itself.
asyncio.CancelledError is a BaseException and the pregel runner
treats cancelled task futures as silent tear-down (e.g. when
Raised when a node invocation exceeds one of its configured timeouts.
Does not inherit from the built-in TimeoutError (a subclass of
OSError) so that the default RetryPolicy treats it as re
A message type for UI updates in LangGraph.
This TypedDict represents a UI message that can be sent to update the UI state. It contains information about the UI component to render and its properties
A message type for removing UI components in LangGraph.
This TypedDict represents a message that can be sent to remove a UI component from the current state.
A graph whose nodes communicate by reading and writing to a shared state.
The signature of each node is State -> Partial<State>.
Each state key can optionally be annotated with a reducer function
Async unbounded FIFO queue with a wait() method.
Subclassed from asyncio.Queue, adding a wait() method.
Semaphore subclass with a wait() method.
Unbounded FIFO queue with a wait() method. Adapted from pure Python implementation of queue.SimpleQueue.
Protocol to represent types that behave like TypedDicts
Version 1: using ClassVar for keys.
Protocol to represent types that behave like TypedDicts
Version 2: not using ClassVar for keys.
Protocol to represent types that behave like dataclasses.
Inspired by the private _DataclassT from dataclasses that uses a similar protocol as a bound.
TypedDict to use for extra keyword arguments, enabling type checking warnings for deprecated arguments.
A string enum.
A much simpler version of RunnableLambda that requires sync and async functions.
Sequence of Runnable, where the output of each is the input of the next.
RunnableSeq is a simpler version of RunnableSequence that is internal to
LangGraph.
Tracks which subgraphs have already loaded their pre-replay checkpoint.
During a parent replay, each subgraph's first invocation should restore the checkpoint from before the replay point. Subsequent
Central event dispatcher for the streaming infrastructure.
Owns the main event log and routes events through a transformer pipeline. StreamChannels with a name discovered in transformer projections a
Capture values events as a drainable stream of state snapshots.
Provides the run.values projection. run.output,
run.interrupted and run.interrupts are tracked directly
by the run stream and d
Capture custom events as a drainable stream of arbitrary payloads.
Nodes emit custom data via get_stream_writer(). This transformer
surfaces those events on run.custom as a StreamChannel[Any],
Capture updates events as a drainable stream of node outputs.
Surfaces stream_mode="updates" data on run.updates as a
StreamChannel[dict[str, Any]]. Each item is a dict mapping a node
(or task)
Capture messages events as ChatModelStream objects.
The messages projection yields one ChatModelStream (or
AsyncChatModelStream) per LLM call. Consumers iterate
run.messages to get stream handl
Payload of a lifecycle event surfaced on the lifecycle channel.
Auto-forwarded as lifecycle protocol events (no custom: prefix
because LifecycleTransformer is a native transformer) so remote
Surface subgraph lifecycle as lifecycle protocol events.
Pushes LifecyclePayload to a StreamChannel named lifecycle.
The channel is auto-forwarded by the mux so payloads land in the
main even
Discover subgraph invocations as in-process navigation handles.
Per discovered direct-child subgraph, builds a SubgraphRunStream
(or AsyncSubgraphRunStream) wrapping a child mini-mux scoped to
th
Capture checkpoint events as a drainable stream.
Surfaces stream_mode="checkpoints" data on run.checkpoints as
a StreamChannel[dict[str, Any]]. Each item is in the same format
as returned by `g
Capture debug events as a drainable stream.
Surfaces stream_mode="debug" data on run.debug as a
StreamChannel[dict[str, Any]]. Each item is a debug event with
step-level detail (checkpoint snap
Capture raw task events as a drainable stream.
Surfaces stream_mode="tasks" data on run.tasks as a
StreamChannel[dict[str, Any]]. Each item is a task payload
(start or result).
`LifecycleTrans
A protocol event emitted by the streaming infrastructure.
Wraps a raw stream part (values, messages, custom, etc.) in a uniform envelope with a monotonic sequence number assigned by the root StreamMu
Extension point for custom stream projections.
Transformers observe protocol events flowing through the StreamMux and build typed derived projections (StreamChannels, promises, etc.).
Set `_native =
Sync run stream with caller-driven pumping.
The caller's iteration on any projection (values, messages,
raw events, or output) drives the graph forward. No background
thread is used — the calle
Async run stream with caller-driven pumping.
Async iteration on any projection drives the graph forward — there is no background task. Concurrent consumers share a single-flight pump via an `asyncio.
Sync handle for a discovered subgraph (extends GraphRunStream).
Async handle for a discovered subgraph (extends AsyncGraphRunStream).
Single-consumer drainable queue for streaming events, with optional protocol auto-forwarding.
When constructed with a name, the StreamMux auto-wires every
push() to also inject a ProtocolEvent
A channel that waits until all named values are received before making the value available.
A channel that waits until all named values are received before making the value ready to be made available. It is only made available after finish() is called.
Stores the last value received, assumes that if multiple values are received, they are all equal.
Stores the value received in the step immediately preceding, clears after.
Stores the last value received, can receive at most one value per step.
Stores the last value received, but only made available after finish(). Once made available, clears the value.
A configurable PubSub Topic.
Stores the last value received, never checkpointed.
Reducer channel that stores only a sentinel in checkpoint blobs and reconstructs state by replaying ancestor writes through the reducer.
DeltaChannel is in beta. The API and
Stores the result of applying a binary operator to the current value and each new value.
import operator
total = Channels.BinaryOperatorAggregate(int, operator.add)Base class for all channels.
Define a LangGraph workflow using the entrypoint decorator.
Function signature
The decorated function must accept a single parameter, which serves as the input to the function. This input
A primitive that can be returned from an entrypoint.
This primitive allows to save a value to the checkpointer distinct from the return value from the entrypoint.
Exception raised when an error occurs in the remote graph.
The RemoteGraph class is a client implementation for calling remote
APIs that implement the LangGraph Server API specification.
For example, the RemoteGraph class can be used to call APIs from de
Callback handler that emits tool-call lifecycle events on the stream.
Fires on LangChain's on_tool_* callbacks and pushes to the tools
stream mode. Emits tool-started / tool-output-delta /
`t
Pregel manages the runtime behavior for LangGraph applications.
Overview
Pregel combines actors and channels into a single application. **Acto
Responsible for executing a set of Pregel tasks concurrently, committing their writes, yielding control to caller when there is output to emit, and interrupting other tasks if appropriate.
A callback handler that implements stream_mode=messages.
Collects messages from: (1) chat model stream events; and (2) node outputs.
v2 variant of StreamMessagesHandler.
Declaring _V2StreamingCallbackHandler as a base flips
BaseChatModel.invoke to route through _stream_chat_model_events
(firing on_stream_event) instead o
Implements the logic for sending writes to CONFIG_KEY_SEND. Can be used as a runnable or as a static method to call imperatively.
Implements the logic for reading state from CONFIG_KEY_READ. Usable both as a runnable as well as a static method to call imperatively.
A node in a Pregel graph. This won't be invoked as a runnable by the graph itself, but instead acts as a container for the components necessary to make a PregelExecutableTask for a node.
A context manager that runs sync tasks in the background. Uses a thread pool executor to delegate tasks to separate threads. On exit,
A context manager that runs async tasks in the background. Uses the current event loop to delegate tasks to asyncio tasks. On exit,
__cancel_on_exit__=TrueProtocol for objects containing writes to be applied to checkpoint. Implemented by PregelTaskWrites and PregelExecutableTask.
Simplest implementation of WritesProtocol, for usage with writes that don't originate from a runnable task, eg. graph input, update_state, etc.
Raised by a node to interrupt execution.
A StateGraph where every node receives a list of messages as input and returns one or more messages as output.
MessageGraph is a subclass of StateGraph whose entire state is a single, append-only* li
Build a sync graph lifecycle callback manager from a runnable config.
This helper filters config["callbacks"] down to handlers that inherit
from GraphCallbackHandler and binds the provided `run_i
Build an async graph lifecycle callback manager from a runnable config.
This helper filters config["callbacks"] down to handlers that inherit
from GraphCallbackHandler and binds the provided `run
TracePolicy helper that records an empty payload, dropping the value entirely.
Use as process_inputs and/or process_outputs on a TracePolicy to keep a node's
span and its timing while omittin
Interrupt the graph with a resumable exception from within a node.
The interrupt function enables human-in-the-loop workflows by pausing graph
execution and surfacing a value to the client. This va
Get the runtime for the current graph run.
Access LangGraph store from inside a graph node or entrypoint task at runtime.
Can be called from inside any StateGraph node or
functional API [task][langgraph.func.
Access LangGraph StreamWriter from inside a graph node or entrypoint task at runtime.
Can be called from inside any StateGraph node o
Push a new UI message to update the UI state.
This function creates and sends a UI message that will be rendered in the UI. It also updates the graph state with the new UI message.
Delete a UI message by ID from the UI state.
This function creates and sends a message to remove a UI component from the current state. It also updates the graph state to remove the UI message.
Merge two lists of UI messages, supporting removing UI messages.
This function combines two lists of UI messages, handling both regular UI messages
and remove-ui messages. When a remove-ui messag
Merges two lists of messages, updating existing messages by ID.
By default, this ensures the state is "append-only", unless the new message has the same ID as an existing message.
Write a message manually to the messages / messages-tuple stream mode.
Will automatically write to the channel specified in the state_key unless state_key is None.
Normalize a timeout value to positive-second policy fields.
Build the canonical error for using timeout with a sync target.
Default cache key function that uses the arguments and keyword arguments to generate a hashable key.
Submit a coroutine object to a given event loop.
Return an asyncio.Future to access the result.
Get the field names of a Pydantic model.
Create a pydantic model with the given field definitions.
Check if a given "complex" type is supported by pydantic.
This will return False for primitive types like int, str, etc.
The check is meant for container types like dataclasses, TypedDicts, etc.
Remove task IDs from checkpoint namespace.
Merge multiple configs into one.
Patch a config with new values.
Get a callback manager for a config.
Get an async callback manager for a config.
Return a config with all keys, merging any provided configs.
Drop langgraph's internal seq:step:* bookkeeping tags.
seq:step:N tags are added internally to mark sequence steps; everything
else (user-supplied tags and any other framework tags) is kept. Retu
Determine the default value for a field in a state schema.
Attempt to extract default values and descriptions from provided type, used for config schema.
Get Pydantic state update as a list of (key, value) tuples.
Return cached annotated keys for a Python class.
Set the child Runnable config + tracing context.
Create an asyncio.Task that inherits config as the child runnable context.
asyncio.create_task snapshots the current contextvars onto the new task,
so calling create_task while the config conte
Check if a function is async.
Check if a function is an async generator.
Coerce a runnable-like object into a Runnable.
Convert a v2 StreamPart to a ProtocolEvent.
Return True if the transformer needs a running event loop.
A transformer requires async if it explicitly opts in
(requires_async = True) or overrides any of the async-lane methods
(aprocess, `afi
Define a LangGraph task using the task decorator.
The task decorator supports both sync and async functions. To use async
Get the graph for this Pregel instance.
Add an edge to the graph.
Coerce message-like write values to typed BaseMessages with stable IDs.
Called in put_writes() before DeltaChannel writes are submitted to the checkpointer. Without this the checkpoint may store raw
Map input chunk to a sequence of pending writes in the form (channel, value).
Map input chunk to a sequence of pending writes in the form (channel, value).
Map pending writes (a sequence of tuples (channel, value)) to output chunk.
Map pending writes (a sequence of tuples (channel, value)) to output chunk.
Produce "task" events for stream_mode=debug.
Return True if the payload already wraps multiple writes from the same channel.
Folds task writes into a result dict and aggregates multiple writes to the same channel.
If the channel contains a single write, we record the write in the result dict as {channel: write}
If the ch
Produce "task_result" events for stream_mode=debug.
Remove pregel-specific keys from the config.
Produce "checkpoint" events for stream_mode=debug.
Apply writes / subgraph states to tasks to be returned in a StateSnapshot.
Get colored text.
Get bolded text.
Synthetic task id for exit-mode DeltaChannel writes.
Embeds the superstep in the first UUID group so ORDER BY task_id, idx
preserves chronological order while remaining a valid RFC UUID (required b
Return the set of DeltaChannel names that should snapshot now.
A channel snapshots when EITHER its accumulated update count reaches
snapshot_frequency OR the total supersteps since its last snapsho
Channel names written by an update_state superstep (excluding PUSH).
DeltaChannels to snapshot on the first update_state of a fresh thread.
Advance counters_since_delta_snapshot for update_state on a non-fresh thread.
Mirrors the per-superstep counter bump in _loop._put_checkpoint.
Return (channels_to_snapshot, metadata) for an update_state head.
Build a new Checkpoint from the previous one and live channel state.
For each name in channels_to_snapshot, a _DeltaSnapshot(value) blob
is written into channel_values[k]. Other delta channels
Hydrate channels from a checkpoint.
For most channels, spec.from_checkpoint(checkpoint["channel_values"][k])
is sufficient. DeltaChannel is the exception: when the channel is
absent from `channel
Async version of channels_from_checkpoint. See docstring there.
Run a task with retries.
Run a task asynchronously with retries.
Get subset of current_versions that are newer than previous_versions.
Get the values a function reaches from outside its own scope.
Check if the given string matches the format of xxh3_128_hexdigest.
A coroutine that waits for a semaphore before running another coroutine.
A function that yields control to other threads before running another function.
Check if the graph should be interrupted based on current state.
Function injected under CONFIG_KEY_READ in task config, to read current state. Used by conditional edges to read a copy of the state with reflecting the writes from that node only.
Default channel versioning function, increments the current int version.
Apply writes from a set of tasks (usually the tasks from a Pregel step) to the checkpoint and channels, and return managed values writes to be applied externally.
Prepare the set of tasks that will make up the next Pregel step.
Prepares a single task for the next Pregel step, given a task path, which uniquely identifies a PUSH or PULL task within the graph.
Prepare a push task with an attached caller. Used for the functional API.
Prepare an immediate node-level error handler task for a failed task.
Get the null version for the checkpoint, if available.
Generate a string representation of the task path.
Pop any values belonging to UntrackedValue channels in Send.arg for safe checkpointing.
Send is often called with state to be passed to the dest node, which may contain UntrackedValues at the top lev
Return the module and name of an object.