Choosing between a flow and an agent
Every AI feature you build on Runtype is backed by either a Flow or an Agent. This is the first design decision you make, and it is the one most worth getting right. Pick a Flow when you can draw the flowchart in advance. Pick an Agent when the next step depends on what the model just learned. This guide gives you a sharper test than “Flows are steps, Agents are loops”, and shows the hybrid shapes that combine both.
The label is not the architecture
“Agent” has become the everyday word for “an AI thing that does something”. People say “build me an agent” for work that is really a fixed, repeatable pipeline. Decide from the shape of the work, not the label in the requirement.
- If the requirement describes a repeatable process you can enumerate in advance, with a defined output (“summarize each new ticket and post it to Slack”, “every morning fetch the numbers, render a report, email it”), build a Flow, even if it was called an agent.
- If the requirement needs a loop, reasoning, and tools, where the next action depends on an intermediate result or on free-form input, build an Agent.
The inverse is just as common: a requirement phrased as “automation” or “workflow” can still need judgment at every step, which makes it an Agent. The label matters less than the operating shape. Teams should choose the primitive that makes the behavior reliable, explainable, and economical, then record the rationale in plain language: “This is a Flow because it is a fixed pipeline, which makes it cheaper and more predictable.”
The flowchart test
Ask yourself one question: can you draw the flowchart before you see the input?
If you can write down every step and every branch in advance, and the diagram does not change from one run to the next, that is a Flow. The branches become Conditional steps, and the work becomes Prompt, Transform Data, Record, and API Call steps in a known order.
If the diagram would have to be redrawn for each input, because you cannot know ahead of time how many tool calls it takes or which order they come in, that is an Agent. You describe the goal and the available tools, and the model draws its own path at run time.
Compounding reliability
There is a quantitative reason to push verifiable work out of the model’s loop and into deterministic steps. Reliability multiplies across steps. If each step is 99% reliable, a ten-step chain is about 90% reliable (0.99 to the tenth power). At 95% per step, ten steps land near 60%. Every step where the model has to make a choice is a place the chain can break.
The lesson is not “avoid AI”. It is: let the model do the steps that genuinely need judgment, and let deterministic steps do everything else. A Flow makes each verifiable step a guarantee rather than a coin flip. An Agent that reasons through ten decisions when eight of them were fixed is trading reliability for flexibility it did not need.
This is also the case for capping an Agent’s turn limit. maxTurns defaults to 1 (a single reasoning-and-tools pass); raise it deliberately, to the smallest number the task actually needs. A high turn ceiling is more surface area for compounding error, more latency, and more cost, not more capability.
Cheap triage before expensive work
When a task splits into a few known paths, do not send every request through your most capable, most expensive model. Put a cheap classifier in front.
A common, effective shape:
- Prompt step with a fast model (
claude-haiku-4-5) that classifies the input into one of a few categories and returns a JSON object. Output variable:intent. - Conditional step that routes on
{{intent.category}}to the right downstream path. - The expensive, specialized work runs only on the branch that needs it.
A cheap first step that filters or routes can cut the cost of a pipeline dramatically, because the expensive model only runs on the fraction of inputs that reach it. The classifier is doing routing, which is exactly the kind of narrow judgment a small model does well.
Known subtasks versus a dynamic set
When you need to do several things and you know what they are in advance, enumerate them. Give a Flow one step per subtask, or give an Agent one tool per subtask and instructions that name them. The set is fixed, so make it explicit.
Reach for dynamic Subagents only when the set of subtasks depends on the input, so you cannot list them ahead of time. In Runtype, this means a parent Agent can create focused child Agents with a scoped subset of tools and isolated context. Use it when the number and shape of the workers is decided at run time (research that fans out to however many sources it finds), not as a default way to structure known work.
Whenever you do allow dynamic Subagents, cap the worker count in configuration, not in the prompt. Use the max-spawns setting on the Agent’s Subagent configuration; “please only spawn a few” in the instructions is a suggestion the model can ignore. See Subagent tools for the delegation contract.
When not to reach for multiple agents
Multi-agent designs are powerful for genuinely parallel, independent research, but they are not free, and they are the wrong tool for most work:
- Shared context and tight coordination fight the model. When subtasks constantly need each other’s intermediate state, splitting them across Agents means each one is missing what the others know. One well-scoped Agent beats three that keep re-explaining themselves.
- Token cost is real. A fan-out of Subagents can use many times the tokens of a single Agent, because each child re-reads its own context. Spend that only when the parallelism buys you something.
- Sequential chains compound. A pipeline of Agent-calling-Agent-calling-Agent multiplies both latency and the number of places a step can fail. If the work is really sequential, a single Agent with a better-scoped tool set is usually simpler and more reliable.
Match the effort to the task. A simple fact-find is one Agent making a handful of tool calls. A comparison across a few sources might warrant two to four Subagents. Reserve ten-plus workers for genuinely complex, wide research. If you find yourself designing an org chart of Agents for a task a single Agent could do, simplify.
A useful smell test: if an Agent needs dozens of tools to do its job, its scope is probably too broad. Split the job, or narrow the tools, before you split into more Agents.
Two hybrid shapes worth naming
Most real systems are neither a pure Flow nor a pure Agent. Two combinations come up again and again:
Deterministic supervisor with scoped autonomous parts. A Flow lays out the fixed skeleton (validate input, look up the Record, branch, respond), and a single Prompt step inside it runs in Agent mode with a tight tool set for the one part that needs judgment. The overall shape stays auditable; the autonomy is boxed into where it earns its keep.
Agent decides, deterministic code executes. The model reasons about what to do, but the actual side effects run through a Flow exposed to it as a tool. This is the shape to prefer when the execution path must stay auditable, which is almost always true for anything touching Records, money, or personal data. The Agent chooses; the Flow performs the write exactly the same way every time. Build these side-effecting Flows thin: two to four steps, no branching, one obvious result. Thin Flows make the best Agent tools.
The anti-pattern: a router disguised as a pipeline
The most common wrong turn is a Flow with three or more when:-guarded branches. Each when: clause is usually a decision that belongs in an Agent. If your Flow reads like “send this email when the intent is status and there is a guide; draft a reply when the intent is draft and there is a guide; store a sample when the intent is sample”, you have written an intent router in flowchart form.
A cleaner shape is either a single Agent whose instructions explain the intents, with a thin tool-backed Flow per action, or, when the work genuinely belongs in a Flow, one Conditional step that wraps the mutually exclusive branches and produces a unified output. A fan of sibling steps each guarded on a different case is a sign you are routing, and routing is usually Agent work.
Quick reference
Start with a Flow when you can. Flows are easier to test, debug, and reason about, and they cost less to run. Add Agent autonomy where the work genuinely needs a decision the flowchart cannot make in advance.
Next steps
- What are Flows?: the Flow primitive and its step types
- What are Agents?: how the Agent loop works
- Using conditional steps: branch a Flow without turning it into a router
- Agent tools: tool types, Subagents, and delegation
- Designing evals that work: measure whichever shape you choose
- Agent and flow templates: start from a worked example