Sub-Agents
Sub-agents are isolated agent instances dispatched from the main agent to handle specialized or parallel work. They run with their own context window, their own toolset, and report back a single result.
Why Sub-Agents
- Parallelize independent work — fan out three searches, get all three results back at once
- Protect the main context — exploration that would burn 50k tokens stays out of the parent
- Use specialists — a “code-reviewer” sub-agent with a different system prompt than your main agent
- Isolate failures — a sub-agent that crashes doesn’t kill the session
Built-In Sub-Agents
| Name | Purpose |
|---|---|
Explore | Fast codebase search and exploration |
Plan | Drafts implementation plans for multi-step work |
code-reviewer | Reviews a completed change against standards |
general-purpose | Open-ended research and execution |
Dispatching from the CLI
The agent dispatches sub-agents using the built-in Agent tool. Example interaction:
> map every place that calls the legacy auth middleware
[Agent dispatches Explore sub-agent]
[Result summarized back: 14 files, listed]Dispatching from the SDK
const result = await agent.dispatch({
subagent_type: 'Explore',
description: 'Find legacy auth callers',
prompt: 'Search the repo for any file importing the deprecated authMiddleware and list them with line numbers.',
})Parallel Dispatch
To run multiple sub-agents in parallel, dispatch them in a single batch:
const [tests, plan, review] = await Promise.all([
agent.dispatch({ subagent_type: 'general-purpose', prompt: 'Run all tests and summarize failures' }),
agent.dispatch({ subagent_type: 'Plan', prompt: 'Plan the migration from v1 to v2' }),
agent.dispatch({ subagent_type: 'code-reviewer', prompt: 'Review the changes on branch feature/x' }),
])The CLI applies the same pattern when you ask the main agent to do independent tasks.
Custom Sub-Agents
Define your own in ~/.syntic/agents/<name>.md:
---
name: migration-reviewer
description: Reviews database migrations for online safety, lock risk, and rollback strategy
tools: Read, Grep, Glob, Bash
---
You are a senior DBA. Review the migration file...Then dispatch it like any other:
await agent.dispatch({
subagent_type: 'migration-reviewer',
prompt: 'Review migrations/0042_add_index.sql',
})Tool Scoping
Sub-agents can restrict the parent’s tool list via the tools: frontmatter. A sub-agent that should only search should not have Edit or Bash.
Best Practices
- Brief like a colleague — the sub-agent has zero context from the parent conversation
- Ask for a short report when you only need findings, not raw output
- Don’t double-search — if the sub-agent is exploring, the parent shouldn’t also explore
- Verify before claiming — a sub-agent reports what it tried, not always what it did