How it works
A workflow graph represents an automated process as nodes connected by edges. Nodes perform work or enforce control: call a model, invoke a tool, evaluate a condition, wait for approval, persist a checkpoint, or join parallel results. Edges specify which node may run next and may carry conditions, data dependencies, or failure routes.
A typical execution proceeds as follows:
- The runtime loads the graph definition and creates a run with its own state.
- It finds nodes whose dependencies and entry conditions are satisfied.
- It executes eligible nodes, recording inputs, outputs, status, and side effects.
- It follows matching edges, including branches, retries, waits, and error paths.
- It completes when a terminal node or explicit stop condition is reached.
The graph definition and the run state are different artifacts. The definition says what transitions are allowed. The run state says which nodes have executed, what they produced, and what remains eligible. Keeping that distinction explicit makes interruption and resumption tractable.
Loops require extra care. A graph may contain cycles, but every cycle needs a visible exit condition and a budget. Without those controls, a workflow graph is merely a diagram around an unbounded process.
Why it matters in an agent harness
A model can propose the next action, but the harness remains responsible for deciding whether that action is permitted and how it changes the run. A workflow graph gives the harness a structural place to make those decisions. It turns execution order, approval requirements, and recovery paths into inspectable system behavior instead of leaving them implicit in prompts.
This improves control. High-impact nodes can require an approval checkpoint, scoped credentials, or a deterministic verifier. Read-only research can branch in parallel while a write operation remains blocked until its prerequisites are satisfied. The model may choose among permitted edges, but it does not gain authority to create new transitions at runtime unless the harness explicitly supports that capability.
Graphs also improve failure containment. A node boundary identifies what was attempted, which inputs were present, and which downstream work may have been affected. If a tool call fails before producing a confirmed result, the runtime can mark that node as failed or unknown rather than allowing later nodes to treat missing data as success. Side-effecting nodes can carry idempotency rules or compensating actions so that retry and rollback have defined semantics.
Observability becomes more useful when events map to graph structure. Operators can see the current node, prior transitions, branch decisions, waiting conditions, and retry counts. That is more actionable than a transcript alone because it exposes the system's control state as well as the model's language.
The graph does not make a workflow reliable by itself. Reliability depends on durable state, explicit transition rules, bounded retries, validated data contracts, and honest handling of unknown outcomes. A visually tidy graph with implicit state or permissive error handling can still conceal irreversible failures.
Workflow Graph vs agentic workflow
A workflow graph is a control representation. An agentic workflow is a broader operating pattern in which one or more agents use models and tools to pursue a goal. An agentic workflow may be implemented with a graph, but the terms are not interchangeable.
| Design question | Workflow graph | Agentic workflow |
|---|---|---|
| Primary concern | Allowed execution paths and dependencies | How agents decide and perform work |
| Next-step selection | Fixed, conditional, or selected from declared edges | May be model-directed within harness limits |
| State boundary | Usually explicit per node and transition | Often includes prompts, memory, tools, and environment state |
| Main engineering test | Can every transition, wait, and recovery path be explained? | Can the system pursue the goal without exceeding delegated authority? |
The distinction changes architecture. Use the graph to constrain and record possible trajectories. Use agent logic inside selected nodes when the work genuinely requires judgment. Putting every decision in the model weakens control. Encoding every judgment as a fixed branch makes the system brittle.
The Rifty take
We treat a workflow graph as an executable control boundary, not a presentation diagram. We optimize for legible state transitions, bounded model choice, and recovery from the last trustworthy checkpoint. We accept some orchestration overhead because implicit transitions are harder to inspect, test, and reverse.
Implementation checks
- Give every node a stable identity and a single, explainable responsibility.
- Define node input, output, and error contracts independently of prompt wording.
- Separate immutable graph definitions from mutable per-run state.
- Record why each conditional edge was selected.
- Make joins specify whether they require all, any, or a named subset of branches.
- Represent waits and approvals as durable states, not blocked processes or hidden polling loops.
- Put iteration and retry budgets on every cycle.
- Classify side effects so retries cannot silently duplicate writes.
- Treat timeouts and lost responses as unknown outcomes until reconciled.
- Test interruption at each side-effecting node and verify that resumption starts from a trustworthy boundary.
- Reject undeclared transitions rather than routing them through a generic success path.
Frequently asked questions
Does a workflow graph need to be acyclic?
No. A workflow graph may contain cycles for iteration, evaluation, or retry, but each cycle should have an explicit exit condition and execution budget. A directed acyclic graph is simpler to reason about, while a cyclic graph requires stronger state tracking and protection against unbounded execution.
Should the model be allowed to choose the next node?
Only among transitions the harness has already authorized. Model-directed routing is useful when the choice requires semantic judgment, but the graph should constrain the available destinations, validate the routing output, and record the reason. The model should not silently expand its own authority by inventing executable nodes.
What state must be persisted for a workflow graph?
Persist enough state to determine completed, active, waiting, failed, and eligible nodes without reconstructing truth from a transcript. This normally includes node inputs and outputs, transition decisions, retry counts, checkpoint references, side-effect receipts, and unresolved outcomes. Secrets should remain referenced through controlled credential mechanisms.
How should side-effecting nodes be retried?
Retry them only when duplicate execution is prevented or safely reconciled. Use idempotency controls where the external operation supports them, record durable request and result identifiers, and classify timeouts as unknown outcomes. When repetition cannot be made safe, require inspection or a defined compensating action before continuing.