CompiledGraph
An executable graph produced by StateGraph.compile. It is immutable and can be shared and run concurrently; each run is isolated by GraphConfig.threadId.
Execution model
A run advances in steps. In each step all currently active nodes run in parallel on the same input state. When there is more than one, their results are combined: the Reducer merges the nodes that returned a whole state, and the updates of the nodes that were added with a work and an update are then applied one after another, in the order those nodes were added to the graph. The outgoing edges of the nodes then decide which nodes are active in the next step. A branch that routes to END simply stops; the run completes when no nodes are active.
A node reached by several branches in the same step runs once. If the branches have different lengths, the node runs once for each step in which a branch reaches it.
Nodes run in the coroutine context of the caller. If a node fails, the other nodes of that step are cancelled and the failure is rethrown as NodeExecutionException. A node that was added with a Retry is first tried again, inside the same step and on the same state. A failure of the reducer or of the condition of an edge is rethrown as ReducerException or EdgeConditionException.
Pauses
A run pauses before or after the nodes that GraphConfig.interruptBefore and GraphConfig.interruptAfter name, and wherever a node calls interrupt. It then ends with GraphResult.Interrupted, and resume continues it. A step in which a node calls interrupt is not saved: the state the node passed is, and resume runs the nodes of that step again.
Subgraphs
A node added with StateGraph.subgraph runs another graph. That graph takes its own steps inside one step of this graph. When one of its nodes calls interrupt, this run pauses as well, and resume continues inside the subgraph, at the node that paused. A stream of this graph has the events of the subgraph too, each inside a GraphEvent.SubgraphEvent.
History
A checkpointer keeps the checkpoint of every step of a thread. history reads them, and fork continues from an earlier one on a new thread.
Failures and retries
With a checkpointer, a step is saved once its nodes have run, their results are merged and the next nodes are chosen. A step that fails at any of these points is not saved, so resume runs the whole step again, including the nodes of that step that had already finished. Make the side effects of a node safe to repeat.
The tries of a node with a Retry are not saved either. They do not count for GraphConfig.maxIterations, and a step that runs again after resume gives each of its nodes all of its tries again.
Properties
Functions
Continues from checkpoint on the new thread GraphConfig.threadId, and leaves the thread that checkpoint comes from as it is. Use it to go back to an earlier step of a run and try something else from there: another answer of a person, a corrected state, a changed node.
Returns the checkpoints of the run of GraphConfig.threadId, oldest first: the one that was saved when the run started, and one for each step that finished since. The last one is where the thread stands now. Empty when the thread has no checkpoint.
Returns where the run of GraphConfig.threadId stopped, read from its last checkpoint, without running anything. Use it to restore a screen after a restart, or to build the next input of a conversation from the state the last run ended with.
Continues the run of GraphConfig.threadId from its last checkpoint, typically after an interrupt and a human decision.
Like invoke, but returns a cold Flow that emits a GraphEvent as each node starts and finishes and after every step, and ends with GraphEvent.Completed or GraphEvent.Interrupted. What a node passes to reportProgress while it runs arrives as a GraphEvent.NodeProgress, what happens inside a subgraph as a GraphEvent.SubgraphEvent, and a try of a node that failed and is followed by another as a GraphEvent.NodeRetry. Nothing runs until the flow is collected, and each collection is a new run.
Like fork, but returns a cold Flow of GraphEvents. See stream.
Like resume, but returns a cold Flow of GraphEvents. See stream.