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 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. Each run starts from an empty conversation, so a reused swarm never carries an earlier task’s transcript.

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". The conversation records timestamps and message IDs, so "str" lines carry a timestamp and "dict" entries carry extra fields.

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. The conversation is cleared, then the task is posted as the opening User message that the first agent responds to.

*args / **kwargs are forwarded to each underlying agent.run() call. The swarm passes messages= itself, so do not pass that keyword. 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, starting from an empty conversation.

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 conversation is cleared and the user task is added 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 as typed turns — before each turn, the whole conversation is passed to the agent as chat messages: the task as a user turn, the agent’s own earlier replies as assistant turns, and every other agent’s replies as user turns prefixed with the speaker’s name.
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). Its final answer, not its whole transcript, is appended to the conversation under its name.
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 are delivered separately as typed chat messages 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 conversation so far, with its own replies kept distinct from its peers’.
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