Nodes and tools

Turn functions into nodes and tools, and route from inside a node. See Nodes and context and Agents and tools.

Nodes

node

node(function=None, /, *, name=None, ref=None, timeout=None, goto=None) -> Node | Callable[[Callable[..., Any]], Node]

Turn a function into a graph node.

The function takes the state, optionally followed by a parameter annotated NodeContext. It returns a dict update, the state it received changed in place, Command, Send, END or None; see Nodes and context for what each one does.

Parameters

function	Callable[..., Any] | None	Function to wrap; omit it to pass options.
name	str | None	Node name; defaults to the function's name. Lambdas need one.
ref	str | None	Import path for Graph.to_spec.
timeout	float | None	Seconds before the node fails with NodeTimeoutError. A sync node fails only when it returns.
goto	Sequence[Node | EndSentinel | str] | None	Every target reached through Command(goto=...), Send or a returned END. Listed nodes join the flow; a name refers to the flow's node of that name, such as the node itself or one defined later. Routing anywhere else raises GraphExecutionError.

Raises

TypeError

If function is not a function or bound method, the name is blank or <lambda>, the signature is not supported, or goto is not a non-empty list of nodes, node names and END.

Node

Node(name, handler, ref=None, accepts_context=False, context_is_keyword=False, context_parameter_name='ctx', timeout=None, goto=None)

A graph step: a callable plus its name and options.

Attributes

name	str
handler	Callable[..., Any]	The wrapped function.
ref	str | None	module:qualname import path of the function, for Graph.to_spec.
accepts_context	bool	The function takes a NodeContext parameter.
context_is_keyword	bool	That parameter is keyword-only.
context_parameter_name	str	Name of that parameter.
timeout	float | None	Seconds before the node fails with NodeTimeoutError.
goto	tuple[Node | EndSentinel | str, ...] | None	Targets the node may reach through Command(goto=...), Send or a returned END, as declared; names are resolved by Graph.flow.
metadata	NodeMetadata	The node's options as a NodeMetadata.

NodeMetadata

NodeMetadata(*, name, ref=None, accepts_context=False, context_is_keyword=False, context_parameter_name='ctx', timeout=None, goto=None)

Serializable description of a node's options.

Attributes

name	str
ref	str | None	module:qualname import path of the node function.
accepts_context	bool	The function takes a NodeContext parameter.
context_is_keyword	bool	That parameter is keyword-only.
context_parameter_name	str	Name of that parameter.
timeout	float | None	Seconds before the node fails with NodeTimeoutError.
goto	tuple[str, ...] | None	Names of the declared goto targets, "END" for the end.

NodeContext

NodeContext(graph_name, run_id, thread_id, step, node, branch_id='main', root_run_id='', task_id='', middleware=(), workspace=None, state_store=None, state_schema=None, stream_modes=(), cache=dict(), resume_values=dict())

Run information and helpers for a running node.

Attributes

graph_name	str	Name of the graph.
run_id	str	Id of this run.
thread_id	str | None	Thread of the run.
step	int	Superstep, counted from 0.
node	str	Name of the node.
branch_id	str	History branch of the run.
root_run_id	str	Id of the outermost run when the graph runs inside another one.
task_id	str	Id of this task within the superstep.
middleware	tuple[Any, ...]	Middleware of the run, in order.
workspace	Any	The graph's workspace.
state_store	Any	Store of the run's history.
state_schema	Any	Schema of the graph state.
stream_modes	tuple[str, ...]	Stream modes the caller asked for.
cache	dict[str, Any]	Saved with the task when it pauses and given back on resume.
resume_values	Mapping[str, Any]	Answers to this task's interrupts by interrupt key, read-only.
context	Any	The context= object of the run; never stored, so pass it again on resume.

Methods

emit(data)

Emit a "custom" stream event with this node, step and task.

emit(data) -> None

Parameters

data

Any

Event payload.

async spawn(tasks, ...)

Start sub-agents concurrently; they belong to this run.

async spawn(tasks, *, thread_prefix=None) -> list[AgentHandle]

A run that finishes or pauses with sub-agents never gathered cancels them and raises GraphExecutionError; a run that fails or is closed early cancels them too. To wait in a later run, use submit.

Parameters

tasks	list[AgentTask]	One task per sub-agent: the graph, its input and options.
thread_prefix	str | None	Prefix of the threads "<prefix>:sub:<handle id>"; defaults to this run's thread id.

Raises

TypeError	If a task has no input.
ValueError	If thread_prefix is empty.

async gather(handles, ...)

Wait for sub-agents started with spawn.

async gather(handles, *, timeout=None, return_exceptions=False) -> list[AgentResult]

Parameters

handles	Sequence[AgentHandle | str]	Handles, or ids of sub-agents spawned in this run, by any node. Ids do not resolve after a pause.
timeout	float | None	Seconds to wait before cancelling the unfinished sub-agents.
return_exceptions	bool	Return failed and cancelled results instead of raising.

Raises

AgentGroupError	If a sub-agent failed or was cancelled and return_exceptions is False.
AgentTimeoutError	If the timeout expires first.
AgentHandleLostError	If a handle was not spawned in this run or was already gathered.

async submit(tasks, ...)

Start sub-agents on a background executor.

async submit(tasks, *, executor, thread_prefix=None) -> list[DurableAgentHandle]

Parameters

tasks	list[AgentTask]	One task per sub-agent: the graph, its input and options.
executor	AgentExecutor	Executor that runs the sub-agents, such as AsyncioExecutor.
thread_prefix	str | None	Prefix of the threads "<prefix>:bg:<handle id>"; defaults to this run's thread id.

Raises

TypeError

If a task has no input; checked before any task starts.

async poll_agents(handles, ...)

Check background sub-agents without waiting.

async poll_agents(handles, *, executor) -> list[AgentResult | None]

Parameters

handles	list[DurableAgentHandle]	Handles returned by submit.
executor	AgentExecutor	The executor the sub-agents were submitted to.

Returns

list[AgentResult or None]

None for sub-agents that are still running.

Raises

AgentHandleLostError

If the executor does not know a handle.

Routing from a node

Command

Command(update=None, goto=None)

Node return value that updates state and routes.

Attributes

update	Mapping[str, Any] | None	Update applied through the reducers; not the state object the node received.
goto	Any	Next targets, replacing the node's edges. [] routes nowhere; None follows the edges.

Send

Send(node, payload=None)

Route to a node with its own input payload.

Attributes

node	Any	Target node.
payload	Any	State fields laid over the current state for that task only, without reducers. Keys must be state fields, unless the state is a plain dict; a model gives only the fields set on it. When the node returns the Send, a Replace, a RemoveMessage or an invalid value raises StateUpdateError, and a value that does not survive being stored as JSON raises StateStoreError.

Tools

tool

tool(function=None, /, *, name=None, description=None, input_model=None) -> Tool | Callable[[Callable[..., Any]], Tool]

Turn a function into a tool.

The arguments are validated against a model built from the type hints, which rejects unknown arguments. A parameter annotated exactly as ToolContext receives the tool context and is hidden from the model. Sync functions run in a worker thread.

Parameters

function	Callable[..., Any] | None	Function to wrap; omit it to use the decorator with options.
name	str | None	Tool name, matching ^[a-zA-Z0-9_-]{1,64}$; defaults to function.__name__. Lambdas need one.
description	str | None	Description sent to the model; defaults to the function's own docstring, all of it.
input_model	type[BaseModel] | None	Argument model to use instead of the generated one; its fields must be exactly the function's parameters, without the ToolContext one.

Raises

TypeError

If function is not a function or bound method, the name is missing or invalid, the description is missing or blank, the function takes *args or **kwargs, a parameter has no annotation and no input_model is given, input_model does not match the parameters, or ToolContext appears other than as one parameter annotated exactly ToolContext (an unannotated ctx or context counts).

Tool

Tool(function, metadata)

A callable exposed to models, with validated input and output.

tool() builds one from a function and its type hints.

Parameters

function	Callable[..., Any]	The function the tool calls.
metadata	ToolMetadata	Name, description and schemas of the tool, kept as metadata.

Attributes

name	str	Tool name shown to the model.
description	str	Tool description shown to the model.
input_model	type[BaseModel]	Pydantic model of the tool arguments.
output_model	type[BaseModel]	Pydantic model of the tool result.

Methods

input_schema_json()

JSON schema of the arguments, as a string.

input_schema_json() -> str

input_schema()

JSON schema of the arguments.

input_schema() -> dict[str, Any]

output_schema_json()

JSON schema of the result, as a string.

output_schema_json() -> str

output_schema()

JSON schema of the result.

output_schema() -> dict[str, Any]

supports_context()

Whether the tool takes a ToolContext argument.

supports_context() -> bool

ToolMetadata

ToolMetadata(*, name, description, input_model, output_model, context_parameter=None, returns_model=False)

Name, description and schemas of a tool.

Attributes

name	str
description	str
input_model	type[BaseModel]	Model the arguments are validated against.
output_model	type[BaseModel]	Model the result is validated against.
context_parameter	str | None	Name of the parameter that receives the ToolContext.
returns_model	bool	The function's return type is the output model itself; otherwise the value is wrapped in the model's result field.

ToolContext

ToolContext(graph_name=None, node=None, state=None, thread_id=None, run_id=None, emit=None, middleware=(), workspace=None, tool_call_id=None, root_run_id=None, task_id='')

Run information passed to tools that declare a ToolContext.

Attributes

graph_name	str | None	Name of the graph.
node	str | None	Name of the node that calls the tool.
state	Any	State that node received.
thread_id	str | None
run_id	str | None	Id of the run.
emit	Callable[[Any], None] | None	Sends a "custom" stream event, like NodeContext.emit.
middleware	tuple[Any, ...]	Middleware of the run, in order.
workspace	Any	The graph's workspace.
tool_call_id	str | None	Id of the tool call being executed.
root_run_id	str | None	Id of the outermost run when the graph runs inside another one.
task_id	str	Task of the node that calls the tool.
context	Any	The context= object of the run the tool is called in.

Methods

from_node_context(ctx, state, ...)

class method Build a tool context from the running node.

from_node_context(ctx, state, *, tool_call_id=None) -> ToolContext

Parameters

ctx	NodeContext	Context of the node that calls the tool.
state	Any	State the node received.
tool_call_id	str | None	Id of the tool call being executed.

ToolCallResult

ToolCallResult(*, value, arguments)

Validated result of a tool call and the arguments it ran with.

Attributes

value	SerializeAsAny[BaseModel]	The result as an instance of the tool's output_model.
arguments	dict[str, Any]	The arguments after before_tool middleware.

call_tool

async call_tool(tool, arguments, ctx=None) -> ToolCallResult

Validate arguments, run tool middleware and call a tool.

Parameters

tool	Tool	A tool made with tool().
arguments	BaseModel | dict[str, Any]	Tool arguments.
ctx	ToolContext | None	Run information and middleware; an empty context is used when omitted.

Returns

ToolCallResult

The validated tool result and the arguments the tool ran with, after before_tool middleware.

Raises

TypeError	If tool is not a Tool.
ValidationError	If the arguments or the result do not match the tool's models; the on_tool_error hooks see a result error first.
Exception	What the tool raised, after the on_tool_error hooks saw it.