Sub-Agents

Read this when a single agent can't handle a task end-to-end — when you need parallel work, specialization, or long-running task chains.

What sub-agents are

A sub-agent is a separate agent instance your main agent can spin up and delegate work to. Each sub-agent can have its own:

• Model (use Haiku for cheap subtasks, Sonnet for reasoning)
• Tools and skills
• System prompt / specialization
• Input and output

The main agent orchestrates. Sub-agents execute. Results come back to the main agent, which synthesizes and responds to you.

When to use sub-agents

Use sub-agents when:

• A task requires fetching from 5 different sources (do them in parallel)
• You want one agent that researches and one that writes
• A task has distinct phases that benefit from fresh context
• You want to isolate tool permissions (sub-agent only gets write, main agent doesn't)

Don't use sub-agents for:

• Simple tasks that one agent handles fine
• Conversation — sub-agents add latency and cost
• Tasks where context needs to flow naturally end-to-end

Basic sub-agent config

{
  "sub_agents": {
    "researcher": {
      "model": "claude-sonnet-4-6",
      "tools": ["web_search", "web_fetch"],
      "systemPrompt": "You are a research specialist. Search thoroughly, fetch sources, and return structured summaries with citations."
    },
    "writer": {
      "model": "claude-sonnet-4-6",
      "systemPrompt": "You are a writing specialist. Take research and turn it into polished prose. No raw lists."
    },
    "data-checker": {
      "model": "claude-haiku-4-5-20251001",
      "tools": ["web_fetch"],
      "systemPrompt": "You check facts and prices. Return only verified data with sources."
    }
  }
}

Triggering sub-agents from the main agent

Once configured, your main agent can delegate automatically. Add to SOUL.md:

## Sub-agents
For research tasks: delegate to the "researcher" sub-agent first, then synthesize its output.
For writing tasks after research: pass the research to the "writer" sub-agent.
For any task requiring real-time prices or facts: use "data-checker" first.

Or trigger explicitly:

"Research the top 5 vector databases using the researcher agent, then have the writer agent produce a comparison article."

Parallel sub-agents

For tasks with independent subtasks, sub-agents can run in parallel:

"I need a report on three competitors: Acme, Globex, and Initech. Research each one in parallel and combine the results."

Your main agent launches three researcher sub-agents simultaneously. Each fetches and summarizes its target. Results come back together.

With a single agent doing this sequentially, it might take 90 seconds. With parallel sub-agents, it takes 30 seconds.

Long-running tasks

Sub-agent execution is managed through the agent's conversation context. When your main agent delegates a long-running task to a sub-agent, it tracks progress internally and synthesizes results once the sub-agent completes.

For tasks that take minutes (large research, document processing), instruct your main agent to delegate and report back when finished. You can also configure the result to be sent to a channel on completion:

{
  "id": "long-research",
  "prompt": "...",
  "channel": "telegram",
  "notifyOnComplete": true
}

Cost awareness

Sub-agents multiply your costs. If a task uses 5 sub-agents each using 10,000 tokens, you're spending 50,000 tokens on one user request.

Tips:

• Use Haiku for sub-agents doing structured extraction or simple summarization
• Limit parallel sub-agents to 3-5 for most tasks
• Set "maxTokens" per sub-agent to cap runaway tasks

{
  "sub_agents": {
    "researcher": {
      "model": "claude-haiku-4-5-20251001",
      "maxTokens": 4000
    }
  }
}