Running and results

What a run returns, the events it streams, and how it pauses and resumes. See Running, Streaming and Interrupts.

Results

GraphResult

GraphResult(state, step, data=dict(), thread_id=None, checkpoint_id=None, status='completed', interrupts=dict())

Outcome of Graph.ainvoke.

Attributes

state	StateT	Final state as the declared schema type.
step	int	Superstep in which the run finished or paused, counted from 0.
data	dict[str, Any]	Final state as a plain dict.
thread_id	str | None	Thread the run used.
checkpoint_id	str | None	Id of the run's last history event.
status	str	"completed" or "interrupted".
interrupts	dict[str, Interrupt]	Pending interrupts by Interrupt.key.

Stream events

StreamEvent

StreamEvent(mode, data=None, node=None, run_id=None, checkpoint_id=None, step=None, task_id=None)

One event produced while a graph runs.

Attributes

mode	str	"updates", "values", "custom", "tokens", "debug", or the terminal "interrupt" and "final".
data	InterruptEventData | FinalEventData | Any	A task's update dict or None for "updates", the merged state for "values", the emitted value for "custom" and "tokens", InterruptEventData or FinalEventData for the terminal events. Events carry copies: changing them does not change the run.
node	str | None	Node of the event; None for "values", the "state_merge" debug event and the terminal events.
run_id	str | None	Run that produced the event.
checkpoint_id	str | None	History event to load the event's state at: superstep_completed for "updates" and "values", the run's last event for the terminal events; None without a store.
step	int | None	Superstep of the run, counted from 0.
task_id	str | None	Task the event belongs to; None whenever node is None.

FinalEventData

FinalEventData(state, thread_id)

Data of the final event: final state and thread.

Attributes

state	dict[str, Any]
thread_id	str

InterruptEventData

InterruptEventData(state, thread_id, interrupts)

Data of an interrupt event: state, thread and pending interrupts.

Attributes

state	dict[str, Any]	State of the paused run.
thread_id	str	Thread of the run.
interrupts	dict[str, Interrupt]	Pending interrupts keyed by Interrupt.key.

Interrupts

interrupt

interrupt(payload, *, id) -> Any

Pause the current node until the interrupt is answered.

An on_interrupt hook may answer at once; otherwise the run pauses. On resume the node runs again from the top, and this call returns the answer. See Interrupts.

Parameters

payload	Any	Question or data for whoever answers.
id	str	Unique within one run of the node; letters, digits, _, . and -.

Returns

Any	The answer, normalized to JSON values.

Raises

ValueError	If id is empty or has other characters.
GraphExecutionError	If the node already used id in this run.
RuntimeError	If called outside a running node.
TypeError	If an on_interrupt hook returns an awaitable.

Interrupt

Interrupt(key, id, node, task_id, payload)

A pending interrupt of a paused run.

Attributes

key	str	Key for Resume(answers={key: ...}): "<task_id>:<id>"; inside a child graph, prefixed with the subgraph node's "<task_id>/".
id	str	The id passed to interrupt.
node	str	Node that paused; the subgraph node for a child graph's interrupt.
task_id	str	Task of that node.
payload	Any	Payload passed to interrupt.

Resume

Resume(value=_NO_VALUE, *, answers=None)

Answers for every pending interrupt of a paused thread.

Parameters

value	Any	Answer for the only pending interrupt.
answers	Mapping[str, Any] | None	Answers by Interrupt.key, one for each pending interrupt.

Raises

TypeError	If answers is not a mapping.
ResumeError	If both or neither of value and answers are given, or answers is empty.

Attributes

value	Any	The single answer; None when answers is given.
answers	dict[str, Any] | None	The answers by key; None when value is given.