Skip to main content

​
Overview

swarms.structs is the library’s multi-agent orchestration layer. Where the single-agent primitive (Agent) decides what one model does on one turn, the structures in this catalog decide how a population of agents combines into a system that produces a single useful answer. Each structure encodes a different opinion about how that combination should work — who talks to whom, in what order, how disagreement is resolved, and how results are merged. The catalog roughly clusters into a handful of recurring patterns:
  • Pipelines and DAGs — SequentialWorkflow, ConcurrentWorkflow, AgentRearrange, SwarmRearrange, GraphWorkflow, BatchedGridWorkflow, SpreadSheetSwarm. These let you describe the topology of execution explicitly, from a flat A→B→C line to a full directed acyclic graph with fan-out/fan-in, callbacks, and streaming. Use these when you already know the shape of the workflow.
  • Routers and selectors — SwarmRouter, MultiAgentRouter, AgentRouter, ModelRouter, AuctionSwarm. These don’t run a fixed plan; they look at the incoming task and pick which agent(s) (or which model) should handle it. The selector itself is either an LLM (“boss”), an embedding match, a skill-graph lookup, or — for AuctionSwarm — a market: each agent bids its own confidence and estimated cost, and the auctioneer awards the task to the best bid instead of trusting a boss LLM’s guess. Use these when the input space is broader than any single agent’s competence.
  • Hierarchies and delegation — HierarchicalSwarm, HierarchicalStructuredCommunicationFramework, HybridHierarchicalClusterSwarm, PlannerWorkerSwarm. A director or supervisor decomposes the task and delegates pieces to workers, then synthesizes. The variants differ in how strictly the communication protocol is defined and whether the workers themselves can cluster and talk peer-to-peer.
  • Ensembles and consensus — MixtureOfAgents, SelfMoASeq, HeavySwarm, MajorityVoting, CouncilAsAJudge, LLMCouncil, DebateWithJudge. The shared assumption is that one model’s first answer is rarely the best answer. These structures sample multiple opinions and combine them — by aggregator synthesis, by vote, by judge ruling, or by structured adversarial debate.
  • Dialogue and discussion — GroupChat, ForestSwarm, AdvisorSwarm, plus the two named-ritual templates that remain in multi_agent_debates.py: OneOnOneDebate (turn-based two-agent debate) and ExpertPanelDiscussion (moderator-guided expert panel). These run scripted conversational patterns end-to-end so you don’t have to reimplement “moderated panel” or “structured debate” by hand. The other rituals — interview series, peer review, mediation, negotiation, brainstorming, council meeting, mentorship, trial simulation — have moved out of the library and now live under examples/multi_agent/alternate_debates/; copy the file you need rather than importing it.
  • Communication primitives and topology experiments — the three message-passing primitives in various_alt_swarms.py (OneToOne, Broadcast, OneToThree) and the seven functional helpers in swarming_architectures.py (circular_swarm, grid_swarm, star_swarm, mesh_swarm, pyramid_swarm, one_to_one, and the async broadcast). These are the smallest possible building blocks: a sender, a receiver set, and a task. They exist for research and exploration — wiring a topology by hand to see whether the shape of the conversation, rather than the agents in it, is what moves the result. They’re cheap to try because they share a tiny common interface.
  • Self-improvement and auto-construction — PlannerGeneratorEvaluator, AutoAgentBuilder, AutoSwarmBuilder, SocialAlgorithms. These build or refine swarms dynamically: a planner negotiates contracts with a generator and evaluator; a builder reads a high-level description and spits out a configured swarm; SocialAlgorithms lets you upload an entirely custom communication protocol over a fixed agent set.
A few practical notes that apply across the whole catalog:
  1. Most structures take a List[Agent]. Mix providers freely — a GPT agent and a Claude agent and a local Llama agent can sit side by side in MixtureOfAgents or GroupChat. The structure doesn’t care; LiteLLM normalizes the calls.
  2. SwarmRouter is the meta-entry point. If you’re not sure which structure to commit to, instantiate one and change swarm_type= later — you don’t have to rewrite the orchestration code.
  3. Topology choice is a lever, not a guess. Sequential is cheapest and most deterministic. Concurrent is fastest end-to-end but loses ordering. Hierarchical pays an extra LLM call to the director in exchange for cleaner delegation. Ensembles pay N× tokens for variance reduction. Pick the trade-off, not the buzzword.
The table below lists every multi-agent structure currently shipped, with a one-line description and a direct link to its source file on GitHub.
Not everything in this table is re-exported from the top-level package. These names ship in the library but are absent from __all__ in swarms/structs/__init__.py, so from swarms import X raises ImportError — import them by full module path instead, e.g. from swarms.structs.tree_swarm import ForestSwarm:AgentRouter, AuctionSwarm, HierarchicalStructuredCommunicationFramework, PlannerWorkerSwarm, ForestSwarm, OneToOne, Broadcast, OneToThree, OneOnOneDebate, ExpertPanelDiscussion, ImageAgentBatchProcessor, AgentRegistry.Everything else in the table is importable directly as from swarms import X.

​
Catalog

​
Conclusion

The breadth of this catalog is deliberate: there is no single “right” way to compose agents. A linear pipeline beats a hierarchy when the work is well-decomposed. A hierarchy beats a pipeline when the decomposition itself is the hard part. An ensemble beats either when correctness matters more than latency. A debate beats an ensemble when the failure mode is one-sided reasoning rather than random noise. The structures here exist so you can pick the one whose assumptions match your task instead of bending one general-purpose pattern to fit every problem. A pragmatic way to use the catalog:
  1. Start with the simplest structure that could plausibly work. A SequentialWorkflow or ConcurrentWorkflow is usually enough for a first pass and forces you to confirm the underlying agents are doing their jobs before you add coordination overhead.
  2. Reach for SwarmRouter when prototyping. Swapping swarm_type= between "SequentialWorkflow", "MixtureOfAgents", "HierarchicalSwarm", and "MajorityVoting" is a one-line change and a fast way to see which topology actually helps on your task.
  3. Escalate to a heavier pattern only when you can name the failure it fixes. Adding CouncilAsAJudge because the single-agent answers are inconsistent across criteria is a good reason; adding it because “more agents is better” usually just buys variance and cost.
  4. Treat the primitives in various_alt_swarms.py and swarming_architectures.py as a research playground. OneToOne, Broadcast, and OneToThree — plus the functional helpers alongside them — are bare message-passing wiring rather than finished orchestrators. They share a tiny interface, are cheap to try, and are useful when you want to ask empirical questions like “does this task benefit from a fan-out step before the agents converge?”
  5. Reach for SocialAlgorithms or the auto-builders only when nothing in the built-in set fits. Most production workloads land cleanly on one of the canonical patterns; reinventing the protocol or auto-generating the swarm is a last resort, not a default.
If you’re adding a new pattern of your own, the convention is straightforward: subclass nothing required, accept a List[Agent] and any structure-specific config, expose .run(task) and (ideally) .batch_run(tasks), and let find_agent_by_name, Conversation, and the helpers in multi_agent_exec handle the boring parts. Drop the new file in swarms/structs/, export it from swarms/structs/__init__.py, and add a row to this table.