2.2 KiB
Subagents
Use subagent_spawn to delegate work to one or more specialized agents running concurrently. Each subagent receives the prompt, executes a single job, and returns a result. All results are joined in submission order.
When to spawn
When a task has N independent subtasks that each require multi-step reasoning or multiple tool calls, spawn N subagents and run them in parallel rather than executing sequentially. Do not wait until one subtask is done to start the next if they share no state.
Spawn when:
- A task decomposes into N independent subtasks, each requiring reasoning or multiple tool calls
- You are processing N items (files, repos, hosts) with the same operation
- A subtask is better handled by a different agent (different model, backend, or system prompt)
- You want to isolate a long-running or risky operation from the current session
Use execute_code parallel steps instead when the subtasks are single shell commands. Subagents are for agent-level work; parallel code steps are for parallel shell execution.
How to use
execute_tool: subagent_spawn
args: ["-n", "N", "-agent", "A", "-cwd", "/path", "prompt text here"]
| Flag | Default | Description |
|---|---|---|
-n N |
1 | Number of parallel subagents |
-agent A |
server default | Agent config name |
-backend B |
server default | Backend override |
-model M |
server default | Model override |
-cwd DIR |
pwd |
Working directory for each subagent |
-keep |
off | Do not remove jobs after collecting results |
Prompt is all remaining arguments after flags.
Output
- N = 1: raw result
- N > 1: results separated by
=== {job-id} ===headers, in submission order
Design rules
Same agent across parallel subagents. Different agents produce different output schemas; concatenating them is incoherent.
Prompt for structured output when you need to parse results. Tell subagents the exact format to respond in (numbered list, JSON, markdown sections) so you can extract what you need from the joined block.
All subagents receive the same prompt. Differentiate their work inside the prompt — include a shard index, file path, or role description if the tasks differ.