max_loops="auto") and uses two internal tools: create_sub_agent and assign_task.
How It Works
- Planning — The coordinator agent analyzes the task and determines what specialized sub-agents are needed
- Creation — The coordinator calls
create_sub_agentto spawn agents with specific names, descriptions, and system prompts - Delegation — The coordinator calls
assign_taskto distribute work to sub-agents, which execute concurrently - 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
- Python (requests)
- Python (SDK)
- TypeScript
- Shell (curl)
Restricting Sub-Agent Tools
You can useselected_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_agentcan 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. Usefalseonly 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