> ## 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.
# RoundRobinSwarm
> A swarm that executes a task across agents in deterministic round-robin order, each agent building on the shared transcript
## Overview
`RoundRobinSwarm` visits agents in their **declared insertion order**, cycling through the full roster once per loop. The schedule is deterministic and identical on every loop:
```
turn t -> agents[t % N] for t in range(max_loops * N)
```
Every agent reads the full conversation transcript accumulated by the agents that spoke before it, and each agent receives exactly `max_loops` turns. Before each turn the swarm injects a role header telling the agent its position, the current loop, the previous/next speaker, and the other participants, then asks it to build on the prior contribution.
Earlier versions of `RoundRobinSwarm` shuffled agents randomly each loop and supported `callback` / `max_retries` parameters. Those are **removed** — the order is now strictly deterministic and those parameters no longer exist.
## Installation
```bash theme={null}
pip install -U swarms
```
## Import
```python theme={null}
from swarms import Agent, RoundRobinSwarm
```
The per-turn prompt builders are also importable for inspection or reuse:
```python theme={null}
from swarms.structs.round_robin import (
RoundRobinSwarm,
build_turn_header,
build_collaborative_task,
)
```
## Constructor
```python theme={null}
RoundRobinSwarm(
name: str = "RoundRobinSwarm",
description: str = "A swarm implementation that executes tasks in a round-robin fashion.",
agents: List[Agent] = None,
verbose: bool = False,
max_loops: int = 1,
output_type: OutputType = "final",
)
```
Name of the swarm. Also used to name the internal conversation.
Description of the swarm's purpose.
Agents that take turns in declared order. **Required** — constructing the swarm without agents raises `ValueError`.
Enable verbose logging of each turn and loop.
Number of full passes over the roster. Each agent speaks exactly once per loop, so with `N` agents and `max_loops` loops the swarm runs `N * max_loops` turns total.
Output format applied to the conversation history. Common values: `"final"` (last message only), `"list"`, `"dict"`, `"str"`, `"json"`.
## Methods
### `run(task, *args, **kwargs)`
Execute the task across the agents in deterministic round-robin order. Returns the conversation in the format specified by `output_type`.
```python theme={null}
def run(self, task: str, *args, **kwargs) -> Union[str, dict, list]
```
The task to execute. Posted as the opening `User` message that the first agent responds to.
`*args` / `**kwargs` are forwarded to each underlying `agent.run()` call.
**Returns:** the task result formatted per `output_type`.
**Raises:** re-raises any exception thrown by an agent during execution.
***
### `run_batch(tasks)`
Execute multiple tasks sequentially. Each task runs through its own full round-robin cycle.
```python theme={null}
def run_batch(self, tasks: List[str]) -> List[Union[str, dict, list]]
```
Tasks to execute, one full round-robin run per task.
**Returns:** a list of results in the same order as `tasks`.
## Usage Examples
### Basic round-robin execution
```python theme={null}
from swarms import Agent, RoundRobinSwarm
agents = [
Agent(
agent_name="Analyst",
system_prompt="You are a data analyst. Analyze information critically.",
model_name="gpt-5.4",
max_loops=1,
),
Agent(
agent_name="Strategist",
system_prompt="You are a strategist. Think about long-term implications.",
model_name="gpt-5.4",
max_loops=1,
),
Agent(
agent_name="Implementer",
system_prompt="You are an implementer. Focus on practical execution.",
model_name="gpt-5.4",
max_loops=1,
),
]
swarm = RoundRobinSwarm(agents=agents, max_loops=1, verbose=True)
result = swarm.run("How should we approach building a new AI product?")
print(result)
```
### Multiple loops
```python theme={null}
# Two full passes: each agent speaks twice, in the same order each loop.
swarm = RoundRobinSwarm(
agents=agents,
max_loops=2,
verbose=True,
)
result = swarm.run("Develop a comprehensive marketing strategy.")
```
### Different output types
```python theme={null}
# Final message only (default)
final_swarm = RoundRobinSwarm(agents=agents, output_type="final")
final_result = final_swarm.run("Analyze this problem.")
# Full conversation as a list of messages
list_swarm = RoundRobinSwarm(agents=agents, output_type="list")
list_result = list_swarm.run("Analyze this problem.")
# Full conversation as a dict
dict_swarm = RoundRobinSwarm(agents=agents, output_type="dict")
dict_result = dict_swarm.run("Analyze this problem.")
```
### Batch processing
```python theme={null}
tasks = [
"Analyze market trends in AI",
"Develop a product roadmap",
"Create a risk assessment",
]
results = swarm.run_batch(tasks)
for i, result in enumerate(results):
print(f"\nTask {i + 1} Result:\n{result}")
```
## How It Works
1. **Opening message** — the user task is added to the conversation as the first `User` message.
2. **Deterministic schedule** — for `max_loops` loops, the swarm iterates `agents` in insertion order: turn `t` goes to `agents[t % N]`.
3. **Full context** — before each turn, the current full transcript is read and passed to the agent.
4. **Role header** — a per-turn header (see below) tells the agent its position, loop, previous/next speaker, and peers.
5. **Collaborative reply** — the agent is asked to build on the prior speaker's contribution (or address the task directly if it opens), and its response is appended to the transcript.
6. **Formatted output** — after all loops complete, the conversation is returned per `output_type`.
## Per-turn prompt
Each agent receives a generated header and a standing instruction, produced by `build_turn_header` and `build_collaborative_task`. The running transcript is **not** concatenated into this prompt string — `run()` calls `build_collaborative_task(conversation_context="", turn_header=turn_header)`, so the prior-turns transcript is delivered separately to the agent via the `messages` argument of `agent.run()`, not as literal text in the task prompt:
```
You are Analyst, agent 1 of 3 in loop 1 of 2. Previous speaker:
(none — you open the conversation). Next speaker: Strategist.
Other participants: Strategist, Implementer.
Review the transcript above and build on the prior speaker's contribution.
Add your own perspective concisely; if you are the opening speaker, address
the original task directly.
Your response:
```
## Features
* **Deterministic order** — agents always speak in declared insertion order, identically every loop.
* **Full context** — each agent sees the complete transcript accumulated so far.
* **Collaborative prompting** — agents are told their position and neighbors and asked to build on prior turns.
* **Flexible output** — choose `"final"`, `"list"`, `"dict"`, `"str"`, or `"json"`.
* **Batch processing** — `run_batch` runs many tasks, one full cycle each.
* **Serializable** — inherits `SerializableMixin` for config serialization.
## Best Practices
1. **Order matters** — place agents in the sequence you want them to speak; the opener sets the framing for everyone after.
2. **Agent diversity** — use complementary roles so each turn adds a distinct perspective.
3. **Loop count** — start with `max_loops=1`; increase only when deeper back-and-forth is needed (cost scales with `N * max_loops`).
4. **Output type** — use `"final"` for a single answer, `"list"`/`"dict"` to inspect the whole collaboration.
5. **Verbose mode** — enable `verbose=True` while debugging to trace each turn.
## Source Code
View the [source code on GitHub](https://github.com/kyegomez/swarms/blob/master/swarms/structs/round_robin.py).