MULTI_AGENT_STRUCTURES.md

Multi-Agent Structures in swarms.structs

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, SkillOrchestra, 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 — in AuctionSwarm's case — each agent's own bid on the task. 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 named-ritual templates in multi_agent_debates.py (OneOnOneDebate, RoundTableDiscussion, PeerReviewProcess, TrialSimulation, and friends). These run scripted conversational patterns end-to-end so you don't have to reimplement "moderated panel" or "academic peer review" by hand.
• Topology experiments — the *Swarm family in various_alt_swarms.py (CircularSwarm, MeshSwarm, FibonacciSwarm, SigmoidSwarm, etc.) and the matching functional helpers in swarming_architectures.py. These exist for research and exploration: what happens if you only activate agents at prime indices? Sinusoidal positions? They're cheap to try because they share a tiny common interface.
• Self-improvement and auto-construction — PlannerGeneratorEvaluator, 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.

Name	Description	File
SequentialWorkflow	Runs agents one after another; each step receives the previous output as context.	link
ConcurrentWorkflow	Fires every agent in parallel on the same task; returns a per-agent result map.	link
AgentRearrange	DSL-driven flow ("A -> B, C -> D") mixing sequential and concurrent steps with optional human-in-the-loop.	link
SwarmRearrange	Same DSL as AgentRearrange but the nodes are whole swarms instead of single agents.	link
GraphWorkflow	Full DAG executor with topological sort, per-node callbacks, and token streaming.	link
BatchedGridWorkflow	Runs an agent×task grid of batched executions.	link
SpreadSheetSwarm	Treats a spreadsheet as the task table; each row becomes a concurrent agent run.	link
SwarmRouter	Single entry point that dispatches to any supported swarm type by name.	link
MultiAgentRouter	LLM-driven "boss" routes a task to one or many specialist agents by capability.	link
AgentRouter	Embedding-based router: matches a task to the best agent via cosine similarity over descriptions.	link
ModelRouter	Routes a task to the best model (not agent) given task requirements.	link
SkillOrchestra	Skill-aware orchestration — picks agents by declared skills and cost.	link
AuctionSwarm	Agents bid (confidence, estimated_cost) via a forced tool call; an auctioneer awards the task to the best bid.	link
HierarchicalSwarm	Director agent decomposes the task and delegates to workers; synthesizes results.	link
HierarchicalStructuredCommunicationFramework	"Talk Structurally, Act Hierarchically" — structured messages between supervisor / generator / evaluator / refiner roles.	link
HybridHierarchicalClusterSwarm	Hierarchy routes to clusters; inside clusters agents communicate peer-to-peer.	link
PlannerWorkerSwarm	Planner emits a task queue; a worker pool claims and executes tasks concurrently.	link
MixtureOfAgents	N workers respond in parallel for L layers; aggregator synthesizes the final answer.	link
SelfMoASeq	Sequential self-MoA: many samples from one strong model, sliding-window aggregation.	link
HeavySwarm	Decomposes a problem into specialized questions, runs each through deep multi-loop agents.	link
MajorityVoting	Agents vote; consensus agent synthesizes / breaks ties across loops.	link
CouncilAsAJudge	Council evaluates a response across multiple dimensions; ranks/scores outputs.	link
LLMCouncil	Independent expert agents respond, peer-review each other, then synthesize.	link
DebateWithJudge	Adversarial debate rounds followed by a judge ruling; supports self-refinement.	link
GroupChat	Asynchronous self-selecting groupchat — every agent independently scores each message via a forced respond(score, message) tool call and broadcasts when the score clears threshold.	link
ForestSwarm	A forest of Trees of TreeAgents; routes tasks to the best matching tree leaf.	link
AdvisorSwarm	Cheap executor + powerful advisor consulted on-demand between turns.	link
PlannerGeneratorEvaluator	Three-agent harness: Planner emits step contracts, Generator produces, Evaluator scores.	link
RoundRobinSwarm	True round-robin distribution with optional turn awareness between agents.	link
AutoSwarmBuilder	Takes a high-level description and auto-generates agents, roles, and swarm structure.	link
SocialAlgorithms	Framework for uploading user-defined communication algorithms over a fixed agent set.	link
CircularSwarm	Agents pass tasks around a ring.	link
StarSwarm	One central agent processes; others orbit.	link
MeshSwarm	Agents pull tasks from a shared queue at random.	link
PyramidSwarm	Agents arranged in a pyramid; tasks flow top-down.	link
FibonacciSwarm	Tasks land on Fibonacci-indexed agents.	link
PrimeSwarm	Prime-indexed agents handle the work.	link
PowerSwarm	Power-of-two-indexed agents handle the work.	link
LogSwarm	Logarithmic spacing of active agents.	link
ExponentialSwarm	Exponential spacing of active agents.	link
GeometricSwarm	Geometric progression of active agents.	link
HarmonicSwarm	Harmonically spaced active agents.	link
StaircaseSwarm	Staircase-pattern indices process the task.	link
SigmoidSwarm	Sigmoid-distributed agent activations.	link
SinusoidalSwarm	Sinusoidal agent activations.	link
Broadcast	One sender broadcasts to many receivers.	link
OneToOne	Pair-wise direct communication between two agents.	link
OneToThree	One sender hands off to exactly three receivers.	link
OneOnOneDebate	Turn-based debate between two agents for N loops.	link
RoundTableDiscussion	Each participant speaks in order; cycle repeats.	link
ExpertPanelDiscussion	Moderator-guided panel of expert agents.	link
InterviewSeries	Structured interview with follow-up questions.	link
PeerReviewProcess	Academic peer review with reviewers + author rebuttals.	link
MediationSession	Mediator resolves conflict between two or more parties.	link
NegotiationSession	Multi-party negotiation toward agreement.	link
BrainstormingSession	Participants build on each other's ideas.	link
CouncilMeeting	Structured council discussion + decision-making.	link
MentorshipSession	Structured mentor / mentee learning and feedback.	link
TrialSimulation	Legal trial with structured phases and roles.	link
circular_swarm	Functional (agents, tasks) circular topology.	link
grid_swarm	Functional agent×task grid execution.	link
star_swarm	Functional star topology — central hub, peripheral workers.	link
mesh_swarm	Functional mesh topology — random task pull.	link
pyramid_swarm	Functional pyramid topology — top-down task flow.	link
one_to_one	Functional direct send/reply between two agents.	link
broadcast	Functional one-sender-to-many-receivers.	link

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 topology swarms in various_alt_swarms.py and swarming_architectures.py as a research playground. 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 non-uniform agent activation?"
5. Reach for SocialAlgorithms or AutoSwarmBuilder 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.