Nous.Workflow.Engine (nous v0.15.7)

Core workflow execution engine.

A recursive function module (not a GenServer) that processes nodes according to the compiled graph topology, threading state through each step. Follows the same pattern as Nous.AgentRunner.

Execution Model

Executes nodes in topological order, following edges. Supports:

Sequential edges (always followed)
Conditional edges (followed when predicate matches)
Branch nodes (routing to one of multiple paths)
Cycles (with max-iteration guards)

Error Handling

Each node has an error_strategy:

:fail_fast — halt immediately
{:retry, max, delay_ms} — retry with delay
:skip — record error, continue
{:fallback, node_id} — route to fallback node

Hooks

Workflow hooks intercept execution at key points:

:workflow_start / :workflow_end — lifecycle events
:pre_node — before each node (can pause/block)
:post_node — after each node (can modify state)

Pause/Resume

Workflows can be paused via:

A :pre_node hook returning {:pause, reason}
An external signal via :atomics pause_ref
A :human_checkpoint node

Summary

Functions

execute(compiled, initial_data \\ %{}, opts \\ [])

Execute a compiled workflow from its entry node.

Functions

execute(compiled, initial_data \\ %{}, opts \\ [])

@spec execute(Nous.Workflow.Compiler.compiled(), map(), keyword()) ::
  {:ok, Nous.Workflow.State.t()}
  | {:suspended, Nous.Workflow.State.t(), map()}
  | {:error, term()}

Execute a compiled workflow from its entry node.

Options

:max_iterations — max cycle iterations per node (default: 10)
:deps — dependencies passed to agents/tools
:callbacks — callback functions for agent steps
:notify_pid — PID to receive progress notifications
:hooks — list of Nous.Hook structs for workflow lifecycle events
:pause_ref — :atomics ref for on-demand pause signaling

Returns

{:ok, final_state} — workflow completed successfully
{:suspended, state, checkpoint} — workflow paused
{:error, reason} — workflow failed