subagents=True, an agent gets a spawn_agent tool. With it, the model launches a fresh agent for a self-contained task (a search, reading a batch of documents, an independent sub-question) and gets back only its final report. The intermediate tool results stay in the sub-agent’s context, not the orchestrator’s: long investigations no longer fill the main context window.
What the model decides
In eachspawn_agent call the model writes:
A sub-agent gets nothing else: not
spawn_agent (sub-agents cannot launch sub-agents), not the memory tools. Several calls in one turn run in parallel.
Settings
Events and usage
Each sub-agent emitssubagent_started (call id, sub-agent id, description, tools, skills, model) and subagent_completed (finish reason, usage, duration). In run_stream and arun_stream, the sub-agents’ own events are forwarded live, tagged with metadata["subagent_call_id"]. See Streaming.
Their spend is folded into the orchestrator’s run (response.usage) and broken out in response.delegation_usage.
Approvals
A sub-agent may use tools declared withrequires_approval=True. When it calls one, the orchestrator’s run pauses with finish_reason="approval_required"; the requests carry subagent_call_id, the id of the spawn_agent call. The next run(approvals={...}) hands the decisions down and the sub-agent resumes where it stopped. A new message instead of an answer stops the paused sub-agent.
A paused sub-agent lives in memory: unlike a paused agent, it cannot be resumed in another process. See Tool approvals.
Tracing
Thespawn_agent span records the request (gwenflow.subagent.description, .tools, .skills, .model, .model_name) and gwenflow.delegation.finish_reason; the sub-agent’s spans nest under it, named sub-agent: <description>. See Telemetry.