API reference

API

The reference is organized around the objects developers import and call directly.

Class

Agent

The main entry point for a Nodex graph. Create one agent, register nodes with decorators, then call run().

Agent(name: str = "agent", debug: bool = False)

name	Name shown in terminal output and execution traces.
debug	Prints richer failure details when available.

Decorator

Registers a Python function as a graph node. The function receives state and must return a non-empty dictionary.

@app.node(next="end", retry=0, on_fail="raise", timeout=30.0, human_review=False)

next	Next node name, or `"end"` to finish.
retry	Number of retry attempts before failure handling.
on_fail	Failure behavior. Use `"raise"` or a fallback node name.
timeout	Maximum seconds allowed for the node function.
human_review	Prompts for terminal approval before continuing.

Decorator

Adds conditional routing to a node. Use it when the next step depends on state produced by earlier nodes.

@app.route(condition, if_true="publish", if_false="review")

State

A small wrapper around user data. It keeps internal execution fields separate from the dictionary your nodes read and update.

get(key, default)	Read a value from the current state.
set(key, value)	Set one state value.
update(dict)	Merge multiple values without overwriting internal fields.

Testing

from nodex.testing import test_node

result = test_node(research, {"query": "AI trends"})
assert result.success

Errors

NodexNodeError	Raised when a node fails after retry and failure handling.
NodexStateError	Raised when a node returns invalid state output.
NodexMiddlewareError	Raised when middleware fails.
NodexConfigError	Raised for invalid app or graph configuration.
NodexTimeoutError	Raised when a node exceeds its timeout.