Class Pregel<Nodes, Channels, ContextType, InputType, OutputType, StreamUpdatesType, StreamValuesType, NodeReturnType, CommandType, StreamCustom>

The Pregel class is the core runtime engine of LangGraph, implementing a message-passing graph computation model inspired by Google's Pregel system. It provides the foundation for building reliable, controllable agent workflows that can evolve state over time.

Key features:

Message passing between nodes in discrete "supersteps"
Built-in persistence layer through checkpointers
First-class streaming support for values, updates, and events
Human-in-the-loop capabilities via interrupts
Support for parallel node execution within supersteps

The Pregel class is not intended to be instantiated directly by consumers. Instead, use the following higher-level APIs:

StateGraph: The main graph class for building agent workflows
- Compiling a StateGraph will return a CompiledGraph instance, which extends Pregel
Functional API: A declarative approach using tasks and entrypoints
- A Pregel instance is returned by the entrypoint function

Example

// Using StateGraph API
const graph = new StateGraph(annotation)
  .addNode("nodeA", myNodeFunction)
  .addEdge("nodeA", "nodeB")
  .compile();

// The compiled graph is a Pregel instance
const result = await graph.invoke(input);

Example

// Using Functional API
import { task, entrypoint } from "@langchain/langgraph";
import { MemorySaver } from "@langchain/langgraph-checkpoint";

// Define tasks that can be composed
const addOne = task("add", async (x: number) => x + 1);

// Create a workflow using the entrypoint function
const workflow = entrypoint({
  name: "workflow",
  checkpointer: new MemorySaver()
}, async (numbers: number[]) => {
  // Tasks can be run in parallel
  const results = await Promise.all(numbers.map(n => addOne(n)));
  return results;
});

// The workflow is a Pregel instance
const result = await workflow.invoke([1, 2, 3]); // Returns [2, 3, 4]

Type Parameters

Nodes extends StrRecord<string, PregelNode>
Mapping of node names to their PregelNode implementations
Channels extends StrRecord<string, BaseChannel>
Mapping of channel names to their BaseChannel or ManagedValueSpec implementations
ContextType extends Record<string, any> = StrRecord<string, any>
Type of context that can be passed to the graph
InputType = PregelInputType
Type of input values accepted by the graph
OutputType = PregelOutputType
Type of output values produced by the graph
StreamUpdatesType = InputType
StreamValuesType = OutputType
NodeReturnType = unknown
CommandType = CommandInstance
StreamCustom = any

Hierarchy (View Summary)

PartialRunnable<
    InputType
    | CommandType
    | null,
    OutputType,
    PregelOptions<Nodes, Channels, ContextType>,
>
- Pregel
  - CompiledGraph

Implements

PregelInterface<Nodes, Channels, ContextType>

Properties

autoValidate

autoValidate: boolean = true

Whether to automatically validate the graph structure when it is compiled. Defaults to true.

`Optional`cache

cache?: any

Optional cache for the graph, useful for caching tasks.

channels

channels: Channels

The channels in the graph, mapping channel names to their BaseChannel or ManagedValueSpec instances

`Optional`checkpointer

checkpointer?: any

Optional checkpointer for persisting graph state. When provided, saves a checkpoint of the graph state at every superstep. When false or undefined, checkpointing is disabled, and the graph will not be able to save or restore state.

`Optional`config

config?: LangGraphRunnableConfig<Record<string, any>>

The default configuration for graph execution, can be overridden on a per-invocation basis

debug

debug: boolean = false

Whether to enable debug logging. Defaults to false.

inputChannels

inputChannels: keyof Channels | (keyof Channels)[]

The input channels for the graph. These channels receive the initial input when the graph is invoked. Can be a single channel key or an array of channel keys.

`Optional`interruptAfter

interruptAfter?: any

Optional array of node names or "all" to interrupt after executing these nodes. Used for implementing human-in-the-loop workflows.

`Optional`interruptBefore

interruptBefore?: any

Optional array of node names or "all" to interrupt before executing these nodes. Used for implementing human-in-the-loop workflows.

nodes

nodes: Nodes

The nodes in the graph, mapping node names to their PregelNode instances

outputChannels

outputChannels: keyof Channels | (keyof Channels)[]

The output channels for the graph. These channels contain the final output when the graph completes. Can be a single channel key or an array of channel keys.

`Optional`retryPolicy

retryPolicy?: RetryPolicy

Optional retry policy for handling failures in node execution

`Optional`stepTimeout

stepTimeout?: number

Optional timeout in milliseconds for the execution of each superstep

`Optional`store

store?: any

Optional long-term memory store for the graph, allows for persistence & retrieval of data across threads

`Optional`streamChannels

streamChannels?: keyof Channels | (keyof Channels)[]

Optional channels to stream. If not specified, all channels will be streamed. Can be a single channel key or an array of channel keys.

streamMode

streamMode: StreamMode[] = ...

The streaming modes enabled for this graph. Defaults to ["values"]. Supported modes:

"values": Streams the full state after each step
"updates": Streams state updates after each step
"messages": Streams messages from within nodes
"custom": Streams custom events from within nodes
"debug": Streams events related to the execution of the graph - useful for tracing & debugging graph execution

Accessors

streamChannelsAsIs

get streamChannelsAsIs(): keyof Channels | (keyof Channels)[]
Gets the channels to stream in their original format. If streamChannels is specified, returns it as-is (either single key or array). Otherwise, returns all channels in the graph as an array.

Returns keyof Channels | (keyof Channels)[]
Channel keys to stream, either as a single key or array
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:649

streamChannelsList

get streamChannelsList(): (keyof Channels)[]
Gets a list of all channels that should be streamed. If streamChannels is specified, returns those channels. Otherwise, returns all channels in the graph.

Returns (keyof Channels)[]
Array of channel keys to stream
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:632

Methods

clearCache

clearCache(): Promise<void>
Returns Promise<void>
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:2314

getGraphAsync

getGraphAsync(config: RunnableConfig): Promise<Graph>
Gets a drawable representation of the graph structure. This is an async version of getGraph() and is the preferred method to use.
Parameters
- config: RunnableConfig
  Configuration for generating the graph visualization
Returns Promise<Graph>
A representation of the graph that can be visualized
Implementation of PregelInterface.getGraphAsync
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:664

getState

getState(
config: RunnableConfig,
options?: GetStateOptions,
): Promise<StateSnapshot>
Gets the current state of the graph. Requires a checkpointer to be configured.
Parameters
- config: RunnableConfig
  Configuration for retrieving the state
- Optionaloptions: GetStateOptions
  Additional options
Returns Promise<StateSnapshot>
A snapshot of the current graph state

Throws
If no checkpointer is configured
Implementation of PregelInterface.getState
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:938

getStateHistory

getStateHistory(
config: RunnableConfig,
options?: any,
): AsyncIterableIterator<StateSnapshot>
Gets the history of graph states. Requires a checkpointer to be configured. Useful for:
- Debugging execution history
- Implementing time travel
- Analyzing graph behavior
Parameters
- config: RunnableConfig
  Configuration for retrieving the history
- Optionaloptions: any
  Options for filtering the history
Returns AsyncIterableIterator<StateSnapshot>
An async iterator of state snapshots

Throws
If no checkpointer is configured
Implementation of PregelInterface.getStateHistory
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:1000

getSubgraphs

getSubgraphs(
    namespace?: string,
    recurse?: boolean,
): Generator<
    [
        string,
        Pregel<
            any,
            any,
            StrRecord<string, any>,
            any,
            any,
            any,
            any,
            unknown,
            CommandInstance<unknown, Record<string, unknown>, string>,
            any,
        >,
    ],
>
Gets all subgraphs within this graph. A subgraph is a Pregel instance that is nested within a node of this graph.
Parameters
- Optionalnamespace: string
  Optional namespace to filter subgraphs
- Optionalrecurse: boolean
  Whether to recursively get subgraphs of subgraphs
Returns Generator<
    [
        string,
        Pregel<
            any,
            any,
            StrRecord<string, any>,
            any,
            any,
            any,
            any,
            unknown,
            CommandInstance<unknown, Record<string, unknown>, string>,
            any,
        >,
    ],
>
Generator yielding tuples of [name, subgraph]

Deprecated
Use getSubgraphsAsync instead. The async method will become the default in the next minor release.
Implementation of PregelInterface.getSubgraphs
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:677

getSubgraphsAsync

getSubgraphsAsync(
    namespace?: string,
    recurse?: boolean,
): AsyncGenerator<
    [
        string,
        Pregel<
            any,
            any,
            StrRecord<string, any>,
            any,
            any,
            any,
            any,
            unknown,
            CommandInstance<unknown, Record<string, unknown>, string>,
            any,
        >,
    ],
>
Gets all subgraphs within this graph asynchronously. A subgraph is a Pregel instance that is nested within a node of this graph.
Parameters
- Optionalnamespace: string
  Optional namespace to filter subgraphs
- Optionalrecurse: boolean
  Whether to recursively get subgraphs of subgraphs
Returns AsyncGenerator<
    [
        string,
        Pregel<
            any,
            any,
            StrRecord<string, any>,
            any,
            any,
            any,
            any,
            unknown,
            CommandInstance<unknown, Record<string, unknown>, string>,
            any,
        >,
    ],
>
AsyncGenerator yielding tuples of [name, subgraph]
Implementation of PregelInterface.getSubgraphsAsync
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:736

invoke

invoke(
    input: null | InputType | CommandType,
    options?: Partial<
        Omit<
            PregelOptions<
                Nodes,
                Channels,
                ContextType,
                undefined
                | StreamMode
                | StreamMode[],
                boolean,
                undefined | "text/event-stream",
            >,
            "encoding",
        >,
    >,
): Promise<OutputType>
Run the graph with a single input and config.
Parameters
- input: null | InputType | CommandType
  The input to the graph.
- Optionaloptions: Partial<
      Omit<
          PregelOptions<
              Nodes,
              Channels,
              ContextType,
              undefined
              | StreamMode
              | StreamMode[],
              boolean,
              undefined | "text/event-stream",
          >,
          "encoding",
      >,
  >
  The configuration to use for the run.
Returns Promise<OutputType>
Implementation of PregelInterface.invoke
Overrides PartialRunnable.invoke
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:2202

stream

stream<
    TStreamMode extends undefined
    | StreamMode
    | StreamMode[],
    TSubgraphs extends boolean,
    TEncoding extends undefined | "text/event-stream",
>(
    input: null | InputType | CommandType,
    options?: Partial<
        PregelOptions<
            Nodes,
            Channels,
            ContextType,
            TStreamMode,
            TSubgraphs,
            TEncoding,
        >,
    >,
): Promise<
    IterableReadableStream<
        StreamOutputMap<
            TStreamMode,
            TSubgraphs,
            StreamUpdatesType,
            StreamValuesType,
            keyof Nodes,
            NodeReturnType,
            StreamCustom,
            TEncoding,
        >,
    >,
>
Streams the execution of the graph, emitting state updates as they occur. This is the primary method for observing graph execution in real-time.

Stream modes:
- "values": Emits complete state after each step
- "updates": Emits only state changes after each step
- "debug": Emits detailed debug information
- "messages": Emits messages from within nodes
- "custom": Emits custom events from within nodes
- "checkpoints": Emits checkpoints from within nodes
- "tasks": Emits tasks from within nodes
Type Parameters
- TStreamMode extends undefined | StreamMode | StreamMode[]
- TSubgraphs extends boolean
- TEncoding extends undefined | "text/event-stream"
Parameters
- input: null | InputType | CommandType
  The input to start graph execution with
- Optionaloptions: Partial<
      PregelOptions<
          Nodes,
          Channels,
          ContextType,
          TStreamMode,
          TSubgraphs,
          TEncoding,
      >,
  >
  Configuration options for streaming
Returns Promise<
    IterableReadableStream<
        StreamOutputMap<
            TStreamMode,
            TSubgraphs,
            StreamUpdatesType,
            StreamValuesType,
            keyof Nodes,
            NodeReturnType,
            StreamCustom,
            TEncoding,
        >,
    >,
>
An async iterable stream of graph state updates
Implementation of PregelInterface.stream
Overrides PartialRunnable.stream
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:1839

streamEvents

streamEvents(
    input: null | InputType | CommandType,
    options: Partial<
        PregelOptions<
            Nodes,
            Channels,
            ContextType,
            undefined
            | StreamMode
            | StreamMode[],
            boolean,
            undefined | "text/event-stream",
        >,
    > & { version: "v1" | "v2" },
    streamOptions?: Omit<EventStreamCallbackHandlerInput, "autoClose">,
): IterableReadableStream<StreamEvent>
Parameters
- input: null | InputType | CommandType
- options: Partial<
      PregelOptions<
          Nodes,
          Channels,
          ContextType,
          undefined
          | StreamMode
          | StreamMode[],
          boolean,
          undefined | "text/event-stream",
      >,
  > & { version: "v1" | "v2" }
- OptionalstreamOptions: Omit<EventStreamCallbackHandlerInput, "autoClose">
Returns IterableReadableStream<StreamEvent>
Inherit Doc
Overrides PartialRunnable.streamEvents
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:1895
streamEvents(
    input: null | InputType | CommandType,
    options: Partial<
        PregelOptions<
            Nodes,
            Channels,
            ContextType,
            undefined
            | StreamMode
            | StreamMode[],
            boolean,
            undefined | "text/event-stream",
        >,
    > & { encoding: "text/event-stream"; version: "v1" | "v2" },
    streamOptions?: Omit<EventStreamCallbackHandlerInput, "autoClose">,
): IterableReadableStream<Uint8Array<ArrayBufferLike>>
Parameters
- input: null | InputType | CommandType
- options: Partial<
      PregelOptions<
          Nodes,
          Channels,
          ContextType,
          undefined
          | StreamMode
          | StreamMode[],
          boolean,
          undefined | "text/event-stream",
      >,
  > & { encoding: "text/event-stream"; version: "v1" | "v2" }
- OptionalstreamOptions: Omit<EventStreamCallbackHandlerInput, "autoClose">
Returns IterableReadableStream<Uint8Array<ArrayBufferLike>>
Inherit Doc
Overrides PartialRunnable.streamEvents
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:1903

updateState

updateState(
    inputConfig: LangGraphRunnableConfig,
    values: unknown,
    asNode?: string | keyof Nodes,
): Promise<RunnableConfig<Record<string, any>>>
Updates the state of the graph with new values. Requires a checkpointer to be configured.

This method can be used for:
- Implementing human-in-the-loop workflows
- Modifying graph state during breakpoints
- Integrating external inputs into the graph
Parameters
- inputConfig: LangGraphRunnableConfig
  Configuration for the update
- values: unknown
  The values to update the state with
- OptionalasNode: string | keyof Nodes
  Optional node name to attribute the update to
Returns Promise<RunnableConfig<Record<string, any>>>
Updated configuration

Throws
If no checkpointer is configured

Throws
If the update cannot be attributed to a node
Implementation of PregelInterface.updateState
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:1681

validate

validate(): this
Validates the graph structure to ensure it is well-formed. Checks for:
- No orphaned nodes
- Valid input/output channel configurations
- Valid interrupt configurations
Returns this
this - The Pregel instance for method chaining

Throws
If the graph structure is invalid
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:604

withConfig

withConfig(
    config: Omit<LangGraphRunnableConfig, "store" | "writer" | "interrupt">,
): Pregel<
    Nodes,
    Channels,
    ContextType,
    InputType,
    OutputType,
    StreamUpdatesType,
    StreamValuesType,
    NodeReturnType,
    CommandType,
    StreamCustom,
>
Creates a new instance of the Pregel graph with updated configuration. This method follows the immutable pattern - instead of modifying the current instance, it returns a new instance with the merged configuration.
Parameters
- config: Omit<LangGraphRunnableConfig, "store" | "writer" | "interrupt">
  The configuration to merge with the current configuration
Returns Pregel<
    Nodes,
    Channels,
    ContextType,
    InputType,
    OutputType,
    StreamUpdatesType,
    StreamValuesType,
    NodeReturnType,
    CommandType,
    StreamCustom,
>
A new Pregel instance with the merged configuration
Example
```
// Create a new instance with debug enabled
const debugGraph = graph.withConfig({ debug: true });

// Create a new instance with a specific thread ID
const threadGraph = graph.withConfig({
  configurable: { thread_id: "123" }
});
```
Implementation of PregelInterface.withConfig
Overrides PartialRunnable.withConfig
- Defined in remotes/langchain-ai/langgraphjs/v1/libs/langgraph/src/pregel/index.ts:586

Class Pregel<Nodes, Channels, ContextType, InputType, OutputType, StreamUpdatesType, StreamValuesType, NodeReturnType, CommandType, StreamCustom>

Example

Example

Type Parameters

Hierarchy (View Summary)

Implements

Index

Properties

Accessors

Methods

Properties

autoValidate

Optionalcache

channels

Optionalcheckpointer

Optionalconfig

debug

inputChannels

OptionalinterruptAfter

OptionalinterruptBefore

nodes

outputChannels

OptionalretryPolicy

OptionalstepTimeout

Optionalstore

OptionalstreamChannels

streamMode

Accessors

streamChannelsAsIs

Returns keyof Channels | (keyof Channels)[]

streamChannelsList

Returns (keyof Channels)[]

Methods

clearCache

Returns Promise<void>

getGraphAsync

Parameters

Returns Promise<Graph>

getState

Parameters

Returns Promise<StateSnapshot>

Throws

getStateHistory

Parameters

Returns AsyncIterableIterator<StateSnapshot>

Throws

getSubgraphs

Parameters

Returns Generator< [ string, Pregel< any, any, StrRecord<string, any>, any, any, any, any, unknown, CommandInstance<unknown, Record<string, unknown>, string>, any, >, ],>

Deprecated

getSubgraphsAsync

Parameters

Returns AsyncGenerator< [ string, Pregel< any, any, StrRecord<string, any>, any, any, any, any, unknown, CommandInstance<unknown, Record<string, unknown>, string>, any, >, ],>

invoke

Parameters

Returns Promise<OutputType>

stream

Type Parameters

Parameters

Returns Promise< IterableReadableStream< StreamOutputMap< TStreamMode, TSubgraphs, StreamUpdatesType, StreamValuesType, keyof Nodes, NodeReturnType, StreamCustom, TEncoding, >, >,>

streamEvents

Parameters

Returns IterableReadableStream<StreamEvent>

Inherit Doc

Parameters

Returns IterableReadableStream<Uint8Array<ArrayBufferLike>>

Inherit Doc

updateState

Parameters

Returns Promise<RunnableConfig<Record<string, any>>>

Throws

Throws

validate

Returns this

Throws

withConfig

Parameters

Returns Pregel< Nodes, Channels, ContextType, InputType, OutputType, StreamUpdatesType, StreamValuesType, NodeReturnType, CommandType, StreamCustom,>

Example

Settings

`Optional`cache

`Optional`checkpointer

`Optional`config

`Optional`interruptAfter

`Optional`interruptBefore

`Optional`retryPolicy

`Optional`stepTimeout

`Optional`store

`Optional`streamChannels

Returns Generator<
[
string,
Pregel<
any,
any,
StrRecord<string, any>,
any,
any,
any,
any,
unknown,
CommandInstance<unknown, Record<string, unknown>, string>,
any,
>,
],
>

Returns AsyncGenerator<
[
string,
Pregel<
any,
any,
StrRecord<string, any>,
any,
any,
any,
any,
unknown,
CommandInstance<unknown, Record<string, unknown>, string>,
any,
>,
],
>

Returns Promise<
IterableReadableStream<
StreamOutputMap<
TStreamMode,
TSubgraphs,
StreamUpdatesType,
StreamValuesType,
keyof Nodes,
NodeReturnType,
StreamCustom,
TEncoding,
>,
>,
>

Returns Pregel<
Nodes,
Channels,
ContextType,
InputType,
OutputType,
StreamUpdatesType,
StreamValuesType,
NodeReturnType,
CommandType,
StreamCustom,
>