Multi-Agent Architectures Overview

Overview

Swarms provides a wide range of multi-agent architectures designed for different use cases, from simple round-robin task distribution to complex hierarchical orchestration. This page provides a comprehensive overview to help you select the right architecture for your needs.

Installation

pip install -U swarms

Core Architectures

Architecture	Use Case	Key Functionality
MajorityVoting	Decision making through consensus	Agents answer independently; a consensus agent synthesizes the majority view, optionally over several loops
AgentRearrange	Custom execution order	Runs agents along a flow string such as `"A -> B, C -> D"`, mixing sequential and concurrent steps
RoundRobinSwarm	Equal turn distribution	Cycles through agents in a fixed order, once each per loop, on a shared conversation
Mixture of Agents	Complex problem solving	Combines diverse expert agents for comprehensive analysis
GroupChat	Collaborative discussions	Agents bid to speak each turn; the highest bid above a threshold takes the floor
SpreadSheetSwarm	Bulk runs as a table	Runs agents concurrently and saves every output to CSV; can load agents and per-agent tasks from a CSV
SwarmRouter	One interface for every architecture	Builds and runs the structure named by `swarm_type`, with optional fallbacks
MultiAgentRouter	Task routing	A boss agent routes each task to the specialist agent(s) best suited to it
AgentRouter	Embedding-based routing	Matches a task to the closest agent description by cosine similarity
ModelRouter	Model selection	A function-calling model picks the model and provider for each task
SocialAlgorithms	Custom communication protocols	Runs your own callable that decides how agents talk, and records every agent call

Workflow Architectures

Architecture	Use Case	Key Functionality
ConcurrentWorkflow	Parallel task execution	Runs every agent on the same task at once and collects the answers in agent order
SequentialWorkflow	Step-by-step processing	Runs agents one after another, each building on the previous output
GraphWorkflow	Complex task dependencies	Manages tasks with complex dependencies
BatchedGridWorkflow	Grid-style parallel task distribution	Pairs each agent with a different task and runs them concurrently
SwarmRearrange	Pipelines of swarms	Runs whole swarms along an `AgentRearrange`-style flow string

Hierarchical Architectures

Architecture	Use Case	Key Functionality
HierarchicalSwarm	Hierarchical task orchestration	Director agent coordinates specialized worker agents
Hybrid Hierarchical-Cluster Swarm	Complex organization	Combines hierarchical and cluster-based organization
Auto Swarm Builder	Automated swarm creation	Automatically creates and configures swarms
Auto Agent Builder	Automated roster creation	Generates the agent roster for a task and leaves the architecture to you
PlannerWorkerSwarm	Plan-then-delegate execution	A planner emits a dependency-aware task queue that a pool of workers claims and executes concurrently
PlannerGeneratorEvaluator	Contract-checked generation	A planner sets step contracts, a generator produces, an evaluator scores each step
HierarchicalStructuredCommunicationFramework	Structured generate-and-critique	Supervisor, generator, evaluator and refiner roles exchange structured messages
ForestSwarm	Topical routing over large rosters	Organizes agents into trees and routes each task by embedding similarity
SubagentRegistry	Background delegation	Spawns async subagent tasks with status tracking, retries and depth limits

Reasoning and Decision Architectures

Architecture	Use Case	Key Functionality
HeavySwarm	Deep, research-grade analysis	A question agent writes role-specific questions for a specialist roster, then the answers are synthesized
CouncilAsAJudge	Multi-criteria evaluation	Judge agents score a response along separate dimensions, then an aggregator writes the report
DebateWithJudge	Structured adversarial debate	Agents argue opposing positions over multiple rounds; a judge rules
LLMCouncil	Consensus-based decision making	Members answer independently, rank each other’s anonymized answers, and a chairman synthesizes
SelfMoASeq	Ensembles from one model	Samples one model many times and aggregates the samples in sliding windows
AdvisorSwarm	Cheap model with expensive backup	An executor consults a stronger advisor model between turns

Communication Topologies

Small, fixed message-passing patterns, all documented on one page.

Architecture	Use Case	Key Functionality
OneToOne / one_to_one	Two-agent loops	Sender and receiver alternate for `max_loops` exchanges on a shared conversation
Broadcast / broadcast	One message, many reactions	The sender speaks, then each receiver replies in turn; `broadcast` is async
OneToThree / one_to_three	Three-reviewer panels	The sender speaks, then exactly three receivers reply in turn
circular, grid, star, mesh, pyramid swarms	Topology experiments	Function-only ring, grid, hub-and-spoke, shared-queue and pyramid layouts

Serving, Scheduling, and Utilities

These are exported from swarms.structs next to the architectures above.

Component	Use Case	Key Functionality
MCPDeployer	Serving swarms to other tools	Exposes an agent, swarm, or callable as an authenticated MCP server; `deploy_as_mcp` is the one-call form
CronJob	Scheduled runs	Runs an agent, swarm, or callable on an interval
DecisionModel	Typed decisions	Client for decision models that answer typed questions about a state
check_models	Model availability	`get_available_models`, `is_model_available` and `model_count` over LiteLLM and OpenRouter names
Multi-agent execution utilities	Running agents without a structure	`run_agents_concurrently`, `batch_agent_execution` and related helpers
Multi-agent blocks	Small building blocks	`aggregate`, `run_agent` and `find_agent_by_name`

For single-agent reasoning strategies such as Tree of Thoughts, see the reasoning agents overview.

AgentRouter, ForestSwarm, PlannerWorkerSwarm and HierarchicalStructuredCommunicationFramework are not exported from the top-level swarms package. Import them from their modules; the structures catalog links each one’s source file.

Communication Structure

The Conversation documentation details the communication protocols and structures used between agents in these architectures.

Choosing the Right Architecture

Task Complexity — Simple tasks may only need basic architectures like RoundRobin, while complex tasks might require Hierarchical or Graph-based approaches.

Parallelization Needs — If tasks can be executed in parallel, consider ConcurrentWorkflow or SpreadSheetSwarm.

Decision Making Requirements — For consensus-based decisions, MajorityVoting is ideal.

Resource Optimization — If you need to optimize agent usage, consider SwarmRouter or MultiAgentRouter.

Dynamic Adaptation — For tasks requiring dynamic adaptation, consider Auto Swarm Builder.

Architecture Selection Guide

By Task Type

Task Type	Recommended Architecture
Simple, sequential tasks	SequentialWorkflow, RoundRobin
Parallel, independent tasks	ConcurrentWorkflow, SpreadSheetSwarm
Consensus-based decisions	MajorityVoting
Complex multi-domain tasks	HierarchicalSwarm, HHCS
Dynamic, evolving tasks	Auto Swarm Builder
Collaborative analysis	GroupChat, Mixture of Agents
Task routing	SwarmRouter, MultiAgentRouter

By Scale

Scale	Recommended Architecture
2-5 agents	RoundRobin, SequentialWorkflow, AgentRearrange
5-20 agents	SwarmRouter, GroupChat, ConcurrentWorkflow
20+ agents	HierarchicalSwarm, HHCS, SpreadSheetSwarm
Variable/dynamic	Auto Swarm Builder

For more detailed information about each architecture, refer to their respective documentation pages linked in the tables above.

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Multi-Agent Architectures Overview

Overview

Installation

Core Architectures

Workflow Architectures

Hierarchical Architectures

Reasoning and Decision Architectures

Communication Topologies

Serving, Scheduling, and Utilities

Communication Structure

Choosing the Right Architecture

Architecture Selection Guide

By Task Type

By Scale

​Overview

​Installation

​Core Architectures

​Workflow Architectures

​Hierarchical Architectures

​Reasoning and Decision Architectures

​Communication Topologies

​Serving, Scheduling, and Utilities

​Communication Structure

​Choosing the Right Architecture

​Architecture Selection Guide

​By Task Type

​By Scale

Overview

Installation

Core Architectures

Workflow Architectures

Hierarchical Architectures

Reasoning and Decision Architectures

Communication Topologies

Serving, Scheduling, and Utilities

Communication Structure

Choosing the Right Architecture

Architecture Selection Guide

By Task Type

By Scale