Skip to main content
Skip to Content
DocsCore Concepts

Heliox designs and runs agentic flows: directed graphs of execution steps, each backed by an LLM call or a tool call, composed into pipelines you can inspect, rewind, and re-run. This page lays out the primitives that make up that mental graph.

Steps

A step is the atomic unit of execution. Every step has:

  • a type — llm_call, tool_call, or router,
  • a prompt (and, for tool/router steps, the tools it can reach),
  • dependencies (prevStepIds) — the upstream steps that must complete first,
  • exactly one role and any number of mods attached,
  • an optional contract — a deterministic definition of “done”,
  • an optional per-step model override.

A step only starts once every step in its prevStepIds has completed, and its result becomes available context to whatever depends on it downstream.

Flows

A flow is a DAG of steps — the unit you design, save, run, and export. On the canvas, a flow is represented as a Frame: a container node that groups its steps and carries the flow’s own metadata (title, description, tags, author, version). Steps fan out and back in however the problem requires; Heliox schedules them in deterministic topological order (dependency-free steps first, ties broken by step id) so the same flow always executes the same way given the same inputs.

You compose a flow two ways: drawing it directly on the canvas, or describing the outcome in a sentence and letting Text-to-Flow — a meta-agent compiler — assemble the step DAG for you. Both paths produce the same underlying flow, editable by hand afterward. See Flow Design for both workflows in detail.

Loops

A flow can declare bounded loop-back edges: after a source step completes, control returns to an earlier target step and every step in between re-runs, up to a capped number of total passes (1–50). Loops are how a flow expresses “keep refining until good enough” without becoming an unbounded agent — the cap is enforced at export time, so every consumer of an exported flow can assume a valid bound without re-validating it.

Loop bodies expand pass-by-pass in the schedule: if a loop covers steps B1 and B2, execution interleaves B1@1, B2@1, B1@2, B2@2, … rather than exhausting every pass of B1 before starting B2 — each pass only unblocks the next once every step inside it has completed. Anything downstream of the loop waits for its final pass.

Checkpoints

After every step completes, Heliox records an immutable checkpoint: the exact input context the step saw, the output it produced, the model used, and the run’s progress up to that point. Checkpoints are never mutated after the fact — only appended.

That immutability is what makes time-travel possible: you can rewind a run to any completed step, inspect precisely what it saw and produced, edit the output by hand, and fork a new execution branch from that point forward — without disturbing the original run. It turns debugging an agentic flow from “re-run and hope” into “step to the exact point that went wrong and try again from there.”

Roles and Mods

Roles and mods are how a step’s behavior is specialized, and they compose in a deliberately aspect-oriented way:

  • Roles are execution personas — who is doing the work (frontend-engineer, security-researcher, technical-writer, …). Exactly one role is active per step, and a role contributes a system prompt that frames the step’s whole approach.
  • Mods are stackable constraints layered on top of a role — how the work must be done (test-driven, strict-linting, dry-run, …). Any number of compatible mods can stack on one step, each one injecting its own rules into the step’s system prompt.

Most mods are pure prompt constraints, but some carry real runtime semantics enforced by the executor itself, not just requested in text — for example test-driven attaches a completion contract that the guardrail engine actually checks, and dry-run strips write-capable tools from the step so “don’t generate code” is a guarantee, not a suggestion. See Roles & Mods for the full catalog and how attachment and composition work.

Contracts

A contract is a deterministic, model-agnostic definition of “done” for a step — assertions like must have written a file matching this path, must not contain stub markers like TODO or placeholder, or every imported package must be declared in the manifest. After a step runs, the guardrail engine checks its contract against the workspace. A failed check produces concrete, corrective feedback appended to the prompt for a bounded number of retries, so a weaker model converges on a complete artifact instead of quietly leaving a stub. Every check is a pure assertion — the verdict is identical no matter which model produced the output.

Verification, briefly

Snapshots — visual captures compared across iterations — are one optional verification technique the platform can use (for instance, a UI-focused flow checking for layout regressions), not a core execution primitive. They sit alongside the Performance Frontier’s other verifiers; see Architecture for where that fits.

Next steps

Last updated on
Getting StartedFlow Design