Skip to main content
Skip to main content
Edit this page

Subagents

Beta feature. Learn more.

A subagent is a child agent that a parent agent invokes to handle a self-contained subtask. The child runs with its own context window and its own attached tools, then returns a compact result to the parent. The parent never sees the child's intermediate steps — only the final answer.

Use subagents to keep a parent agent focused. Long research passes, tool-heavy exploration, and specialized review steps work better when their token-heavy intermediate state stays out of the parent's context.

Enable subagents​

In the Agent Builder, open Advanced settings and toggle Subagents. Two more controls appear:

  • Allow self-spawn — when on, the agent can spawn copies of itself for parallel work. Useful for fan-out patterns (one parent, several identical workers).
  • Additional subagents — pick specific other agents this parent is allowed to delegate to. The parent decides at runtime which subagent (if any) to call based on the task.

Save. When the agent runs, it has a new tool available for invoking subagents.

When a subagent helps​

  • Research subtasks — the parent decomposes a complex question, hands a slice to a subagent specialized for that slice, and synthesizes the responses.
  • Tool-heavy passes — code interpreter sessions, multi-step web search loops, or anything that would consume the parent's context with intermediate tool output.
  • Specialized review — one agent generates, another reviews, the reviewer's full reasoning stays in its own context window.

Avoid subagents for trivial calls. The handoff adds latency and tokens.

Subagents vs. agent chain​

Subagents are a runtime delegation mechanism — the parent decides on the fly. An agent chain is a pre-defined graph of agents that run in a fixed order. Reach for subagents when the routing is dynamic; reach for a chain when the routing is fixed.

Limits​

  • Max 10 subagents listed per parent.
  • Max depth of 5 hops from the root agent.
  • Max 50 unique subagent targets loaded for a single run.
  • Max 100 expanded subagent configurations per request.

Subagents you reference must be visible to the user running the parent. References that resolve to an inaccessible or deleted agent are skipped silently — design your parents to handle a missing child gracefully.