Loading the documentation…
Swarm spreads the work of one message across sub-agents that run at the same time. The Mind starts them when it decides the work can be split; each agent works in its own chat, and their reports come back into the main conversation when they finish.
The toggle appears only when the Mind includes swarm. A Mind manager switches it on with Parallel sub-agents on the Mind's AI Config tab; see Choose models and AI behaviour.
With the toggle on, the Mind may start parallel sub-agents for that message. A spawn starts 1 to 5 agents, and the Mind decides when a message is worth splitting. The Mind's Max concurrent agents setting, from 1 to 25 (10 by default), caps how many agents run at the same time in one chat.
While at least one agent is queued, running or waiting for you, a Swarm bar sits above the message box. It counts the agents, for example 1 waiting for you · 2 running · 1 queued, and it shows how long the longest-running agent has been working. When agents wait for you and none of them are running, the bar takes a warning tone. The bar disappears once every agent has finished, failed or stopped.
A node shows the agent's name, its status, when it started or finished, the tokens its own chat has spent (for example 12.3K tok), a short summary of its result once it finishes, and the names of the artifacts it delivered. A line to an agent animates while that agent is still live.
The six statuses are Queued, Running, Waiting for you, Completed, Failed and Stopped, and the window's footer lists them. Queued, Running and Waiting for you are live statuses; the others are endings.
If no agent has started yet, the window reads No swarm agents yet and suggests Turn on the swarm toggle in the composer and ask the mind to parallelize its work.
Swarm work also appears as step cards in the answer. A spawn card reads Spawning 2 agents… while the agents start, then Spawned 2 agents. Other steps read Swarm status, Agent stopped or Agent resumed. When a step fails, the card says so, for example Swarm agents not spawned, Message not delivered, Agent not stopped, Agent not resumed, Swarm status unavailable or Swarm report failed.
For the chat's own working, waiting and connection states, see Chat states and recovery.
Stopping an agent also closes whatever it was waiting for from you: a pending question is settled as skipped ("The user skipped this question"), and a waiting approval is declined with "The agent was stopped before a decision was made."
An agent that needs an answer or an approval from you shows the status Waiting for you, and it stays live while it waits.
A notice appears: the agent's name in quotation marks, followed by needs your decision. When the name is not known, it reads A swarm agent needs your decision. Click Open to jump to the agent's chat, or open it from its node, and decide there. The notice is skipped when you already have that chat open. A question it asks is answered like any other question from a Mind; see Questions from a Mind.
Some steps need something only a person can give, such as access to data. Those requests always wait for your approval, even when the chat is set to apply other changes automatically. See Change approval in a builder chat.
An agent waits for you for 24 hours. After that it continues on its own: a question is answered for it with "Nobody answered this question within 24 hours. Decide it yourself with the safest option the tools support, and name the question and your choice in your report.", and an approval is declined with "Nobody decided within 24 hours."
When no agent in the tree is still live, one message arrives in the main conversation with their reports. It opens with "[Swarm]" and counts what came back, as in "[Swarm] 2 sub-agent(s) finished. Their reports follow:". Under it, each agent has a section headed by its name and its status.
The Filed by swarm row counts what came back, for example 2 agents reported, and View report opens the full report. When there is no count, the row reads Report filed.
The Swarm Report shows one section per agent, with its summary and the artifacts it produced. A SQL badge marks SQL artifacts. Click an artifact chip to open the artifact; on desktop the report closes behind it. If an artifact cannot be opened, the chip is dimmed and its tooltip reads Artifact not available. If nothing was recorded, the report reads No report details available.
Every swarm step also appears in Tool History (Ctrl+Shift+H). Open a step to read more: Requested agents lists the full task each agent received and any artifacts attached to it, Swarm status shows a table with every agent's Status, Depth and Tokens, and Reports holds the report content.
Click an agent in the tree to open its chat. Messages that the parent chat delivered are marked Task from parent.
The Delivered artifacts card shows what the parent sent with the agent, for example Delivered artifacts (3). A + briefing badge means a briefing came along. A chip marked no data attached means the parent left result rows out of the delivery, and the agent runs the query itself. Hover the chip to read why:
If the card has no details, it reads No artifact details available. Instructions that the parent writes to an agent stay out of the visible chat; the Delivered artifacts card is the record of what arrived.
An agent's chat follows the main conversation for some settings:
/ is not available in an agent's chat.No. The toggle only lets the Mind split the work of that message. The Mind decides when it needs sub-agents, and it starts 1 to 5 of them when it does.
At most five live ones: queued, running and waiting for you all count. While five are live, a further spawn is refused with "A parent may have at most 5 live sub-agents at a time." Across the whole chat, the Mind's Max concurrent agents setting (1 to 25, 10 by default) caps how many run at once.
The agent is blocked until you answer it or approve something. Open its chat from the tree, or click Open in the notice, and answer there. If nobody answers within 24 hours, the agent continues on its own; see Answer an agent that waits for you.
The agent stops, and every agent below it stops with it; the rest of the tree keeps running. Nothing is left hanging: a pending question is settled as skipped, and a waiting approval is declined with "The agent was stopped before a decision was made." To stop everything, use Stop all.
Yes, if its status is Stopped or Failed. Use Resume agent {name} on its node in the tree. Any other status is refused with "Only stopped or failed agents can be continued."
Click View report on the Filed by swarm row to open the Swarm Report. For the steps behind it, open the swarm entries in Tool History: Requested agents lists the full task each agent received.
A conversation runs one turn at a time, and an agent works inside its own chat. While its turn runs, sending there is refused with "This conversation is already running a turn." Wait for the turn to end.
Yes. The agents work inside their own chats, so you can keep using the main conversation. Their report is delivered when no agent is still live; if the chat is busy at that moment, it arrives when the chat is free.
One turn of an agent is cut off after 150 minutes: "The swarm turn did not finish within 150 minutes." If an agent did not finish, its section in the report says how it ended.
For most steps they follow the chat's acceptance mode. A step that needs something only a person can give, such as access to data, always waits for your approval, even when the chat is set to apply other changes automatically. See Change approval in a builder chat.
A stopped agent's section in the report says "Stopped before filing a report." An agent that waited longer than its session allows was closed automatically, and its section says it was reaped. You can resume it from the tree while its status is Stopped or Failed.
That answer replies to the agents' report, not to a message of yours, so it has no Retry with configuration. It already runs with the settings of your last message in the chat. To change the settings, send a new message with the ones you want.