Choosing between a flow and an agent

Choose a Flow or an Agent for every AI feature you build on Runtype. Build a Flow when you can define the steps and branches before a run. Build an Agent when the next action depends on model-selected tool calls or an intermediate result. Use this guide to distinguish the two and combine them in hybrid designs.

Choose by the work, not the label

Use the shape of the work to choose the right option, not the word in the requirement. Use these signals:

• Build a Flow when the requirement describes a repeatable process that you can enumerate before each run and that produces a defined output. Examples include summarizing each new ticket and posting it to Slack, or fetching numbers each morning, rendering a report, and emailing it.
• Build an Agent when the model must select tools or decide its own next action from intermediate results or free-form input. For a fixed sequence that repeats until a deterministic verdict, use a bounded loop step in a Flow.

If a requirement says automation or workflow but needs judgment at each step, build an Agent. Record the rationale in plain language: “This is a Flow because the steps are fixed and explicit.”

Use the flowchart test

Ask one question: can you draw the flowchart before you see the input?

If you can list every step and branch before a run, build a Flow. Use Using conditional steps for branches and Using bounded loops for a fixed review/revise sequence with a deterministic exit verdict. Configure Prompt, Transform Data, Record, and API Call steps in the required order.

If the model must decide the next tool call beyond a predefined branch or bounded loop, build an Agent. Define the goal and available tools, then let the model select and sequence calls during the run.

Reliability across steps

Under the simplifying assumption of independent step failures, reliability multiplies across a chain. If each step succeeds 99% of the time, a ten-step chain succeeds about 90% of the time (0.99^10). At 95% per step, it succeeds about 60% of the time. Each model-selected step adds another decision point where the chain can fail.

Put model judgment only where it adds value. Put verifiable work in deterministic Flow steps. A Flow then runs those steps without asking the model to select them on every turn. An Agent that makes ten decisions when eight are fixed adds decision points without adding needed flexibility.

Use maxTurns as a safety cap, not a target. It defaults to 1, which gives one reasoning-and-tools pass. The loop ends after the model finishes its turn. It takes another turn only when the current turn reaches the tool-call budget or when loading a Skill or searching for tools expands the available tools. A higher cap does not create extra turns by itself. Keep verifiable work in Flow steps, and raise maxTurns when the task needs another pass.

Route low-cost checks before high-cost work

For a task with a few known paths, route requests through a low-cost classifier before high-cost model work. Use this shape:

1. Classify the input in a Prompt step. Use the fast claude-haiku-4-5 model and return a JSON object in intent.
2. Route the result in a Conditional step. Use {{intent.category}} to select the downstream path.
3. Run specialized work on the selected branch. Invoke high-cost model work only on the branch that needs it.

This shape keeps narrow routing work in a low-cost step and sends high-cost model calls only to the branches that need them.

Choose between known subtasks and dynamic sets

When you know the subtasks in advance, enumerate them. Use one Flow step per subtask, or give an Agent one tool per subtask and instructions that name those tools. The set is fixed, so declare it explicitly.

Use dynamic Subagents only when the input determines the subtasks. A parent Agent can create focused child Agents with scoped tools and isolated contexts. Choose this design when the number and shape of the workers are decided at run time.

Set maxSpawnsPerRun in the Agent’s Subagent configuration, not in its prompt. A prompt instruction such as only spawn a few does not enforce this limit. For more information, see Agent tools.

When to use multiple Agents

Use multiple Agents for parallel, independent research. Avoid them when added context and token costs outweigh the parallel work:

• Keep shared context together. If subtasks need each other’s intermediate results, use one Agent. Each child Agent receives only its scoped context.
• Account for token cost. Running several Subagents can use many times the tokens of one Agent because each child processes its own context.
• Avoid sequential chains. A chain of Agents adds latency and more failure points. Use one Agent with a scoped tool set when the work is sequential.

Use one Agent for a small fact-finding task. Consider two to four Subagents for a comparison across a few sources. Use ten or more workers only for research with many independent sources. If one Agent can handle the task, keep one Agent.

Scope tools to the task and measure selection quality. Tool-search activation or a large catalog alone does not mean the Agent must be split; separate capabilities when they need different context, permissions, or responsibilities.

Combine Flows and Agents

Use these two hybrid designs:

• Fixed Flow with scoped model decisions. Build a Flow for the fixed skeleton, such as validating input, looking up a Record, branching, and responding. Put one Prompt step in Agent mode with a scoped tool set at the step that needs judgment. The Flow keeps the overall path visible, and the model handles only the open-ended part.
• Model selection with Flow execution. Let the model select the action, then expose a thin Flow as a tool for the resulting write or other action. Use this design when you need an auditable path for Record writes, financial actions, or personal data. Keep each Flow focused on one contract with one clear result; use deterministic branches when that contract needs them. The Agent invokes the Flow, and the Flow runs the write steps in the configured order.

Make routing rules explicit

Use a Conditional step for mutually exclusive deterministic branches, or when guards for independent optional steps. The number of branches does not decide Flow versus Agent; reserve model selection for open-ended decisions.

For example, a Flow sends an email for a status intent. It drafts a reply for a draft intent and stores a sample for a sample intent. For known intents, classify once if needed, then route through one Conditional step and return one unified output.

Quick reference

Use the following table to choose based on the work’s shape.

Start with a Flow when you know the required steps. A Flow exposes each step for testing and debugging and keeps fixed work out of the model’s decision loop. Add an Agent when the model must select the next action or when the path depends on intermediate results.

Next steps

Use these pages to apply the decision:

• What are Flows?: learn how Flows define steps
• What are Agents?: learn how models select tools
• Using conditional steps: branch a Flow with explicit conditions
• Agent tools: configure tools and Subagents
• Designing evals that work: measure the behavior you choose
• Agent and Flow templates: start with a worked example