Skip to navigation
Flows

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, not the name the task goes by. Use these signals:

  • Build a Flow for 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.

If a task is called an automation or a workflow but needs judgment at each step, build an Agent. If it is called an agent but has known steps and a known output, build a Flow.

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 conditional steps for branches. For a fixed sequence that repeats until a deterministic verdict, such as review and revise, use a bounded loop. A bounded loop runs at most 10 rounds, set by its maxIterations field. If the work can need more rounds, or an open-ended number of them, use an Agent.

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

Reliability across steps

If step failures are independent, 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, and put verifiable work in deterministic Flow steps. A Flow 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.

Treat an Agent’s Max turns setting as a safety cap, not a target. A higher cap does not add turns by itself. For how the loop decides to take another turn, see Agent loop.

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, set responseFormat to json, and set the output variable to intent. Have the prompt return an object such as {"category": "billing"}.
  2. Route the result in a Conditional step. Branch on the category with a condition such as '{{intent.category}}' === 'billing'.
  3. Run specialized work on the selected branch. Invoke high-cost model work only on the branch that needs it.

When you need only a label or a pass/fail verdict, a judgment is typically faster and costs less than a Prompt step classifier. A choice question returns the selected label with a probability for every label, and a Conditional step can branch on the result.

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.

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

A subagent cannot see the parent’s conversation or ask follow-up questions, so give it a complete, self-contained task. Each subagent runs under its own turn limit.

Cap the number of subagents with Max spawns per run in the Agent’s Subagents settings. The dashboard control sets values from 1 to 20. To set a value up to 50, set maxSpawnsPerRun through the API. If you leave it unset, a run can spawn up to 5 subagents. A prompt instruction such as only spawn a few does not enforce a limit. For setup, see Subagent 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 subagent receives only its scoped context.
  • Account for token cost. Several subagents can use many times the tokens of one Agent because each subagent processes its own context.
  • Avoid chains of Agents. Each hand-off adds latency and another failure point. If the steps are known, use a Flow. If the model must choose them, use one Agent with a scoped tool set.

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 subagents 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. A large tool 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 hybrid designs:

  • Fixed Flow with one tool-using step. Build a Flow for the fixed skeleton, such as validating input, looking up a Record, branching, and responding. At the step that needs judgment, attach a scoped tool set to a Prompt step and set its Tool call strategy to Auto. The Flow keeps the overall path visible, and the model handles only the open-ended part.
  • Flow that delegates to an Agent. Add an Execute Agent step to run a saved Agent with a message and store its reply in an output variable. You can override the Agent’s maximum turns and timeout on the step. The step picker doesn’t list Execute Agent, so add the step through the API, MCP, or the TypeScript SDK.
  • Agent that calls a Flow. Let the model select the action, then run the resulting write or other action through a thin Flow. Publish the Flow and add it to the Agent’s tools, as described in Flow tools. 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. The Agent invokes the Flow, and the Flow runs its 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 support Flow classifies each message as billing, bug, or feedback. One Conditional step routes each category to its own path:

  • billing: look up the refund status.
  • bug: create a ticket.
  • feedback: write a Record.

Each path returns the same output shape, so the Flow returns one unified output.

Quick reference

Use the following signals to choose based on the shape of the work:

  • You can draw the entire flowchart before seeing the input: Flow.
  • The model must select the number or order of tool calls: Agent.
  • Fixed pipeline, such as ingest, render, and dispatch: Flow.
  • Fixed natural-language transformation: Prompt step in a Flow.
  • Subject-line or intent routing: Conditional step after a classifier or judgment.
  • Exact rules, even with many branches: Flow.
  • A fixed operation that an Agent calls as a tool: thin Flow.
  • Called an “agent” but has known steps and output: Flow.
  • One open-ended stage inside a fixed pipeline: Flow with an Execute Agent step or a tool-using Prompt step.
  • The execution path must be auditable and the decision needs model judgment: Agent that calls a Flow.

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: