Use Sub-Agents

Sub-agents allow a parent agent to delegate specialized tasks to child agents that run concurrently in isolated sessions. The parent orchestrates, waits for results, and aggregates them into a unified output.

Expand

When to use sub-agents

Use sub-agents when a task naturally decomposes into parallel, specialized workstreams:

• Research + Code + Review in parallel
• Testing multiple approaches simultaneously
• Processing large datasets in chunks
• Delegating domain-specific work (e.g., a security reviewer sub-agent alongside a coder)

Sub-agent roles

Each sub-agent is assigned a role that shapes its system prompt and behavior:

Role	Specialization
researcher	Information gathering, search, synthesis
coder	Code generation, debugging, refactoring
reviewer	Code review, security audit, quality checks
tester	Test writing, test execution, coverage analysis
analyst	Data analysis, reporting, metrics
creative	Writing, content creation, brainstorming
general	General-purpose (no specialization)

How to spawn sub-agents

In the chat interface, ask your agent to delegate work:

Example prompt: “Spawn a researcher sub-agent to investigate the latest OAuth2 best practices, and a coder sub-agent to refactor auth.py. When both are done, synthesize their findings into a pull request description.”

The parent agent handles sub-agent spawning internally. You simply describe the delegation in natural language and the agent takes care of assigning roles, goals, and tool access for each sub-agent.

Concurrency limits

Limit	Default
Max concurrent sub-agents globally	8
Max per parent agent	5
Max nesting depth	3 levels
Max sub-agents per session	50

Approval gates

Sub-agents can require human approval before starting. Configure this in the agent’s settings:

• Auto-approve: All sub-agents start immediately (default for trusted agents)
• Approval required: Parent pauses until you approve each sub-agent
• Mid-run approval: Sub-agents can request approval mid-execution for risky actions

In the UI, pending approvals appear as a badge in the chat header.

Tool isolation

Each sub-agent runs in an isolated session with a filtered tool set. The parent agent controls which tools each sub-agent can access. You can configure tool restrictions in the agent’s Settings tab under Tools — select an allowlist of permitted tools or a denylist of blocked tools for each sub-agent role.

Resource budgets

Sub-agents have per-agent token and cost limits to prevent runaway spending. Configure budgets in the agent’s Settings tab:

Setting	Description
Max Tokens	Maximum token consumption per sub-agent (e.g., 50,000)
Max Cost (USD)	Maximum dollar spend per sub-agent (e.g., $0.50)

At 80% of budget, the parent receives a warning. At 100%, the sub-agent is cancelled and a partial result is returned.

Aggregation strategies

When multiple sub-agents complete, the parent uses an aggregation strategy to combine results:

Strategy	Description
concatenate	Append results in order
structured_merge	Merge JSON objects from each sub-agent
ai_summarize	Use an LLM to synthesize results
pipeline	Pass output of each sub-agent as input to the next

Shared context

Sub-agents can collaborate through a shared context pool — a key-value store that all agents in the same session can read and write:

# Sub-agent A writes research findings
shared_context.write("oauth_findings", {"pkce_required": True, "sources": [...]})

# Sub-agent B reads them to inform code changes
findings = shared_context.read("oauth_findings")

Changes to shared context are tracked with a history log.

Peer messaging

Sub-agents can send messages to each other:

For example, a researcher sub-agent might message a coder sub-agent with: “Found that the old HMAC approach is deprecated. Use PKCE instead.”

Rate limit: 50 messages per minute per agent.

Viewing sub-agent activity

Open the agent detail page to view sub-agent activity. You’ll see a tree view of the parent and all spawned sub-agents, with:

• Status (running / completed / failed)
• Token usage per agent
• Duration
• Output preview

Sub-agent status lifecycle

A sub-agent moves through these states: pending then queued then running. From running, it either reaches completed, or transitions to awaiting_approval (if an approval gate is configured) and then back to running once approved. A sub-agent can terminate as failed, cancelled, or timed_out at any point during execution.

Tips

• Assign specific goals to each sub-agent — vague goals lead to overlapping work
• Use pipeline aggregation for sequential refinement tasks (research → code → review)
• Set conservative budgets when experimenting — increase once you understand the cost profile
• Use the tester role for sub-agents that need to run tests; they’re configured with safer tool access by default