When to Use Swarm

Guidelines for when to use Swarm versus a single agent, how to decompose tasks, and common pitfalls to avoid.

Swarm is powerful, but it's not always the right tool. This guide helps you decide when to parallelize and how to decompose tasks effectively.

Use Swarm When...

You have 3+ independent tasks — If you can split work into multiple files, modules, or aspects that don't depend on each other, a swarm will complete them much faster.
Large-scale refactors — 1 Architect + N Developers (1 per file) + 1 Tester is the canonical swarm pattern.
Multi-perspective analysis — Have multiple researchers investigate different facets of a problem in parallel, then synthesize.
Batch operations — Generating documentation for 20 files, running security audits across a codebase, or testing multiple modules.
Content generation at scale — Writing 50 wiki articles, creating marketing copy for 10 products, etc.

Use a Single Agent When...

One simple task — If it's a single straightforward job (summarize a file, run a command), use agent directly. Swarm has unnecessary overhead for this.
Tasks are deeply sequential — If every step depends on the previous one's output and there's no parallelism, a swarm won't help — you're better off working in the main conversation.
Tight back-and-forth is needed — If the task requires iterative refinement with user feedback between steps, keep it in the main session.

Task Decomposition Guidelines

Do

One task = one file or one clear aspect. Finer decomposition means more effective parallelism.
Make every prompt self-contained. The agent has zero context from the main conversation — include all necessary file paths, requirements, and constraints.
End with a Reviewer or Tester. The last task should verify the other agents' work.
Pick matching roles. Use agent_roles(action: "list") to find roles that give agents the right system prompt and tool restrictions.
Keep prompts concise. Large prompts risk context overflow (413 errors, which are non-retryable).

Don't

❌ Reference "the file we discussed" — agents can't see your conversation.
❌ Create tasks that depend on each other within the same plan — they run in parallel, so task B can't use task A's output. Use separate plans or sequential phases instead.
❌ Exceed 100 agents per swarm — this is the hard limit.
❌ Forget wrap_up — without it, there's no final synthesis.

Cost Considerations

Swarm cost is linear — the total token usage is approximately the same as doing the work sequentially. What changes is wall-clock time: with N parallel agents, the job completes in roughly 1/N the time.

However, be mindful that:

Each agent has its own system prompt + context, adding some overhead per agent.
Very fine decomposition (100 agents for a small task) wastes tokens on overhead.
The sweet spot is typically 5–50 agents depending on task size.

See Cost Management for detailed strategies.

Decision Flowchart

Is it a single simple task?
  → Yes: Use agent() directly
  → No: Are there 3+ independent subtasks?
    → Yes: Use swarm with create_plan
    → No: Work in main conversation