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)

from nodex import Agent

app = Agent(name="research-agent", debug=True)

trace = app.run({"query": "AI trends"})

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=None, human_review=False)

@app.node(next="writer", retry=2, on_fail="fallback", timeout=10.0)
def research(state):
    return {"notes": call_model(state.get("query"))}

Registers a middleware function that wraps every node call. Middleware receives the current NodexState and a next_node callable. Call next_node(state) to continue execution.

@app.middleware
def my_middleware(state, next_node): ...

See the Middleware guide for full examples.

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")

@app.node()
@app.route(
    condition=lambda state: state.get("confidence", 0) > 0.8,
    if_true="publish",
    if_false="review",
)
def writer(state):
    return {"draft": "content", "confidence": 0.92}

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

Returned by app.run(). Captures the full result of one graph execution.

trace = app.run({"query": "AI trends"})

if trace.success:
    print(f"Done in {trace.total_duration:.2f}s, {trace.total_tokens} tokens")
else:
    for r in trace.results:
        if r.status != "success":
            print(f"Failed: {r.node_name} — {r.error}")

One result per executed node, available as trace.results.

Import from nodex.testing to test individual nodes in isolation without running the full graph.

from nodex.testing import assert_node_output, make_state, test_node

# Run a node and inspect the result
result = test_node(research, {"query": "AI trends"})
assert result.success
assert "notes" in result.output

# Assert specific keys are present in the output
assert_node_output(research, {"query": "AI trends"}, ["notes"])

# Build a NodexState manually for more control
state = make_state({"query": "test", "confidence": 0.9})
result = test_node(writer, state)

All Nodex exceptions inherit from NodexError.