When Ironflow Fits an Agentic System

Ironflow is a durable runtime for agents. This page is about the question that comes before wiring one up: is your problem the kind that suits this at all?

The short version: Ironflow is the harness, and the agent is a tool it calls. Engine owns control flow, model owns judgment. That inversion is what makes a particular class of problem tractable — and it’s the wrong shape for everything else.

For how to wire an agent up once you’ve decided, see How Ironflow Fits with Agent Frameworks.

Where Ironflow sits

Ironflow does not replace your reasoning layer. It wraps the calls that must survive a crash, a deploy, or a three-day wait — and leaves prompts, model choice, and planning to whatever you already use.

Three layers: a reasoning layer owning prompts and planning, the Ironflow runtime wrapping the memoized model call, memoized tool call, durable approval wait and queryable event history, and your application owning domain rules and permissions

The boundary is the whole idea. The model decides what to say; the engine decides what happens next. Cross that line — let the model choose the next state — and you give up replay, resumability, and the audit trail in one move.

The fit test

Two questions, not one. Most “should I build an agent?” debates conflate them.

A third gate before any of this: if the work finishes inside one request, you don’t need durable execution — you need an API call. It’s multi-day waits and multiple parties that make durability load-bearing rather than decorative.

Heuristic: draw the state machine on a whiteboard. If you can, it belongs in the engine. Whatever you couldn’t draw — because it depends on reading a diff, a document, a message — is where the agent goes.

The shape

Problems in the top-right quadrant tend to decompose the same way:

  ① SELECT    pick the next unit of work from a backlog   → AGENT
  ② EXECUTE   fan-out over N; partial failure tolerated    → no agent
  ③ VERIFY    deterministic checks, then triage residue    → AGENT
  ④ CONFIRM   external approval · wait → nudge → escalate  → AGENT
  ⑤ CLOSE     seal the record                              → no agent

The agent belongs where the input is unstructured or the output is for a human. Stages ② and ⑤ are neither. Stage ③ is the one most often got wrong — run cheap deterministic checks first and send the model only what they couldn’t classify.

Ironflow primitives map onto this directly: step.map with a concurrency limit for ②, step.compensate for per-item rollback, and the ctx-injected approve() helper from @ironflow/node/agent for the human gate in ④ — a durable wait with a TTL that doesn’t hold a worker open.

The invariants

These transfer regardless of domain.

#	Invariant	Why
I1	Engine owns control flow; agent owns judgment	The moment the model decides what’s next, you lose replay and the audit trail
I2	Closed command vocabulary	The agent maps text onto fixed commands or says “don’t know” — it never mints event names
I3	Every agent call returns a schema-validated struct	Makes I1 enforceable rather than aspirational; malformed output retries instead of branching
I4	Deterministic first, agent on the residue	Cheaper, and the failure taxonomy grows from real cases
I5	The conversational surface is stateless	Publishes commands, reads projections, holds no memory — so it stays correct after a restart
I6	Failures carry a class from a finite enum, routed to a handler	Diagnose once, handle forever. This is where value compounds
I7	Human gates are commands, not hardcoded pauses	The autonomy ladder becomes an architectural property

I7 matters most. Promoting a gate from human to agent becomes a change to who emits the command — not a workflow rewrite. You can start with every gate human and climb as trust is earned, without re-architecting.

Why a durable runtime rather than the alternatives

Against a plain agent loop. Those are built for the bottom-right quadrant — the model choosing its own trajectory. Point one at a known process and you pay nondeterminism for nothing. They also have no answer for “wait 72 hours and survive a deploy,” and their audit trail is a chat transcript.

Against a general workflow engine. Durable execution is table stakes; most engines would run these five stages. What they don’t give you natively is a queryable, rebuildable history. Entity streams and projections mean “why did the system do that, and who approved it” is answered from the same log that drove execution.

Both differences show up on the same event — an agent seven turns into a run when the worker dies:

The same agent seven turns deep when the worker dies at turn 3, compared three ways: a plain agent loop starts over and leaves a chat transcript, a general workflow engine resumes at turn 3 and leaves whatever you logged, Ironflow resumes at turn 3 and leaves the event log that drove execution

The middle column is the one worth dwelling on. A general workflow engine recovers just as well — the difference isn’t resumability, it’s what you can ask afterwards.

That gap matters more for agents than for ordinary workflows. “Why did the agent do that” is the first question anyone asks — and it’s the question that decides whether you’re allowed to raise the autonomy level. The event log is the agent’s accountability layer. Durable execution that is interrogable is what makes autonomy defensible.

Where this shape shows up

Anything describable as a campaign with an external approver:

Access recertification (SOX / SOC 2)
Compliance evidence collection
Vendor and supplier onboarding
Tenant or customer data migration
Repository or infrastructure migration programmes
Data-quality remediation campaigns
Contract renewal and procurement
Claims and underwriting triage

The tell: someone else’s approval sits on the critical path, and you will run the loop hundreds of times.

Costs and anti-fit

Doesn’t fit: sub-10-second tasks with no waits · genuinely open-ended work where the path isn’t knowable · no external party and no audit requirement · very high volume with very low value per item.

Costs: you must know the process before you build — this is a spec, not a discovery exercise · the event vocabulary is a commitment, evolved later through upcasters · more test surface than a simple service · more infrastructure than calling a model in a loop.

Break-even is roughly N × coordination-cost-per-iteration. Hundreds of iterations at hours of human coordination each is clearly worth it. Five iterations is not.

How Ironflow Fits with Agent Frameworks — the layer boundary and integration paths
Workflows — durable steps, waits, and compensation
Event Sourcing — entity streams and the audit trail
Projections — building the read model the conversational surface answers from