Subagent

agent_spawn

Group: Agent orchestration
Turned on by: Its own switch on the Tools page of Conversation settings.
Approval: Reviewed: writes and open-ended actions ask for approval unless the security level or an earlier “Always allow” covers them.
Profile key: tool.agent_spawn.description

Starts a subagent: a separate model run that works on one task in the background and reports back to this conversation.

By default the subagent sees only the task the model writes, not this conversation. Its result comes back through task_wait or in a box row. See Subagents and workflows.

When it asks you

Under Manual, each new subagent asks first; the card offers Always allow.

Limits

At most 8 background tasks run at once in a conversation, counting subagents, workflow runs and background commands. Starting a ninth is refused until one finishes, whether or not its result was collected; a command that reaches its timeout still moves to the background, even past the limit.
The result is the subagent's final reply, cut at 64 KiB.

Good to know

A subagent has the conversation's tools except agent_spawn, workflow, ask_user, fork and the plan and handoff tools. Its background commands report to it, and any still running when it gives its final reply are stopped.
Stopping the turn does not stop a subagent. Stop it from its row in the Tasks pane (More options → Tasks).

Parameters

Parameter	Type	Details
`name` required Name	string	Required. Name this child yourself: it is both the address task_wait takes and the title the task is listed under. Say what the child is for (researcher, review-api), not what you are asking it right now. The name is reserved for the whole conversation branch tree, so it must not repeat one already used here.
`prompt` required Prompt	string	The child's entire task; it sees nothing else of this conversation by default.
`agent_type` Named agent type	string	Name of a host-resolved trusted agent definition. The schema you actually receive lists this conversation's names as an enum here. The definition's prompt, model and memory identity are not model-writable.
`context` Initial context	string	none: the child sees only the task. conversation: a filtered copy of this conversation's history is attached. `"none"` `"conversation"` Default `"none"`
`label` Display name	string	Short display name shown on the timeline.
`schema` Output schema	object	JSON Schema subset the child must satisfy via structured_output; the validated value returns with task_wait. Top level must be an object schema; supported keywords: type, properties, required, items, enum, const, additionalProperties, minItems/maxItems, minLength/maxLength, minimum/maximum. Others are rejected.