Skip to main content

Overview

SelfOrganizingSwarm runs N copies of one model as a team with no leader, no roles and no turn order. Every member gets the same task, its own history and, optionally, its own private input and its own copy of any task tools. Members decide for themselves when to talk, using three messaging tools. It is an inference-only port of the harness from s³, “Simple Scaling of Swarms via Cooperative Multi-agent RL” (Jha, Faria, Li, Geng et al., 2026, scalingswarms.com). The paper trains the coordination with RL. This class keeps the harness and the shared objective and leaves out the training, so any tool-calling model can run in it. How one run works:
  1. Build. Every member gets a fresh Agent, a random public name such as agent_17, and a shuffled list of teammates. Agents are rebuilt on every run(), so runs never share history.
  2. Work. Each member runs in its own thread and carries on as soon as its own tool call returns. No member waits for a slower one.
  3. Notify. When a message arrives, the recipient gets a notice between its model calls listing unread counts by sender. The notice never includes message contents. The member calls read_messages to read them.
  4. Idle. A member that ends a response without a tool call becomes idle and spends nothing. A new message wakes it.
  5. Finish. A member answers with a line that starts with ####. The work phase ends when an answer passes the verifier, when a task tool calls solve(), when every member is idle or finished, or when the token allowance or timeout runs out.
  6. Final answers. Members that have not answered are asked once for a final answer. In this phase the last non-empty line of the reply counts as the answer if it has no #### line.
Every member is told the team is scored as one: it succeeds if any member is right, and there is no bonus for being the one who answers.

Installation

Constructor

str
default:"SelfOrganizingSwarm"
Name of the swarm
str
What the swarm is for
int
default:"4"
Team size N. Must be at least 1, or ValueError is raised
str
default:"gpt-5.4"
Model for every member. The model must support tool calling when communication=True or when you pass task_tools
bool
default:"True"
False gives members no messaging tools and a solo prompt, so the run is N independent attempts. Use it as the best-of-N baseline for the same task
Optional[int]
default:"8192"
Generation allowance L for each member, counted from the provider’s reported output tokens. A member that reaches it stops working and is asked for a final answer. None removes the limit
float
default:"0.25"
λ in the team reward. 0 turns the cost term off
int
default:"100"
Safety cap on model calls between two idle periods. The token allowance and timeout are the real limits
float
default:"900.0"
Wall-clock limit for the work phase, in seconds. It is checked between model calls and while members are idle, so a model call already in progress is allowed to finish
bool
default:"True"
End the run as soon as an answer passes the verifier
Optional[int]
default:"None"
Seeds the member names and teammate order
Optional[Dict[str, Any]]
default:"None"
Extra keyword arguments for every member’s Agent. By default members are built with print_on=False, reasoning_prompt_on=False, persistent_memory=False and tool_retry_attempts=1; values in agent_kwargs override these
bool
default:"False"
Log every message as it is sent

run()

str
required
The problem, shown to every member as its first message
Optional[List[str]]
default:"None"
One string per member, appended to that member’s first message. The length must equal num_agents, or ValueError is raised
Optional[Callable[[str], bool]]
default:"None"
Returns True for a correct final answer. It enables success, early stopping and the team reward. A verifier that raises counts as False
Optional[Callable]
default:"None"
A factory called once per member as task_tools(agent_name, solve). It returns that member’s private list of tool functions. Calling solve(answer) from a tool marks the team as solved and ends the run
str
default:"\"\""
Task-specific rules added to every member’s system prompt
Optional[str]
default:"DEFAULT_FINAL_PROMPT"
Asked of every member without an answer when the work phase ends. None skips the final-answer phase

Messaging tools

With communication=True, every member gets: A tool that raises returns its error as text instead, so the agent’s tool retry never resends a message.

Result

run() returns a dict:

Examples

Private information

Three members each hold one number and have to message each other to submit all three sorted.

Best-of-N baseline

Run the same task with communication=False to compare the swarm with N independent attempts at the same cost settings.

Task tools that end the run

Give each member its own copy of an environment. A tool calls solve() when the goal is reached, which marks the team as solved and stops every member.

When to choose SelfOrganizingSwarm

  • The task splits naturally but you don’t want to hard-code who does what.
  • Members hold different private information that only helps once shared.
  • You want to measure whether communication helps, with communication=False as the matched baseline.
When the split is known ahead of time, HierarchicalSwarm or PlannerWorkerSwarm is more predictable. When the members don’t need each other’s work, ConcurrentWorkflow or MajorityVoting is cheaper.

Source code

View the source code on GitHub