How Sub Agents Work

Understand the complete lifecycle of a sub agent - from spawning to result delivery. Learn about context passing, tool access, memory isolation, and execution modes.

The Agent Spawning Lifecycle

Every sub agent goes through a predictable lifecycle from creation to completion:

1. 1. Task Identification

   The parent agent recognizes that a task would benefit from delegation. This could be a research task, a coding task, or any work that can be scoped independently.

2. 2. Agent Creation

   The parent spawns a new agent instance with a specific prompt describing the task, the expected output format, and any relevant context.

3. 3. Execution

   The sub agent works autonomously, using its available tools to complete the task. It may read files, search code, write implementations, or run commands.

4. 4. Result Return

   When finished, the sub agent returns its results to the parent. This typically includes a summary of findings, code changes made, or recommendations.

5. 5. Cleanup

   The sub agent's context is discarded. The parent receives only the final output, keeping its own context lean and focused.

Parent Agent
    |
    v
[Identify Task] -- "I need to understand the auth module"
    |
    v
[Spawn Sub Agent] -- Creates agent with task prompt
    |
    v
[Sub Agent Works] -- Reads files, searches, analyzes
    |
    v
[Results Return] -- "Auth uses JWT with refresh tokens..."
    |
    v
Parent continues with knowledge

Context Passing

When a parent agent spawns a sub agent, it must pass enough context for the sub agent to do its job effectively. This context typically includes:

• Task description: A clear, specific prompt describing what the sub agent should accomplish.
• Relevant background: Key information the sub agent needs to know (e.g., project structure, coding conventions, constraints).
• Expected output format: How the sub agent should structure its response so the parent can easily use it.

// Parent agent creates a sub agent with this prompt:

"Search the codebase for all authentication-related
files. Look for:
1. Where JWT tokens are created and validated
2. How refresh tokens are handled
3. Any middleware that checks auth status
4. Rate limiting on auth endpoints

Return a structured summary with file paths and
key findings for each area."

Tool Access Per Agent Type

Not all sub agents get the same tools. Tool access is restricted based on the agent's role to enforce safety and prevent unintended side effects:

Result Aggregation

After sub agents complete their work, the parent agent must aggregate their results into a coherent whole. This process involves:

• Collecting outputs: Gathering the text responses from each sub agent.
• Resolving conflicts: If multiple agents touched related areas, the parent checks for conflicts or inconsistencies.
• Synthesizing: Combining individual results into a unified response or action plan.
• Reporting: Presenting the aggregated results to the user in a clear, organized format.

Memory Isolation vs Shared Context

A critical design decision in sub agent systems is how much context is shared between agents:

Background vs Foreground Execution

Sub agents can run in two modes:

Foreground (Blocking)

The parent agent waits for the sub agent to finish before continuing. This is appropriate when the parent needs the sub agent's results to decide what to do next.

// Parent waits for result before continuing
result = spawn_agent("Research the auth module")
// Parent can now use the result
plan = make_plan(result)

Background (Non-Blocking)

The sub agent runs independently while the parent continues with other work. The parent checks for results later. This enables true parallel execution.

// Parent spawns multiple agents and continues
agent_a = spawn_background("Research auth module")
agent_b = spawn_background("Research database layer")
agent_c = spawn_background("Research API routes")

// Parent does its own work while agents run
// Results collected when agents finish