Multi-Swarm Orchestration

​

Overview

​

Installation

pip install -U swarms

​

Architecture Comparison

​

Core Architectures

​

Hybrid Hierarchical-Cluster Swarm (HHCS)

• Each task is routed to one specialized swarm based on its requirements
• batched_run() routes many tasks concurrently, each to its own swarm
• Ideal for complex, multi-domain tasks and enterprise-scale operations
• Provides clear task routing but requires more complex setup

​

Auto Agent Builder

• A builder agent analyzes the task and designs a roster of up to max_agents agents (default 5), each with its own name, description, system prompt and model
• run() returns constructed Agent objects, or the raw configuration dicts when return_dict=True
• It does not run the agents. Hand them to a structure such as SwarmRouter or HierarchicalSwarm to execute the task
• Best suited for evolving requirements and dynamic workloads

from swarms import AutoAgentBuilder, SwarmRouter

task = "Evaluate whether a mid-size retailer should build or buy its e-commerce platform."

agents = AutoAgentBuilder(model_name="gpt-5.4", max_agents=3).run(task)

router = SwarmRouter(agents=agents, swarm_type="SequentialWorkflow")
result = router.run(task)

​

SwarmRouter

• Sequential workflows
• Concurrent workflows
• Hierarchical swarms
• Group chat interactions
• Mixture of agents, majority voting, debate, council and planner-worker patterns

​

Use Case Recommendations

​

HHCS

• Enterprise-scale operations
• Multi-domain problems
• Complex task routing
• Parallel processing needs

​

Auto Agent Builder

• Dynamic workloads
• Evolving requirements
• Research and development
• Exploratory tasks

​

SwarmRouter

• General purpose tasks
• Quick deployment
• Mixed workflow types
• Smaller scale operations

​

Best Practices for Selection

​

Evaluate Task Complexity

• Simple tasks: SwarmRouter
• Complex, multi-domain tasks: HHCS
• Dynamic, evolving tasks: Auto Agent Builder

​

Consider Scale

• Small scale: SwarmRouter
• Large scale: HHCS
• Variable scale: Auto Agent Builder

​

Resource Availability

• Limited resources: SwarmRouter
• Abundant resources: HHCS or Auto Agent Builder
• Dynamic resources: Auto Agent Builder

​

Development Time

• Quick deployment: SwarmRouter
• Complex system: HHCS
• Experimental system: Auto Agent Builder

​

Related Documentation

• Hybrid Hierarchical-Cluster Swarm (HHCS)
• SwarmRouter
• Auto Agent Builder
• Auto Swarm Builder