> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Structures Catalog

> Every multi-agent orchestration class and function shipped under swarms.structs, plus the reasoning agents in swarms.agents, with one-line descriptions, docs links and source links

## 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, 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. `SwarmRouter` is the exception: you pick the `swarm_type`, and it builds and runs that structure. 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 point-to-point patterns, each a class plus a function in its own module (`OneToOne`/`one_to_one` in `one_to_one.py`, `Broadcast`/`broadcast` in `broadcast.py`, `OneToThree`/`one_to_three` in `one_to_three.py`), and the five topology functions in `swarming_architectures.py` (`circular_swarm`, `grid_swarm`, `star_swarm`, `mesh_swarm`, `pyramid_swarm`). 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. See [Swarming Architectures](/api/swarming-architectures).
* **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 the agents never see each other's work. 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, linked to its docs page where one exists, with a one-line description and a direct link to its source file on GitHub.

<Note>
  **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`, `OneOnOneDebate`, `ExpertPanelDiscussion`, `one_on_one_debate`, `ImageAgentBatchProcessor`, `AgentRegistry`.

  Everything else in the table is importable directly as `from swarms import X`.
</Note>

## Catalog

| Name | Description | Source |
| - | - | - |
| [`SequentialWorkflow`](/api/sequential-workflow) | Runs agents one after another; each step receives the previous output as context. | [sequential\_workflow.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/sequential_workflow.py) |
| [`ConcurrentWorkflow`](/api/concurrent-workflow) | Fires every agent in parallel on the same task; results are collected in agent order. | [concurrent\_workflow.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/concurrent_workflow.py) |
| [`AgentRearrange`](/api/agent-rearrange) | DSL-driven flow (`"A -> B, C -> D"`) mixing sequential and concurrent steps. | [agent\_rearrange.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_rearrange.py) |
| [`SwarmRearrange`](/api/swarm-rearrange) | Same DSL as `AgentRearrange` but the nodes are whole swarms instead of single agents. | [swarm\_rearrange.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarm_rearrange.py) |
| [`GraphWorkflow`](/api/graph-workflow) | Full DAG executor with topological sort, per-node callbacks, and token streaming. | [graph\_workflow.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/graph_workflow.py) |
| [`BatchedGridWorkflow`](/api/batched-grid-workflow) | Pairs agent *i* with task *i*, runs the pairs concurrently, and repeats for `max_loops`. | [batched\_grid\_workflow.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/batched_grid_workflow.py) |
| [`SpreadSheetSwarm`](/api/spreadsheet-swarm) | Runs agents concurrently (on one task, or each CSV-configured agent on its own task) and saves every output to CSV. | [spreadsheet\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/spreadsheet_swarm.py) |
| `ImageAgentBatchProcessor` | Runs one or more agents over a batch of images concurrently, giving each image its own copy of the agent, with per-image error isolation. | [image\_batch\_processor.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/image_batch_processor.py) |
| [`SwarmRouter`](/api/swarm-router) | Single entry point that builds and runs any supported swarm type by name. | [swarm\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarm_router.py) |
| [`MultiAgentRouter`](/api/multi-agent-router) | LLM-driven "boss" routes a task to one or many specialist agents by capability. | [multi\_agent\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/multi_agent_router.py) |
| [`AgentRouter`](/api/agent-router) | Embedding-based router: matches a task to the best agent via cosine similarity over descriptions. | [agent\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_router.py) |
| [`ModelRouter`](/api/model-router) | Routes a task to the best *model* (not agent) given task requirements. | [model\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/model_router.py) |
| `AuctionSwarm` | Agents bid `(confidence, estimated_cost)` on a task via a forced tool call; the top-scoring bidder(s) execute it. | [auction\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/auction_swarm.py) |
| [`HierarchicalSwarm`](/api/hierarchical-swarm) | Director agent decomposes the task and delegates to workers; synthesizes results. | [hiearchical\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/hiearchical_swarm.py) |
| [`HierarchicalStructuredCommunicationFramework`](/api/hierarchical-communication-framework) | "Talk Structurally, Act Hierarchically" — structured messages between supervisor / generator / evaluator / refiner roles. | [hierarchical\_structured\_communication\_framework.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/hierarchical_structured_communication_framework.py) |
| [`HybridHierarchicalClusterSwarm`](/api/hhcs) | Hierarchy routes to clusters; inside clusters agents communicate peer-to-peer. | [hybrid\_hiearchical\_peer\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/hybrid_hiearchical_peer_swarm.py) |
| [`PlannerWorkerSwarm`](/api/planner-worker-swarm) | Planner emits a task queue; a worker pool claims and executes tasks concurrently. | [planner\_worker\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/planner_worker_swarm.py) |
| [`SubagentRegistry`](/api/async-subagent) | Async subagent spawning with status tracking, result aggregation, retry policy, and depth-limited recursion. | [async\_subagent.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/async_subagent.py) |
| [`MixtureOfAgents`](/api/mixture-of-agents) | N workers respond in parallel for L layers; aggregator synthesizes the final answer. | [mixture\_of\_agents.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/mixture_of_agents.py) |
| [`SelfMoASeq`](/api/self-moa-seq) | Sequential self-MoA: many samples from one strong model, sliding-window aggregation. | [self\_moa\_seq.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/self_moa_seq.py) |
| [`HeavySwarm`](/api/heavy-swarm) | Decomposes a problem into role-specific questions for a specialist roster (research, analysis, alternatives and verification in the default variant), then synthesizes. | [heavy\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/heavy_swarm.py) |
| [`MajorityVoting`](/api/majority-voting) | Agents vote; consensus agent synthesizes / breaks ties across loops. | [majority\_voting.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/majority_voting.py) |
| [`CouncilAsAJudge`](/api/council-as-judge) | Council evaluates a response across multiple dimensions; ranks/scores outputs. | [council\_as\_judge.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/council_as_judge.py) |
| [`LLMCouncil`](/api/llm-council) | Independent expert agents respond, peer-review each other, then synthesize. | [llm\_council.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/llm_council.py) |
| [`DebateWithJudge`](/api/debate-with-judge) | Adversarial debate rounds followed by a judge ruling; supports self-refinement. | [debate\_with\_judge.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/debate_with_judge.py) |
| [`GroupChat`](/api/group-chat) | Turn-based, self-selecting chat — each turn every agent privately bids `(score, message)` via a forced tool call, and the highest bidder above `threshold` takes the floor. | [groupchat.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/groupchat.py) |
| [`ForestSwarm`](/api/forest-swarm) | A forest of `Tree`s of `TreeAgent`s; routes tasks to the best matching tree leaf. | [tree\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/tree_swarm.py) |
| [`AdvisorSwarm`](/api/advisor-swarm) | Cheap executor + powerful advisor consulted on-demand between turns. | [advisor\_swarm.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/advisor_swarm.py) |
| [`PlannerGeneratorEvaluator`](/api/planner-generator-evaluator) | Three-agent harness: Planner emits step contracts, Generator produces, Evaluator scores. | [planner\_generator\_evaluator.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/planner_generator_evaluator.py) |
| [`RoundRobinSwarm`](/api/round-robin-swarm) | Visits agents in a fixed rotation, once each per loop; each turn sees the conversation so far plus a header naming its position, predecessor and successor. | [round\_robin.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/round_robin.py) |
| [`AutoAgentBuilder`](/api/auto-agent-builder) | Generates only the agent roster — name, description, system prompt, model — via a forced function call, leaving the architecture to you. | [auto\_agent\_builder.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/auto_agent_builder.py) |
| [`AutoSwarmBuilder`](/api/auto-swarm-builder) | Takes a high-level description and auto-generates agents, roles, and swarm structure. | [auto\_swarm\_builder.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/auto_swarm_builder.py) |
| [`SocialAlgorithms`](/api/social-algorithms) | Framework for uploading user-defined communication algorithms over a fixed agent set. | [social\_algorithms.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/social_algorithms.py) |
| `AgentRegistry` | Thread-safe registry of named agents with schema validation and lookup. | [agent\_registry.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_registry.py) |
| [`OneToOne`](/api/swarming-architectures) | Reusable sender/receiver pair that alternates for `max_loops` exchanges. | [one\_to\_one.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/one_to_one.py) |
| [`Broadcast`](/api/swarming-architectures) | Reusable one-sender, many-receiver group; receivers reply in turn. `run` is synchronous. | [broadcast.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/broadcast.py) |
| [`OneToThree`](/api/swarming-architectures) | Reusable one sender plus exactly three receivers, who reply in turn. | [one\_to\_three.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/one_to_three.py) |
| [`OneOnOneDebate`](/api/orchestration-methods) | Turn-based debate between two agents for N loops. | [multi\_agent\_debates.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/multi_agent_debates.py) |
| [`ExpertPanelDiscussion`](/api/orchestration-methods) | Moderator-guided panel of expert agents. | [multi\_agent\_debates.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/multi_agent_debates.py) |
| [`circular_swarm`](/api/swarming-architectures) | Every agent answers every task in order on one shared conversation. | [swarming\_architectures.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarming_architectures.py) |
| [`grid_swarm`](/api/swarming-architectures) | Agents in a √N×√N grid, one task per cell. | [swarming\_architectures.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarming_architectures.py) |
| [`star_swarm`](/api/swarming-architectures) | Star topology — the first agent answers each task first, then the rest answer it on their own. | [swarming\_architectures.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarming_architectures.py) |
| [`mesh_swarm`](/api/swarming-architectures) | Agents take turns pulling tasks from a shared FIFO queue until it is empty. | [swarming\_architectures.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarming_architectures.py) |
| [`pyramid_swarm`](/api/swarming-architectures) | Agents in triangular levels, one task per cell. | [swarming\_architectures.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarming_architectures.py) |
| [`one_to_one`](/api/swarming-architectures) | Function form of `OneToOne`. | [one\_to\_one.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/one_to_one.py) |
| [`broadcast`](/api/swarming-architectures) | Function form of `Broadcast` (**async** — must be awaited, though receivers still run one after another). | [broadcast.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/broadcast.py) |
| [`one_to_three`](/api/swarming-architectures) | Function form of `OneToThree`. | [one\_to\_three.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/one_to_three.py) |
| [`one_on_one_debate`](/api/orchestration-methods) | Functional turn-based two-agent debate; procedural twin of `OneOnOneDebate`. | [deep\_discussion.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/deep_discussion.py) |
| [`aggregate`](/api/ma-blocks) | Runs N agents concurrently on one task and synthesizes their outputs via an aggregator agent. | [ma\_blocks.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/ma_blocks.py) |

## Other exports from swarms.structs

These are exported from `swarms` alongside the structures above. They serve, schedule, or support swarms rather than orchestrate agents themselves.

| Name | Description | Source |
| - | - | - |
| [`MCPDeployer`](/api/mcp-deployer) | Serves an agent, swarm, or callable as an authenticated MCP server, one tool per target. | [mcp\_deployer.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/mcp_deployer.py) |
| [`deploy_as_mcp`](/api/mcp-deployer) | Builds an `MCPDeployer` for one target and serves it. Blocks. | [mcp\_deployer.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/mcp_deployer.py) |
| [`CronJob`](/api/cron-job) | Turns any callable, including an `Agent`, into a scheduled job. | [cron\_job.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/cron_job.py) |
| [`DecisionModel`](/api/decision-model) | HTTP client for decision models (TypeSafe Jev, Cloudflare Clef) that answer typed questions about a state. | [decision\_model.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/decision_model.py) |
| [`get_decision_models`](/api/decision-model) | Lists decision model names from every provider. | [decision\_model.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/decision_model.py) |
| [`get_available_models`](/api/check-models) | Lists every model name LiteLLM knows, plus OpenRouter's live catalogue (cached for five minutes). | [check\_models.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/check_models.py) |
| [`is_model_available`](/api/check-models) | Whether a model name is one LiteLLM or OpenRouter can serve. | [check\_models.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/check_models.py) |
| [`model_count`](/api/check-models) | How many model names `get_available_models` would return. | [check\_models.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/check_models.py) |
| [`Conversation`](/api/conversation) | Message history shared by agents and structures, with export and token counting. | [conversation.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/conversation.py) |
| [`AgentLoader`](/api/agent-loader) | Creates `Agent` objects from Markdown, YAML, and CSV files. | [agent\_loader.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_loader.py) |
| [`rearrange`](/api/agent-rearrange) | One-call helper that builds an `AgentRearrange` and runs a task. | [agent\_rearrange.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/agent_rearrange.py) |
| [`run_agent`](/api/ma-blocks), [`find_agent_by_name`](/api/ma-blocks) | Run one agent with argument checks; look up an agent in a list by name. | [ma\_blocks.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/ma_blocks.py) |
| [`batch_agent_execution`](/api/multi-agent-execution-utilities) | Runs agents (or callables) on one task each, with optional images, concurrently. | [batch\_agent\_execution.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/batch_agent_execution.py) |
| [`run_single_agent`, `run_agent_async`, `run_agents_concurrently`, `run_agents_concurrently_async`, `run_agents_concurrently_multiprocess`, `run_agents_with_different_tasks`, `batched_grid_agent_execution`, `get_agents_info`, `get_swarms_info`](/api/multi-agent-execution-utilities) | Sync, async, threaded, and batched execution helpers, plus formatters that describe a roster of agents or swarms. | [multi\_agent\_exec.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/multi_agent_exec.py) |
| [`Node`, `Edge`, `NodeType`](/api/graph-workflow) | Graph building blocks for `GraphWorkflow`. | [graph\_workflow.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/graph_workflow.py) |
| [`SwarmType`](/api/swarm-router) | The `Literal` of valid `swarm_type` strings for `SwarmRouter`. | [swarm\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarm_router.py) |
| [`RESPOND_TOOL`](/api/group-chat) | The forced `respond(score, message)` tool schema `GroupChat` uses for speaking bids. | [groupchat.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/groupchat.py) |
| [`StepContract`, `EvaluationReport`, `HarnessResult`](/api/planner-generator-evaluator) | Data types for `PlannerGeneratorEvaluator` contracts, per-step scores, and final results. | [planner\_generator\_evaluator.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/planner_generator_evaluator.py) |
| [`SubagentTask`, `TaskStatus`](/api/async-subagent) | Per-task record and status enum for `SubagentRegistry`. | [async\_subagent.py](https://github.com/kyegomez/swarms/blob/master/swarms/structs/async_subagent.py) |

## Reasoning agents in swarms.agents

`swarms.agents` holds single-agent reasoning strategies and agent utilities. Every name below is exported from `swarms`.

| Name | Description | Source |
| - | - | - |
| [`TreeOfThoughts`](/agents/tree-of-thoughts) | Searches a tree of reasoning steps (BFS or DFS), scoring and pruning branches. `run` returns the answer; the full search is kept on `last_result` as a `TreeOfThoughtsResult` of `ThoughtNode`s. | [tree\_of\_thoughts.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/tree_of_thoughts.py) |
| [`ReasoningDuo`](/agents/reasoning-duo) | A reasoning agent and a main agent work in tandem. | [reasoning\_duo.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/reasoning_duo.py) |
| [`SelfConsistencyAgent`](/agents/self-consistency-agent) | Samples several answers and keeps the most consistent one. | [consistency\_agent.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/consistency_agent.py) |
| [`ReflexionAgent`](/agents/reflexion-agent) | Improves its answer through self-reflection across iterations. | [flexion\_agent.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/flexion_agent.py) |
| [`GKPAgent`](/agents/gkp-agent) | Generated Knowledge Prompting: generates relevant knowledge before answering. | [gkp\_agent.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/gkp_agent.py) |
| [`IterativeReflectiveExpansion`](/agents/iterative-agent) | Iterative Reflective Expansion (IRE) reasoning algorithm. | [i\_agent.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/i_agent.py) |
| [`AgentJudge`](/agents/agent-judge) | Evaluates and scores outputs from other agents or systems. | [agent\_judge.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/agent_judge.py) |
| [`ReasoningAgentRouter`](/agents/reasoning-agent-router) | Picks a reasoning agent by `swarm_type`; `agent_types` lists the valid values. | [reasoning\_agent\_router.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/reasoning_agent_router.py) |
| [`ContextCompressor`](/agents/agent-memory) | Summarizes an agent's short-term memory when it nears the context limit in `max_loops="auto"` runs. | [context\_compressor.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/context_compressor.py) |
| [`SkillsManager`](/api/skills-manager) | Loads Agent Skills from disk and renders them for the model. | [skills\_manager.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/skills_manager.py) |
| [`LLMManager`](/api/llm-manager) | Model selection, LiteLLM construction, invocation, and fallback for an agent. | [llm\_manager.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/llm_manager.py) |
| [`AgentMarketplaceHandler`](/api/agent-marketplace-handler) | Fetches prompts from, and publishes prompts to, the Swarms Marketplace. | [agent\_marketplace\_handler.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/agent_marketplace_handler.py) |
| [`create_agents_from_yaml`](/api/agent-loader) | Creates agents, and optionally a `SwarmRouter`, from a YAML file or string. | [create\_agents\_from\_yaml.py](https://github.com/kyegomez/swarms/blob/master/swarms/agents/create_agents_from_yaml.py) |

## 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 communication primitives as a research playground.** `OneToOne`, `Broadcast`, and `OneToThree`, their function forms, and the topology functions in `swarming_architectures.py` 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.