RoundRobinSwarm

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

pip install -U swarms

Import

from swarms import Agent, RoundRobinSwarm

The per-turn prompt builders are also importable for inspection or reuse:

from swarms.structs.round_robin import (
    RoundRobinSwarm,
    build_turn_header,
    build_collaborative_task,
)

Constructor

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",
)

str

default:"RoundRobinSwarm"

Name of the swarm. Also used to name the internal conversation.

str

Description of the swarm’s purpose.

List[Agent]

required

Agents that take turns in declared order. Required — constructing the swarm without agents raises ValueError.

bool

default:"False"

Enable verbose logging of each turn and loop.

int

default:"1"

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.

OutputType

default:"final"

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.

def run(self, task: str, *args, **kwargs) -> Union[str, dict, list]

str

required

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.

def run_batch(self, tasks: List[str]) -> List[Union[str, dict, list]]

List[str]

required

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

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

# 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

# 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

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

Opening message — the user task is added to the conversation as the first User message.
Deterministic schedule — for max_loops loops, the swarm iterates agents in insertion order: turn t goes to agents[t % N].
Full context — before each turn, the current full transcript is read and passed to the agent.
Role header — a per-turn header (see below) tells the agent its position, loop, previous/next speaker, and peers.
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.
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

Order matters — place agents in the sequence you want them to speak; the opener sets the framing for everyone after.
Agent diversity — use complementary roles so each turn adds a distinct perspective.
Loop count — start with max_loops=1; increase only when deeper back-and-forth is needed (cost scales with N * max_loops).
Output type — use "final" for a single answer, "list"/"dict" to inspect the whole collaboration.
Verbose mode — enable verbose=True while debugging to trace each turn.

Source Code

View the source code on GitHub.

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

RoundRobinSwarm

Overview

Installation

Import

Constructor

Methods

`run(task, *args, **kwargs)`

`run_batch(tasks)`

Usage Examples

Basic round-robin execution

Multiple loops

Different output types

Batch processing

How It Works

Per-turn prompt

Features

Best Practices

Source Code

​Overview

​Installation

​Import

​Constructor

​Methods

​run(task, *args, **kwargs)

​run_batch(tasks)

​Usage Examples

​Basic round-robin execution

​Multiple loops

​Different output types

​Batch processing

​How It Works

​Per-turn prompt

​Features

​Best Practices

​Source Code

Overview

Installation

Import

Constructor

Methods

`run(task, *args, **kwargs)`

`run_batch(tasks)`

Usage Examples

Basic round-robin execution

Multiple loops

Different output types

Batch processing

How It Works

Per-turn prompt

Features

Best Practices

Source Code