Skip to main content

Sub-Agent Complete Guide: From Basics to Pitfalls in 5 Minutes

· 4 min read

Core takeaways from the official Multi Sub-Agent Recommendations and Use Cases, for quick reference and decision-making.
Created: 2026-03-09
Last revised: 2026-03-09

30-Second Overview​

  • What is Sub-Agent: Offload long tasks to child sessions; the main session responds immediately; child tasks report back via announce when done
  • When to use: Long tasks, parallel processing, cost layering, session isolation → use Sub-Agent; few types, small batches, prioritize lower ops → consider single Agent + Skills
  • Relation to Skills: Complementary, not either/or; Sub-Agent handles session and execution, Skills handle capability and orchestration
  • Key config: model (cheaper model saves cost), runTimeoutSeconds (300–900), maxSpawnDepth (recommend 2)
  • Must-know limits: announce is best-effort; child Agent only gets AGENTS.md + TOOLS.md; timeout ≠ archive

Quick Decision Tree​

Check this table before choosing Sub-Agent vs Skills:

Your needBetter approach
Multi-source, multi-type, batch processing; main session needs fast response and parallel extractionMain Agent + multiple Sub-Agents
Few types, single/small batch, latency-insensitive, prioritize lower opsSingle Agent + multiple Skills
Validate flow before adopting Sub-AgentSingle Agent + Skills first → then split by type into Sub-Agents

1. Official Positioning (One Sentence)​

Sub-Agent is the standard way to "offload long tasks and keep the main session responsive": Heavy work is delegated to child sessions; the main session gets immediate feedback; when child tasks finish, summaries are sent back via announce; you can configure cheaper models for child agents to control cost.

Recommended for Sub-AgentNot recommended as replacement
Long / heavy tasksUsing "single Agent + multiple Skills" instead of Sub-Agent
Dispatching by task type (bidding, enterprise, policy, etc.)Skills do not provide independent sessions, async callback, or parallel child tasks
Need parallel execution, higher throughput
Cost layering (strong model for orchestration, cheaper model for execution)
Session and context isolation

3. Sub-Agent vs Skills​

LayerResponsibility
Sub-AgentSession and execution isolation: independent session, async announce, parallel child tasks, configurable cheaper model
SkillsCapability description and orchestration: teach Agent when and how to use tools and flows

Complementary, not either/or: Main Agent and Sub-Agents can all mount Skills; the main Agent dispatches and aggregates; Sub-Agents execute specific logic per Skill in their own sessions.

4. Core Config Parameters Quick Reference​

4.1 Global defaults agents.defaults.subagents​

ParameterPurposeSuggestion
modelDefault model for child tasksSet to a cheaper model to save cost
runTimeoutSecondsChild task timeout (seconds)300–900 recommended, avoid infinite hangs
maxChildrenPerAgentMax active child sessions per sessionDefault 5, range 1–20
maxConcurrentGlobal subagent concurrency limitDefault 8
archiveAfterMinutesAuto-archive time for child sessionsDefault 60 minutes
maxSpawnDepthNesting depthRecommend 2 (main → orchestrator → leaf)

Minimal example:

agents:
  defaults:
    subagents:
      model: "gpt-4o-mini"        # cheaper model for child tasks
      runTimeoutSeconds: 600       # 10 min timeout
      maxSpawnDepth: 2

4.2 Cross-Agent dispatch permission​

  • Configure allowAgents: ["main-agent-id"] on the child Agent being dispatched
  • Main Agent does not need to "register" a dispatch list; permission is declared only on the child Agent side

4.3 sessions_spawn tool essentials​

  • Non-blocking: Call returns immediately with { status: "accepted", runId, childSessionKey }
  • Callback: Child task reports back via announce when done (best-effort; may be lost on Gateway restart)
  • Required: task; optional: agentId, model, runTimeoutSeconds, cleanup, etc.

5. Important Limits and Boundaries​

  • announce is best-effort: For critical results, have the main Agent use sessions_history or transcript for a second fetch
  • Child Agent context: Only AGENTS.md + TOOLS.md are injected (no SOUL, IDENTITY, USER, etc.)
  • runTimeoutSeconds: Only stops execution, does not auto-archive; archiving is controlled by archiveAfterMinutes or cleanup: "delete"

6. Common Pitfalls​

PitfallDescriptionMitigation
announce lostBest-effort callback may be lost on Gateway restartUse sessions_history or transcript for critical results
Incomplete child Agent contextOnly AGENTS.md + TOOLS.md injected, no SOUL, IDENTITY, USERPut required info explicitly in task
Timeout ≠ archiverunTimeoutSeconds only stops run, does not delete sessionUse archiveAfterMinutes or cleanup: "delete" for archiving
Wrong permission configMain Agent dispatch failsConfigure allowAgents: ["main-agent-id"] on the child Agent being dispatched

7. Selection Quick Reference (with Typical Scenarios)​

NeedTypical scenarioBetter approach
Multi-source, multi-type, batch; main session needs fast response, parallel extractionMulti-source bidding extraction, enterprise info batch collectionMain Agent + multiple Sub-Agents
Few types, single/small batch, latency-insensitive, prioritize lower opsSingle-doc Q&A, simple classificationSingle Agent + multiple Skills
Validate flow before Sub-AgentBuilding from scratchSingle Agent + Skills first → then split by type into Sub-Agents

8. References and Next Steps​

  • Full version: Multi Sub-Agent Official Recommendations and Use Cases — after this quick guide, read the full version for design details and more scenarios
  • Official docs: Sub-Agents, Configuration Reference