Agent Swarms with Inspect

An experimental package for running swarms of agents on Inspect tasks and comparing them against a single agent.
Authors

Ransom Richardson

Alexandra Abbas

Published

November 18, 2026

Inspect Swarm runs a swarm of agents on one sample of an Inspect task. A swarm is an Inspect agent, so it replaces the task’s solver, and the task’s scorer scores the swarm’s answer the same way it would score a single agent. Everything in the package is experimental and may change in any release. We’re sharing it now because the question it is built to ask, whether a team of agents beats one agent at the same budget and by how much, is one that several groups are already answering with harnesses of their own.

Pass swarm() as the solver of an existing task:

from inspect_ai import eval
from inspect_ai.agent import react

from inspect_swarm import member, swarm

from my_tasks import my_task

eval(
    my_task(),
    solver=swarm(members=member(react, count=4)),
    model="anthropic/claude-sonnet-4-5",
)

Each sample runs four react() members at the same time. Each starts with the sample’s input and a short preamble: its name, the number of members, and how to share files. The swarm stops at the first submission and uses it as its answer. The other members finish the calls they have in flight and stop. The same swarm runs from the command line with --solver inspect_swarm/swarm -S 'members={factory: react, count: 4}'.

A task can also build the swarm itself, which makes the number of members a task parameter:

@task
def getting_started(k: int = 3) -> Task:
    return Task(
        dataset=QUESTIONS,
        solver=swarm(members=member(react, count=k), channels=[]),
        scorer=match(),
        token_limit=200_000,
    )

-T k=1 is a swarm of one: a single agent run under the swarm’s rules with the same records, which is the arm to compare against. baseline() builds that arm with the same result contract as the swarm.

Members, Controllers, Channels, and Budgets

A swarm is composed from four pieces, each of which can be changed on its own:

  • Members are agents registered with @agent, such as react() or deepagent(). Give a factory and a count, or an agent you have built. Members can have roles, their own models, their own limits, and their own sandboxes.
  • Controllers decide which members start, when, and when the swarm is done. The built-in leaderless controller starts every member and stops as soon as the answer can no longer change: at the first submission by default, or at the first that passes a check when the swarm is given one. A controller of your own is a short async function: start one member and escalate to the rest only if it gives up, or hand tasks in turn to a persistent member that keeps its context between activations.
  • Channels decide how members share information. The default filesystem channel states a convention for sharing files in the sandbox. shared_memory gives members a board of files with a record of every write and read, messages gives them direct messages, and topics gives them named rooms with declared readers and writers. With these channels, a member that needs a peer’s work waits for it with swarm_wait instead of polling.
  • Budgets cap cost, tokens, and time. By default the swarm derives its caps from the sample’s limits and members share them as a pool. split="equal", or weights of your own, gives each member a fixed share instead, so the split stays a condition of the experiment. Members can check what is left with the swarm_resources() tool.

What the Log Records

Inspect View shows the swarm as one agent with a lane for each member, so you can follow one member’s trajectory at a time. When the swarm ends it writes a result record to the transcript with each member’s state and status and which member’s output is the answer, which swarm_result() reads back. It also writes a ledger of the caps and each member’s usage and cost, and metrics covering tokens, time, how members acted and communicated, and the critical path: the number of model calls the answer depended on, one after another, across members. SwarmColumns adds each sample’s cost and the ledger’s caps to samples_df() for analysis.

Sweeps

Agent count, budget, and split are task parameters, so they sweep like anything else:

inspect eval examples/budget_sweep.py -T k=8 -T budget=8 -T split=equal

Hold the budget fixed and vary k. Or fix a per-agent budget b, run budget = k * b with an equal split, and vary both. Or hold k and the budget and vary the split as an ablation. Compare arms on the cost the log records rather than on the caps.

Additional Capabilities

Beyond those four pieces, the package covers much of the rest of a multi-agent experiment:

  • Choosing the answer. A result contract gives the swarm the task’s answer key and its own check, and the controller’s answer chain picks the answer by first, last, verify, vote, or synthesize, a final model call that combines the members’ submissions.
  • Scoring each member. member_scores() grades every member’s output as if it had run alone, giving team@k and the mean member. Per-member artifacts do the same for tasks scored on what the members leave in the sandbox.
  • Independent attempts. select_at_k() applies the swarm’s answer rule to k independent single-agent attempts, a comparison in which neither side uses the target.
  • Holding members between turns. Boundary callbacks let a controller read or replace a member’s conversation at each turn boundary, hold it there, or end it.
  • Reports from the world. Code that owns the environment reports each change with world_report(), from the host or from a sandbox, so a controller can stop the swarm on the state of the world, such as a cluster losing its quorum.
  • Operating a running swarm. inspect ctl sample agent messages, pauses, resumes, or stops any member of a running swarm by name.
  • CLI agents as members. Bridged members, such as inspect_swe’s agents, run a CLI agent in the sandbox and reach the shared memory and messages through swarm_bridged_tools().
  • Monitoring with Inspect Sentinel. Writes to the shared memory are ordinary tool calls, so an Inspect Sentinel protocol can screen them before they reach the board.
  • Members that choose their names. With choose_name=True, members are not told their names and introduce themselves to each other.
  • Channels of your own. A custom channel goes through the same bus as the built-in ones, so its sends and reads are recorded, and the reads it reports link into the critical path.

Install Inspect Swarm from PyPI with pip install inspect_swarm. It needs Python 3.11 or later and inspect_ai 0.3.291 or later. The documentation has runnable examples for each of the pieces above, and is also published as Markdown for agents in llms.txt. The designs behind the package are in the repository’s design directory.