Skip to main content
Sub-agent delegation allows a single coordinator agent to dynamically spawn specialized child agents and distribute tasks across them for parallel execution. The coordinator analyzes the main task, creates purpose-built sub-agents, assigns work, and aggregates results — all autonomously. This capability is built on top of the autonomous agent mode (max_loops="auto") and uses two internal tools: create_sub_agent and assign_task.

How It Works

  1. Planning — The coordinator agent analyzes the task and determines what specialized sub-agents are needed
  2. Creation — The coordinator calls create_sub_agent to spawn agents with specific names, descriptions, and system prompts
  3. Delegation — The coordinator calls assign_task to distribute work to sub-agents, which execute concurrently
  4. Aggregation — Results from all sub-agents are collected and the coordinator synthesizes a final response

Enabling Sub-Agents

Sub-agent delegation requires two configuration settings on your agent:
When max_loops="auto" is set without specifying selected_tools, all safe default tools are enabled including sub-agent tools.

Available Tools

create_sub_agent

Creates and caches one or more specialized sub-agents on the coordinator. Each sub-agent receives a unique ID in the format sub-agent-{uuid} (e.g., sub-agent-a1b2c3d4) and is stored in the coordinator’s internal cache for reuse. A sub-agent inherits the coordinator’s model_name and tool list, and its own max_loops is capped internally (5 if it has tools, otherwise 1) so it cannot itself recurse into further sub-agent creation.

assign_task

Distributes tasks to previously created sub-agents for concurrent execution. Sub-agent tasks run concurrently using asynchronous execution, so multiple sub-agents work in parallel.

API Usage

Sub-agents are used through the standard /v1/agent/completions endpoint. The coordinator agent autonomously invokes the sub-agent tools during its execution loop.

Basic Example

Restricting Sub-Agent Tools

You can use selected_tools to control exactly which tools the coordinator can access:
The full list of available tools for autonomous agents: create_plan, think, subtask_done, complete_task, respond_to_user, create_sub_agent, assign_task. The shell and file tools (run_bash, create_file, update_file, read_file, list_directory, delete_file) are not permitted, and a request that lists them, or any unknown tool name, returns 422.

Pre-Defined Sub-Agents with handoffs

If you already know which specialists an agent needs, you can define them up front with the handoffs field on agent_config instead of having the coordinator create them at runtime. handoffs takes a list of full agent specifications (the same shape as agent_config); these agents are created with the request and the parent agent can hand tasks off to them during execution. Unlike create_sub_agent, this does not require max_loops="auto". The list holds at most 2000 agents, and each one goes through the same model and premium checks as the parent. Each handoff agent’s tokens are billed at its own model’s price and included in the response’s usage.

Sub-Agents vs Other Multi-Agent Patterns

Best Practices

  • Clear coordinator prompts — Tell the coordinator explicitly that it should create sub-agents and delegate work. Include guidance on what types of specialists to create.
  • Keep the sub-agent count proportional to the task — there’s no hard limit on how many sub-agents create_sub_agent can spawn, but each one adds its own token usage and wall-clock time, so more sub-agents means more cost and coordination overhead for the coordinator to manage.
  • Specific sub-agent descriptions — The more specific the agent_description, the better the sub-agent performs its specialized task.
  • Use wait_for_completion: true (default) when the coordinator needs to synthesize results. Use false only for fire-and-forget scenarios.
  • Set appropriate timeouts — Sub-agent workflows take longer than single-agent calls since multiple agents run sequentially or in parallel. Use a timeout of 300+ seconds for complex tasks.

Cost Considerations

Sub-agent delegation uses more tokens than a single agent call because:
  • The coordinator agent uses tokens for planning and synthesis
  • Each sub-agent uses tokens for its specialized task
  • Tool calls (create/assign) consume additional tokens
For cost-sensitive workloads, consider using a multi-agent swarm with pre-defined agents instead, which avoids the overhead of dynamic agent creation.