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
- Single interface — one class, one
run(task)method, regardless of which architecture you select. - Strategy via parameter — set
swarm_type="SequentialWorkflow","ConcurrentWorkflow","MixtureOfAgents", etc. - Per-architecture options — some swarm types use dedicated router parameters (e.g.
rearrange_flowforAgentRearrange, theheavy_swarm_*settings forHeavySwarm). ForMixtureOfAgents, the last agent inagentsis used as the aggregator automatically. - Same agents everywhere — define your
Agentinstances 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 onlyswarm_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. WithSwarmRouter, 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
Combineautosave, 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.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.
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
agentswhen usingMixtureOfAgents—SwarmRouterusesagents[-1]as the aggregator. There is noaggregator_agentkwarg on the router. - Don’t pass unsupported constructor kwargs (e.g.
rules,aggregator_agent,speaker_fn) — the router’s__init__swallows extra**kwargsand silently ignores them. Apply global rules through each agent’ssystem_promptinstead. - Don’t omit
rearrange_flowwhen usingAgentRearrange— 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.