Skip to main content
The SwarmRouter is the universal entry point for multi-agent orchestration in Swarms. Instead of importing and configuring different swarm classes, you keep the same agents list and just change the swarm_type to switch between Sequential, Concurrent, AgentRearrange, MixtureOfAgents, HierarchicalSwarm, and more. This page walks through one runnable example per common swarm_type, plus strategy comparison, fallback, token-usage, and production-ready patterns.

How SwarmRouter Works

  1. Single interface — one class, one run(task) method, regardless of which architecture you select.
  2. Strategy via parameter — set swarm_type="SequentialWorkflow", "ConcurrentWorkflow", "MixtureOfAgents", etc.
  3. Per-architecture options — some swarm types use dedicated router parameters (e.g. rearrange_flow for AgentRearrange, the heavy_swarm_* settings for HeavySwarm). For MixtureOfAgents, the last agent in agents is used as the aggregator automatically.
  4. Same agents everywhere — define your Agent instances once and reuse them across architectures.

Basic Example: Switching Architectures Without Rewriting Code

Define your agents once, then run the same task through three different architectures by changing only swarm_type.

Example: Sequential Workflow via SwarmRouter

Each agent’s output flows into the next. Ideal for ordered pipelines like research → write → edit.

Example: Concurrent Workflow via SwarmRouter

All agents see the same task and run in parallel. Use for independent perspectives, redundancy, or fan-out queries.

Example: AgentRearrange via SwarmRouter

Mix sequential and parallel execution in one flow using the DSL. -> chains agents; , runs them in parallel.

Example: Mixture of Agents via SwarmRouter

Workers respond independently, then an aggregator agent synthesizes a final answer. With SwarmRouter, the aggregator is not a separate kwarg — it is the last agent in the agents list. The router passes the full list as workers too, so the aggregator also answers in each layer before it synthesizes.

Example: Hierarchical Swarm via SwarmRouter

A director agent decomposes the task and delegates subtasks to worker agents.

Pattern: Strategy Comparison

Run the same task through multiple architectures and compare outputs. Useful when you don’t know which architecture suits your task best.

Pattern: Dynamic Architecture Selection

Pick the architecture at runtime based on task characteristics. This is a common production pattern when one server handles tasks of varying complexity.

Pattern: Production-Ready Configuration

Combine autosave, the multi-agent collaboration prompt, and an explicit output_type for a deployable router. The router will save its config, state, and metadata after every run.

Pattern: Fallback Architectures

Give the router an ordered list of backup swarm types. If the primary swarm raises, the next one is built from the same agents and runs the same task.
If every swarm in the chain fails, run() raises SwarmRouterRunError (from swarms.structs.swarm_router) naming each attempt.

Pattern: Tracking Token Usage

router.usage sums token usage over every agent the swarm ran, including agents the swarm builds for itself, such as the HierarchicalSwarm director. See Token usage.
Agent totals are lifetime totals, so take the difference between two reads to get the cost of one run.

Batch and Concurrent Execution

SwarmRouter exposes the same task-execution helpers regardless of which architecture is selected.

Choosing a swarm_type

What to Avoid

  • Do put the aggregator last in agents when using MixtureOfAgents — SwarmRouter uses agents[-1] as the aggregator. There is no aggregator_agent kwarg on the router.
  • Don’t pass unsupported constructor kwargs (e.g. rules, aggregator_agent, speaker_fn) — the router’s __init__ swallows extra **kwargs and silently ignores them. Apply global rules through each agent’s system_prompt instead.
  • Don’t omit rearrange_flow when using AgentRearrange — it is required and validated at construction time.
  • Don’t reuse a SwarmRouter across unrelated tasks expecting clean state — construct a new one per logical job, or reset its internal conversation between runs.