> ## 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.

# SwarmRouter

> Universal router that dispatches a task to any supported swarm architecture through a single, uniform interface

## Overview

The `SwarmRouter` class dispatches tasks to any supported multi-agent architecture through a single, uniform interface. Set `swarm_type` to choose the architecture; pass the same agent list and call `run(task)` regardless of which architecture you select.

It also handles:

* Validated construction of the underlying swarm (`reliability_check`)
* Optional autosave of config / state / metadata to the workspace
* Multi-agent collaboration prompt injection
* Optional rules / shared-memory injection
* O(1) factory dispatch with internal caching

## Import

```python theme={null}
from swarms.structs.swarm_router import (
    SwarmRouter,
    SwarmType,
    SwarmRouterConfig,
    SwarmRouterRunError,
    SwarmRouterConfigError,
)
```

## `SwarmType`

`SwarmType` is a `typing.Literal` enumerating every accepted `swarm_type` string. Any value outside this set raises `SwarmRouterConfigError` at construction time.

```python theme={null}
SwarmType = Literal[
    "AgentRearrange",
    "MixtureOfAgents",
    "SequentialWorkflow",
    "ConcurrentWorkflow",
    "GroupChat",
    "MultiAgentRouter",
    "AutoSwarmBuilder",
    "HierarchicalSwarm",
    "auto",
    "MajorityVoting",
    "CouncilAsAJudge",
    "HeavySwarm",
    "BatchedGridWorkflow",
    "LLMCouncil",
    "DebateWithJudge",
    "RoundRobin",
    "PlannerWorkerSwarm",
]
```

<Note>
  `"auto"` and `"AutoSwarmBuilder"` are listed in the Literal but are **not** dispatched by the current factory (it handles 15 of the 17 values). Selecting either passes construction validation, then raises `ValueError` during `run()`. Use one of the other 15 values.
</Note>

## Constructor

```python theme={null}
SwarmRouter(
    id: str = generate_api_key(prefix="swarm-router"),
    name: str = "swarm-router",
    description: str = "Routes your task to the desired swarm",
    max_loops: int = 1,
    agents: List[Union[Agent, Callable]] = [],
    swarm_type: SwarmType = "SequentialWorkflow",
    autosave: bool = False,
    rearrange_flow: Optional[str] = None,
    return_json: bool = False,
    auto_generate_prompts: bool = False,
    shared_memory_system: Any = None,
    rules: Optional[str] = None,
    documents: List[str] = [],
    output_type: OutputType = "dict-all-except-first",
    speaker_fn: Optional[Callable] = None,
    load_agents_from_csv: bool = False,
    csv_file_path: Optional[str] = None,
    return_entire_history: bool = True,
    multi_agent_collab_prompt: bool = True,
    list_all_agents: bool = False,
    conversation: Any = None,
    agents_config: Optional[Dict[Any, Any]] = None,
    speaker_function: Optional[str] = None,
    heavy_swarm_loops_per_agent: int = 1,
    heavy_swarm_question_agent_model_name: str = "gpt-4.1",
    heavy_swarm_worker_model_name: str = "gpt-4.1",
    heavy_swarm_swarm_show_output: bool = True,
    heavy_swarm_use_grok_agents: bool = False,
    telemetry_enabled: bool = False,
    council_judge_model_name: str = "gpt-5.4",
    verbose: bool = False,
    worker_tools: Optional[List[Callable]] = None,
    aggregation_strategy: str = "synthesis",
    chairman_model: str = "gpt-5.1",
    autosave_use_timestamp: bool = True,
    *args,
    **kwargs,
)
```

### Core parameters

<ParamField path="id" type="str" default="generate_api_key(prefix='swarm-router')">
  Unique identifier for the router instance. Used for autosave directory naming and telemetry.
</ParamField>

<ParamField path="name" type="str" default="swarm-router">
  Human-readable name. Used for autosave directory naming.
</ParamField>

<ParamField path="description" type="str" default="Routes your task to the desired swarm">
  Free-form description of the router's purpose.
</ParamField>

<ParamField path="agents" type="List[Union[Agent, Callable]]" default="[]">
  Agents the router will pass to the selected swarm. Some swarm types require a specific minimum count (e.g. `DebateWithJudge` needs at least three).
</ParamField>

<ParamField path="swarm_type" type="SwarmType" default="SequentialWorkflow">
  Which architecture to instantiate. See the `SwarmType` Literal above.
</ParamField>

<ParamField path="max_loops" type="int" default="1">
  Maximum execution loops where supported by the underlying swarm (e.g. `HierarchicalSwarm`, `GroupChat`).
</ParamField>

<ParamField path="output_type" type="OutputType" default="dict-all-except-first">
  Output formatter applied to the conversation. One of `'str'`, `'string'`, `'list'`, `'json'`, `'dict'`, `'dict-all-except-first'`, `'yaml'`, `'xml'`.
</ParamField>

<ParamField path="return_json" type="bool" default="False">
  When `True`, results are returned as JSON regardless of `output_type`. Useful for downstream parsing.
</ParamField>

<ParamField path="return_entire_history" type="bool" default="True">
  Whether the underlying swarm returns the full conversation history or only the final step.
</ParamField>

### Behavior modifiers

<ParamField path="rules" type="str" optional>
  String injected into every agent's system prompt before execution. Useful for global guardrails (citation requirements, tone, format).
</ParamField>

<ParamField path="multi_agent_collab_prompt" type="bool" default="True">
  Inject the built-in collaboration prompt into each agent so they understand they are part of a multi-agent team.
</ParamField>

<ParamField path="auto_generate_prompts" type="bool" default="False">
  Automatically generate / refine each agent's system prompt before the first run.
</ParamField>

<ParamField path="shared_memory_system" type="Any" optional>
  Shared memory backend (e.g. a vector store) made available to all agents.
</ParamField>

<ParamField path="documents" type="List[str]" default="[]">
  File paths to documents the router can attach to agent context.
</ParamField>

<ParamField path="list_all_agents" type="bool" default="False">
  When `True`, embed a manifest of every agent (name + description) into the conversation so each agent can see its peers.
</ParamField>

<ParamField path="conversation" type="Any" optional>
  Pre-existing `Conversation` instance to reuse instead of starting fresh.
</ParamField>

<ParamField path="agents_config" type="Optional[Dict[Any, Any]]" optional>
  Per-agent configuration overrides applied during swarm setup.
</ParamField>

<ParamField path="load_agents_from_csv" type="bool" default="False">
  When `True`, agents are loaded from `csv_file_path` instead of from the `agents` list.
</ParamField>

<ParamField path="csv_file_path" type="str" optional>
  Path used when `load_agents_from_csv=True`.
</ParamField>

<ParamField path="verbose" type="bool" default="False">
  Emit detailed logs during construction and execution.
</ParamField>

<ParamField path="telemetry_enabled" type="bool" default="False">
  Forward telemetry events about this router's runs.
</ParamField>

### Autosave

<ParamField path="autosave" type="bool" default="False">
  When enabled, persist `config.json` on construction and `state.json` + `metadata.json` after each run to `{workspace_dir}/swarms/SwarmRouter/{swarm-name}-{stamp}/`.
</ParamField>

<ParamField path="autosave_use_timestamp" type="bool" default="True">
  Use an ISO timestamp in the directory name when `True`; use a UUID when `False`.
</ParamField>

### Per-architecture parameters

These are only consulted when the corresponding `swarm_type` is selected.

#### AgentRearrange

<ParamField path="rearrange_flow" type="str" required>
  Flow DSL string, e.g. `"researcher -> writer, editor"`. Required for `swarm_type="AgentRearrange"`.
</ParamField>

#### GroupChat

<ParamField path="speaker_fn" type="Callable" optional>
  Speaker-selection function for `GroupChat`. Receives state and returns the next speaker's name.
</ParamField>

<ParamField path="speaker_function" type="str" optional>
  Named speaker function (e.g. `"round_robin"`, `"expertise_based"`).
</ParamField>

#### HeavySwarm

<ParamField path="heavy_swarm_loops_per_agent" type="int" default="1">
  Number of reasoning loops per worker agent.
</ParamField>

<ParamField path="heavy_swarm_question_agent_model_name" type="str" default="gpt-4.1">
  Model used by the question-generation captain.
</ParamField>

<ParamField path="heavy_swarm_worker_model_name" type="str" default="gpt-4.1">
  Model used by every worker agent.
</ParamField>

<ParamField path="heavy_swarm_swarm_show_output" type="bool" default="True">
  Whether to render the live dashboard during execution.
</ParamField>

<ParamField path="heavy_swarm_use_grok_agents" type="bool" default="False">
  When `True`, instantiate the 4-agent Grok variant (Captain / Harper / Benjamin / Lucas) instead of the default 5-agent set.
</ParamField>

<ParamField path="worker_tools" type="List[Callable]" optional>
  Tools made available to every worker agent in `HeavySwarm`.
</ParamField>

#### CouncilAsAJudge

<ParamField path="council_judge_model_name" type="str" default="gpt-5.4">
  Model used by the judge agent.
</ParamField>

#### LLMCouncil

<ParamField path="aggregation_strategy" type="str" default="synthesis">
  How council member responses are combined into the chairman's final decision.
</ParamField>

<ParamField path="chairman_model" type="str" default="gpt-5.1">
  Model used by the chairman.
</ParamField>

### Additional kwargs

The constructor accepts arbitrary `*args` / `**kwargs` for forward-compatibility, but they are **not** stored on the router or forwarded to the underlying swarm — extra constructor kwargs are effectively ignored. Configure the underlying swarm through the router's explicit parameters listed above.

For `MixtureOfAgents`, the aggregator is **not** passed as a kwarg; the **last agent** in `agents` is used as the aggregator automatically:

```python theme={null}
router = SwarmRouter(
    swarm_type="MixtureOfAgents",
    agents=[worker_1, worker_2, aggregator],  # aggregator = agents[-1]
)
```

## Exceptions

<ResponseField name="SwarmRouterConfigError" type="Exception">
  Raised by `reliability_check()` when construction inputs are invalid: unknown `swarm_type`, missing required parameter for the chosen type (e.g. `rearrange_flow` for `AgentRearrange`), `max_loops <= 0`, etc.
</ResponseField>

<ResponseField name="SwarmRouterRunError" type="Exception">
  Raised by `run()` / `batch_run()` / `concurrent_run()` when task execution fails inside the underlying swarm. Wraps the original traceback.
</ResponseField>

## Methods

### `run(task=None, img=None, tasks=None, *args, **kwargs)`

Execute a single task using the configured swarm.

<ParamField path="task" type="str" optional>
  The task to be executed. Required for most `swarm_type` values.
</ParamField>

<ParamField path="img" type="str" optional>
  Optional image input forwarded to vision-capable agents.
</ParamField>

<ParamField path="tasks" type="List[str]" optional>
  List of tasks. Consumed by `BatchedGridWorkflow`.
</ParamField>

**Returns:** `Any` — shape depends on `output_type` and the underlying swarm.

**Raises:** `SwarmRouterRunError` on execution failure.

```python theme={null}
result = router.run("Analyse Q1 market trends.")
```

***

### `__call__(task, *args, **kwargs)`

Alias for `run`. Lets you treat a router as a callable.

```python theme={null}
result = router("Analyse Q1 market trends.")
```

***

### `batch_run(tasks, img=None, imgs=None, *args, **kwargs)`

Execute many tasks sequentially. Each task gets a fresh execution against the same router instance.

<ParamField path="tasks" type="List[str]" required>
  Tasks to process.
</ParamField>

<ParamField path="img" type="str" optional>
  Single image applied to every task.
</ParamField>

<ParamField path="imgs" type="List[str]" optional>
  Per-task images aligned to `tasks` by index.
</ParamField>

**Returns:** `List[Any]` — results in the same order as `tasks`.

```python theme={null}
results = router.batch_run([
    "Summarize Q1.",
    "Summarize Q2.",
    "Summarize Q3.",
])
```

***

### `concurrent_run(task, img=None, imgs=None, *args, **kwargs)`

Execute one task in a separate thread using a `ThreadPoolExecutor`. Useful when calling the router from synchronous code that should not block.

```python theme={null}
result = router.concurrent_run("Summarize Q1.")
```

***

### `reliability_check()`

Validates the configuration (swarm type, per-type required parameters, `max_loops`) and then runs `setup()`. Called automatically at the end of `__init__`; you do not normally call it yourself. Raises `SwarmRouterConfigError` on invalid input.

***

### `setup()`

Applies pre-run configuration to the agents: auto-prompt-engineering (`auto_generate_prompts`), shared-memory activation (`shared_memory_system`), rules injection (`rules`), and the multi-agent collaboration prompt (`multi_agent_collab_prompt`). Called automatically during construction via `reliability_check()`. The underlying swarm itself is created lazily on the first `run()`.

***

### `to_dict()`

Serialize the router's configuration and current state to a dictionary suitable for logging or persistence.

**Returns:** `Dict[str, Any]`.

```python theme={null}
config = router.to_dict()
```

***

### `fetch_message_history_as_string()`

Return the underlying conversation as a single formatted string.

***

### `activate_shared_memory()` · `handle_rules()` · `activate_ape()`

Internal helpers used during `setup()` for shared-memory activation, rules injection, and auto-prompt-engineering. Rarely called directly.

## Required parameters by `swarm_type`

| `swarm_type`          | Additional required parameters                                                  |
| --------------------- | ------------------------------------------------------------------------------- |
| `SequentialWorkflow`  | `agents` (≥1)                                                                   |
| `ConcurrentWorkflow`  | `agents` (≥1)                                                                   |
| `AgentRearrange`      | `agents`, `rearrange_flow`                                                      |
| `MixtureOfAgents`     | `agents` (workers + aggregator as the **last** element)                         |
| `HierarchicalSwarm`   | `agents` (workers); director is created automatically                           |
| `GroupChat`           | `agents`, `speaker_fn` or `speaker_function`                                    |
| `MajorityVoting`      | `agents` (≥3 recommended)                                                       |
| `CouncilAsAJudge`     | `council_judge_model_name` (builds its own agents)                              |
| `LLMCouncil`          | `agents`, `chairman_model`, `aggregation_strategy`                              |
| `DebateWithJudge`     | `agents` (≥3: pro, con, judge)                                                  |
| `HeavySwarm`          | `heavy_swarm_worker_model_name`, `heavy_swarm_question_agent_model_name`        |
| `BatchedGridWorkflow` | `agents`, `tasks` passed to `run`                                               |
| `RoundRobin`          | `agents` (≥2)                                                                   |
| `MultiAgentRouter`    | `agents`                                                                        |
| `PlannerWorkerSwarm`  | `agents` (workers); planner is created automatically                            |
| `AutoSwarmBuilder`    | *Reserved — not dispatched by the current factory (raises `ValueError` at run)* |
| `auto`                | *Reserved — not dispatched by the current factory (raises `ValueError` at run)* |

## Autosave layout

When `autosave=True`, the router writes to:

```
{workspace_dir}/swarms/SwarmRouter/{name}-{timestamp_or_uuid}/
├── config.json    # written on __init__
├── state.json     # rewritten after each run
└── metadata.json  # rewritten after each run
```

`workspace_dir` resolves to the `SWARMS_WORKSPACE_DIR` env var if set, otherwise to the configured Swarms workspace.

## Usage Example

```python theme={null}
from swarms.structs.agent import Agent
from swarms.structs.swarm_router import SwarmRouter

researcher = Agent(
    agent_name="Research-Agent",
    system_prompt="You are a research specialist.",
    model_name="claude-sonnet-4-6",
)

analyst = Agent(
    agent_name="Analysis-Agent",
    system_prompt="You analyze research findings into actionable insights.",
    model_name="claude-sonnet-4-6",
)

router = SwarmRouter(
    name="research-analysis-swarm",
    description="A swarm for research + analysis tasks",
    agents=[researcher, analyst],
    swarm_type="SequentialWorkflow",
    max_loops=1,
    autosave=True,
    verbose=True,
)

result = router.run("Research recent trends in AI hardware and analyze them.")
print(result)
```

## Related Pages

* [SwarmRouter architecture overview](/architectures/swarm-router)
* [SwarmRouter example walkthrough](/examples/swarm-router-example)
* [MultiAgentRouter API reference](/api/multi-agent-router) — task-aware routing to one of N agents
* [AutoSwarmBuilder API reference](/api/auto-swarm-builder) — LLM-driven swarm construction

## Source

[`swarms/structs/swarm_router.py` on GitHub](https://github.com/kyegomez/swarms/blob/master/swarms/structs/swarm_router.py)