Sub-agents¶
An agent can hand a piece of work to a sub-agent: a separate agent, in its own sandbox, that runs one task, reports one result back, and is then removed. You don't create sub-agents yourself. You ask an agent to delegate, and it starts them. The chat calls each one a temporary agent.
When an agent uses one¶
Most harnesses have their own built-in helpers, which work inside the agent's own sandbox, start in seconds and use no extra compute. Agents are told to prefer those. A sub-agent is for work that needs something only a separate agent gives:
- a different harness
- its own setup: a repository, an install command, environment variables, or skills
- more CPU, memory, or disk than the agent has
- isolation from the agent's own workspace
- heavy parallel work
- a result checked against a fixed shape
The agent decides which to use. If you specifically want separate agents, say so and say why. The agent can also choose each sub-agent's harness and model, for instance a cheaper model for a mechanical step, or the same task on two models to compare. It can hand work off directly, or write a script that fans a lot of work out. Both show up the same way in the chat.
A sub-agent runs its task to the end without asking you anything, so a good request gives it everything it needs up front.
What you see¶
The agent's message in the chat carries a block that says how many temporary agents it delegated to, and how many are still working or have failed. Each sub-agent gets a row showing the first line of its task and its status:
| Status | Meaning |
|---|---|
| Working | It's running the task. |
| Waiting for room | It's waiting for compute to free up in your budget, and starts on its own once there's room. |
| Done | It reported a result. |
| Failed | It ended without a result. The row says why. |
Expand a row to see the Prompt it was given, its Result once done, and two actions:
- Open conversation opens the sub-agent's conversation beside the chat, read-only. It's available once the sub-agent has reported. While it's still working, the button is disabled. Occasionally a conversation isn't kept, and the button says so.
- Stop ends a running sub-agent after you confirm. It's removed, and the agent gets a failed result.
A sub-agent that delegates further shows its own sub-agents nested inside its row. The block stays in the conversation after the sub-agents are gone, so you can come back to the results later.
Where they run¶
Each sub-agent is an agent of its own, but it doesn't get a row on Home. While any are running, the row of the agent that started them says how many temporary agents are running and what they're using.
A sub-agent is removed shortly after it reports. It also fails and is removed if it runs past the time limit the agent gave it, if a setup step fails, or if it restarts. Deleting the agent that started it fails its running sub-agents and removes them.
While an agent has sub-agents running, it doesn't hibernate, even if nobody is chatting with it. Stopping or pausing it still works. If the agent handed work off directly and ended its turn before a sub-agent finished, the result arrives later as a new turn in the conversation, and wakes the agent if it needs to. A stopped agent isn't started for it. The result waits until you start the agent again.
What a sub-agent can use¶
- Model provider: the same one as the agent that started it. A harness that can't run on that provider is refused before anything is created.
- Connections: only the ones the agent passes on, and only from connections already granted to it. A sub-agent never gets more than its agent has.
- Network access: the network rules of the agent you asked. A request those rules neither allow nor deny raises an approval for that agent, and allowing it permanently adds the rule there.
- Compute: a sub-agent counts against your budget like any running agent. One too large for your whole budget is refused at once.