Inspect Swarm

Welcome

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.

Warning

Everything in Inspect Swarm is experimental and may change in any release without notice, including swarm(), member(), Budget, the built-in controller and channel names, and the record and evidence formats. No support is guaranteed.

Getting Started

Install it from PyPI:

pip install inspect_swarm

or, in a uv project:

uv add inspect_swarm

To install the latest development version from GitHub:

pip install git+https://github.com/meridianlabs-ai/inspect_swarm

or, in a uv project:

uv add "inspect_swarm @ git+https://github.com/meridianlabs-ai/inspect_swarm"

It needs inspect_ai 0.3.283 or later and Python 3.11 or later.

Run a swarm on an existing task

Pass swarm() as the solver. From Python:

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

From the command line:

inspect eval my_tasks.py --solver inspect_swarm/swarm -S 'members={factory: react, count: 4}'

Each sample runs four react() members, react-1 to react-4, 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 task’s scorer scores the answer as it would score a single agent.

--solver and eval(solver=...) replace the task’s whole solver, including any system message or tools it set up, so give the members their tools and prompt. Members use the eval’s model unless they are given one. The task’s setup solver still runs first.

A task with a swarm

A task can build the swarm itself. This one, from examples/getting_started.py, makes the number of members a task parameter:

from inspect_ai import Task, task
from inspect_ai.agent import react
from inspect_ai.scorer import match
from questions import QUESTIONS

from inspect_swarm import member, swarm


@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,
    )
inspect eval examples/getting_started.py --model openai/gpt-5-mini -T k=4
  • channels=[] gives the members no channel. The default, filesystem, tells members to share files in the sample’s sandbox, and these questions have none. See Channels.
  • The swarm takes its budget from the sample’s limits: here it stops its members at 95% of the token limit. See Budgets.
  • -T k=1 is a swarm of one, the single-agent arm to compare with. See Scoring.

What the log shows

Each member’s events are in a timeline named after it, so the log viewer can show one member’s trajectory. The sample’s messages are its input followed by the answer’s message. The swarm also writes three entries to the sample store:

  • inspect_swarm:result: each member’s state and status, and which member’s output is the answer. See Scoring.
  • inspect_swarm:ledger: the swarm’s caps and the usage and cost of each member. See Analysis.
  • inspect_swarm:metrics: tokens, cost and time for the swarm and each member, and counts of how members acted and communicated. See Analysis.

Learning more

  • Members: member records, names, limits, member builders, and how a member ends.
  • Controllers: when the swarm stops, and writing a controller of your own.
  • Channels and Shared Memory: how members share information, and waiting for each other.
  • Budgets and Sandboxes: the swarm’s caps and splits, and shared or per-member sandboxes.
  • Scoring, Analysis and Restrictions: the answer and the result record, metrics, the ledger, and what the swarm does not support or record.

The examples are runnable tasks for each of these. The designs behind the swarm are in design/.

For agents

The documentation is also published as Markdown for agents: