Agent swarms

One agent holds one conversation well. Some jobs are bigger than that: audit a repository, research every account on a list, work through a backlog of tickets. For those you give the job to a swarm — a set of agents that split the work, talk to each other, and roll their results up to one place.

A swarm is nothing new to set up. It is ordinary agents in an agent group. What this page adds is how to shape the group so the swarm stays coherent at ten agents or a thousand, and how to watch and stop it.

Agents ask each other

Agents in the same group can reach each other with the ask_agent tool. An ask is a self-contained request: the peer runs its own turn, with its own knowledge and tools, and sends back a plain-text reply. The asker normally gets that reply as a follow-up after its own turn ends; it can also wait for it inside the turn when it needs the answer right away. Your contacts never see these exchanges.

Every group also has a shared note. It is where the group writes down what it has settled: decisions, who covers what, findings so far. Each member reads the note at the start of a turn and can rewrite it with group_note_write. The note is capped at 4,000 characters, so agents keep what still holds and drop what does not. You can read, seed or correct the note on the Groups page, and every version is kept, so you can look back at what the group knew and when.

Flat or tiered

A group without a hub is flat: every member sees and can ask every other member. That is the right shape for a handful of agents with distinct roles — a researcher, a writer, a checker.

A group with a hub is a tier. Pick one member as the hub and the others become its spokes. Spokes see and ask only the hub; the hub sees and asks its spokes. In a tier only the hub writes the note, so thirty spokes reporting at once cannot overwrite each other. A group has at most one hub.

Tiers stack. A hub of one group can be a spoke in another, which is how a swarm grows past one hub: workers report to their hub, hubs report to a lead. An ask travels at most three hops, so lead → hub → worker is as deep as a swarm goes.

Sizing a swarm

Size the swarm from the work, not from a number.

• Split the goal into units that can proceed without talking to each other, and give each unit one worker. A unit that cannot be split — one candidate to reproduce, one account to research — is one worker.
• Put workers under a hub once there are more than a handful. A hub folds six to eight spokes into one note comfortably.
• With one hub, that hub is your lead. With two or more, add a separate lead: hubs cannot reach each other, so without one nobody merges their results. Two hubs with three workers each is nine agents in three groups — one group per hub with its workers, and one group with the lead as hub and the two hubs as spokes.
• Give every member a short description of its slice when you add it to the group. That is how the others know whom to ask for what; you never list peers by hand in a prompt.
• Each prompt names the agent's own slice, what "done" looks like, and whom it reports to. Spokes report findings to their hub; hubs fold them into the note and roll up to the lead.

Workers that must read a repository, run commands or build a reproduction need Run code turned on, so each works in its own sandbox. Hubs and leads do not — they read replies and keep the note.

You can also describe the goal to Copilot. It sizes the swarm the same way, tells you the shape and the expected spend, and creates the agents and their groups once you approve. Workers it creates with a sandbox run their commands themselves rather than handing each one to a sub-agent, which is what you want for long, hands-on work.

Watching a swarm

The Groups page shows a live roster for each group: every member with its state — running, waiting on a peer, idle or ended — its turns and asks in flight, background tasks, and the tokens and cost of the last 24 hours, with totals for the group. The group note is where the result accumulates.

Each agent's conversations show the same liveness. A conversation is Working while a turn or a background task runs for it, and Waiting while it has an ask out to a peer. Tasks an agent delegated appear on its conversation page while they run, with a Cancel for each.

Stopping a swarm

End all on a group ends every live exchange among its members and cancels their background tasks in one step. Only owners and admins can do it. Asks that were still waiting are answered with a notice that the exchange was ended, and an ended exchange stays ended: a member that asks that peer again is refused and told to finish with what it has. The note and every conversation stay as they were; reopen a conversation to let the pair talk again.

To stop one piece of work, cancel the background task from the conversation page. The agent that delegated it is told it was cancelled and carries on with what it has.

Agents can also stop themselves: an agent that asks the same peer more than twenty times in an hour on one thread is refused, which ends a runaway ask-and-reply loop before it spends two agents' turns.