Skip to main content

ADR 10: Nested Sub-agent Task Delegation

Context

When performing complex multi-step tasks, a single agent loop can exhaust its context window or get stuck in repetitive reasoning loops. Spawning subprocesses or running external scripts is unreliable. We need a way for the agent to delegate sub-tasks to specialized sub-agents.

Decision

We decided to support nested sub-agents by enabling AgentCore to spawn child AgentCore instances recursively.

Implementation Details

  1. Creation:
    • The tool context exposes ctx.createChildAgent(sessionId).
    • The child agent is initialized with the same system ports (filesystem, LLM service, process runner) but receives a customized session ID and custom system prompt.
  2. Context Passing:
    • The parent can specify a list of files (filesToInclude) which are explicitly added to the child's context store before starting.
  3. Depth Guard:
    • The parent context tracks a delegationDepth.
    • Spawning is rejected with an error if the delegation depth exceeds 3, preventing runaway loops of sub-agents calling more sub-agents.

Consequences

  • Pros:
    • Code reusability: uses the exact same AgentCore logic and ReAct loop.
    • Context isolation: child agents have clean context windows with only the relevant files loaded.
    • Safe boundary limits: recursion depth prevents infinite token loops.
  • Cons:
    • LLM calls run sequentially, increasing total latency when sub-agents are spawned.
    • Token consumption can increase rapidly since each sub-agent initializes its own prompt.