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:
- Build. Every member gets a fresh
Agent, a random public name such asagent_17, and a shuffled list of teammates. Agents are rebuilt on everyrun(), so runs never share history. - 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.
- 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_messagesto read them. - Idle. A member that ends a response without a tool call becomes idle and spends nothing. A new message wakes it.
- Finish. A member answers with a line that starts with
####. The work phase ends when an answer passes the verifier, when a task tool callssolve(), when every member is idle or finished, or when the token allowance ortimeoutruns out. - 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.
Installation
Constructor
Model for every member. The model must support tool calling when
communication=True or when you pass task_toolsFalse 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 taskGeneration 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 limitSafety cap on model calls between two idle periods. The token allowance and
timeout are the real limitsWall-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
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 theserun()
One string per member, appended to that member’s first message. The length must equal
num_agents, or ValueError is raisedReturns
True for a correct final answer. It enables success, early stopping and the team reward. A verifier that raises counts as FalseA 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 runAsked of every member without an answer when the work phase ends.
None skips the final-answer phaseMessaging tools
Withcommunication=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 withcommunication=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 callssolve() 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=Falseas the matched baseline.
HierarchicalSwarm or PlannerWorkerSwarm is more predictable. When the members don’t need each other’s work, ConcurrentWorkflow or MajorityVoting is cheaper.