Skip to content

How multi-node automations work

A headless run executes a prompt node under an App's identity, outside any interactive session — fired by a manual trigger, a schedule, or an inbound webhook (see the CLI's Headless runs surface). A single-node run does one thing: run the entry node, write a result.

A multi-node run keeps going. After a node runs, the platform follows a routing edge to the next node and runs that one too, repeating until no edge fires. The triggers are the same, the budgets are the same — the walk is what's new. This page is the mental model; the field-level rules live in Multi-node run flows and a worked build in Build a branching automation.

A flow is a graph, not a script

You don't write a flow as a sequence of steps. You author prompt nodes and connect them with routing edges, and the platform walks the graph: run a node, look at its outgoing routing edges, take the first one whose condition fires, run that node, and so on. A "flow" is just a subgraph of your memory that happens to be wired for walking.

This matters because the graph is the same graph your nodes already live in. A flow node can carry reference edges, sit under a parent, and be read by search like any other node. Nothing about it is a special "workflow object" — it's ordinary nodes with routing edges between them.

Routing edges versus reference edges

Only edges named next or next.* route. Every other edge — documents, depends-on, abstract-of, anything else — is invisible to the walker. The consequence for authors is freeing: you can wire a flow node to its supporting material without the walker wandering into it. A documents edge to a playbook node annotates the flow; it never becomes a step.

The two kinds of edge also treat the target's content oppositely:

  • A reference edge inlines its target's content into the running node's prompt. Point a flow node at a playbook with a documents edge and the playbook text is assembled into that node's prompt.
  • A routing edge deliberately does not inline. The next step's prompt never leaks into the current step — the walker uses routing edges as rails, not as content. Each node sees only its own prompt plus its reference edges.

Decisions live on edges, not in prompts

Hadron draws a hard line between shaping a prompt and choosing the next one. Mustache templating shapes the content of a single prompt — it fills in {{topic}}. A conditional edge decides which prompt runs next — it evaluates a JSONLogic rule against the run's data.

An LLM is never asked to route. The model's job is to produce text and, where a node asks for it, to extract structured fields. The branch itself is a deterministic evaluation of a condition the author wrote. That's what makes a flow predictable and auditable: given the same data, the same edge always fires, and the fired edge is recorded. If no routing edge has a condition, the first one in edge order simply always fires — the fall-through.

The run envelope

Nodes can do more than emit text — a node can carry an extraction spec that pulls structured fields out of the model's response (an intent, a confidence score). Those extracted facts don't go back into the graph; they accumulate on the run itself, in a growing bag of fields called the envelope. Each hop's extractions merge onto it, later values winning.

The envelope is what conditions branch on and what later prompts render. The run's trigger payload (webhook args, a schedule's event data) and the envelope form one merged view, exposed to conditions and templates as message.data.*. When both carry the same key, the envelope wins — a fact the flow extracted overrides a hint the trigger supplied. This is why a classify-then-branch flow works: the first node writes confidence into the envelope, and the edge leaving it reads message.data.confidence.

Flow nodes can act, not just produce text

A node can also declare tools. Instead of only writing text, such a node runs a bounded tool loop — reading a node, creating one, updating one — and every individual call is authorized against the run's policy chain and budget at the moment it happens. That granularity is what makes a run safely cancellable: cancelling halts the walk at the next hop, so a create that hasn't run yet never runs.

Two failure philosophies are worth internalizing, because they read differently in the audit trail:

  • hadron_fail is the author's deliberate stop. A node can call it to end the run on purpose — "this doesn't meet the bar, stop here." It surfaces as an intentional halt, not a crash.
  • A tool malfunction is terminal and never retried. If a tool call throws, the run fails and is not re-attempted. This is deliberate: a retried flow must never repeat a side effect. Re-running a flow that already created a node must not create it twice, so any hop that has run a side-effecting call is never redelivered.

A node either extracts fields or runs tools — not both in the same node. Keep classification (extract) and action (tools) in separate nodes wired by a routing edge.

How flows end

A flow ends when no routing edge fires — every outgoing next* edge either has a condition that evaluates false, or there are no outgoing routing edges at all. That's not an error; it's the normal way a flow completes. A "terminal" node isn't specially marked — it's simply a node whose conditions don't send the walk onward. The last node to run writes the run's result record, the same way a single-node run always has.

Progress and safety

The walk is observable and bounded:

  • Progress is recorded as it goes. The run stores its current position and a trail of the hops it has taken — visible mid-run, not just at the end.
  • Budgets count every hop. The action budget and token budget decrement as the walk proceeds; a runaway flow hits a ceiling and stops rather than looping forever. There's also a hard cap on the number of hops.
  • Cancelling halts at the next hop. A live run transitions to cancelled cleanly between steps.
  • A transient failure resumes at the failing step. If a hop fails for a retryable reason and nothing has been committed, the run resumes at that step — not from the beginning. (A hop that already ran a side effect is never retried; see above.)
  • Multi-node run flows — the field-level reference: routing-edge selection, extractionSpec, output, tools, limits, failure codes, and the run record.
  • Edge conditions — the design rationale for deterministic conditions, and the model behind the portal builder.
  • Build a branching automation — a worked classify-then-branch flow, end to end.
  • Headless runs (CLI) — the triggers (manual / schedule / webhook) that start a run.