Sub-Agent Tools

Delegate complex tasks to specialized sub-agents for isolated context execution

Overview

The task() tool allows you to delegate work to specialized sub-agents that run in their own isolated context. This helps preserve the main conversation context and enables autonomous execution of complex, multi-step tasks.

task

Delegate a task to a specialized sub-agent that runs in its own context.

Parameters

description · str · required

A short (3-5 word) description of the task for logging and display. ALWAYS PROVIDE THIS PARAMETER FIRST.

prompt · str · required

The task description for the sub-agent. Be specific and clear about what needs to be done. ALWAYS PROVIDE THIS PARAMETER SECOND.

subagent_type · Literal['general-purpose', 'bash'] · required

The type of sub-agent to use. ALWAYS PROVIDE THIS PARAMETER THIRD.

max_turns · int

Optional maximum number of agent turns. Defaults to the sub-agent’s configured maximum.

---

Sub-Agent Types

general-purpose

A capable agent for complex, multi-step tasks that require both exploration and action.

Configuration:

• Max turns: 50 (default)
• Timeout: 900 seconds (15 minutes)
• Available tools: All parent tools (except task, ask_clarification, present_files)

Use this sub-agent when:

• The task requires both exploration and modification
• Complex reasoning is needed to interpret results
• Multiple dependent steps must be executed
• The task would benefit from isolated context management

Do NOT use for:

• Simple, single-step operations (use tools directly)
• Tasks requiring user interaction or clarification

Example:

task(
    description="Analyze codebase structure",
    prompt="Analyze the project structure in /mnt/user-data/workspace and create a detailed report of all Python modules, their dependencies, and key functions. Save the report to /mnt/user-data/outputs/analysis.md",
    subagent_type="general-purpose"
)

bash

Command execution specialist for running bash commands in a separate context.

Configuration:

• Max turns: 30 (default)
• Timeout: 900 seconds (15 minutes)
• Available tools: bash, ls, read_file, write_file, str_replace only

Use this sub-agent when:

• You need to run a series of related bash commands
• Terminal operations like git, npm, docker, etc.
• Command output is verbose and would clutter main context
• Build, test, or deployment operations

Do NOT use for:

• Simple single commands (use bash tool directly instead)

Example:

task(
    description="Build and test project",
    prompt="Navigate to /mnt/user-data/workspace, run npm install, then npm run build, and finally npm test. Report any errors or test failures.",
    subagent_type="bash"
)

---

When to Use Sub-Agents

Sub-agents help you:

• Preserve context: Keep exploration and implementation separate from the main conversation
• Handle complexity: Execute complex multi-step tasks autonomously
• Isolate execution: Run commands or operations without cluttering the main context
• Parallelize work: Delegate independent tasks to run concurrently

Good Use Cases

# Complex analysis task
task(
    description="Performance analysis",
    prompt="Analyze the performance of all API endpoints in the codebase. Check for N+1 queries, missing indexes, and slow operations. Generate a report with recommendations.",
    subagent_type="general-purpose"
)

# Git operations
task(
    description="Git sync and merge",
    prompt="Fetch the latest changes from origin, merge main into the current branch, resolve any conflicts in favor of the current branch, and push the changes.",
    subagent_type="bash"
)

# Refactoring task
task(
    description="Extract utility functions",
    prompt="Find all duplicate code patterns in the /mnt/user-data/workspace/src directory and extract them into a new utils.py file with proper documentation.",
    subagent_type="general-purpose",
    max_turns=30
)

When NOT to Use

# DON'T: Simple single command
# BAD
task(
    description="List files",
    prompt="List files in /mnt/user-data/workspace",
    subagent_type="bash"
)
# GOOD
ls(description="List files", path="/mnt/user-data/workspace")

# DON'T: Tasks requiring user input
# BAD
task(
    description="Get API key",
    prompt="Ask the user for their API key and save it to config",
    subagent_type="general-purpose"
)
# GOOD - ask_clarification is disallowed in sub-agents anyway
ask_clarification(
    question="What is your API key?",
    clarification_type="missing_info"
)

---

Delegation Flow

1. Task Initialization

   • Sub-agent executor is created with specified configuration
   • Parent context (sandbox, thread data, model) is inherited
   • Task starts in background thread

2. Execution

   • Sub-agent runs autonomously in isolated context
   • Progress updates stream to parent via task events
   • Timeout and max turns enforced automatically

3. Completion

   • Results returned to parent agent
   • Success/failure/timeout status reported
   • Execution logs available for debugging

Task Events

The parent agent receives real-time events:

• task_started: Task begins execution
• task_running: Sub-agent sends progress messages
• task_completed: Task finishes successfully
• task_failed: Task encounters an error
• task_timed_out: Task exceeds timeout limit

---

Return Values

The task() tool returns a string with the execution result:

Success

Task Succeeded. Result: [sub-agent's final response]

Failure

Task failed. Error: [error description]

Timeout

Task timed out. Error: [timeout details]

---

Advanced Usage

Custom Max Turns

Limit the number of agent iterations:

task(
    description="Quick code review",
    prompt="Review the main.py file for obvious bugs and style issues",
    subagent_type="general-purpose",
    max_turns=10  # Override default 50
)

Parallel Delegation

Delegate multiple independent tasks:

# Task 1: Analyze frontend
task(
    description="Analyze frontend",
    prompt="Analyze React components in /mnt/user-data/workspace/frontend",
    subagent_type="general-purpose"
)

# Task 2: Analyze backend (runs in parallel)
task(
    description="Analyze backend",
    prompt="Analyze Python services in /mnt/user-data/workspace/backend",
    subagent_type="general-purpose"
)

---

Best Practices

Clear Instructions

Provide specific, actionable prompts:

# Good: Specific and actionable
task(
    description="Update dependencies",
    prompt="Update all Python dependencies in requirements.txt to their latest compatible versions. Check for breaking changes and update code if necessary. Run tests to verify everything works.",
    subagent_type="general-purpose"
)

# Bad: Vague and unclear
task(
    description="Fix dependencies",
    prompt="Make the dependencies better",
    subagent_type="general-purpose"
)

Choose the Right Sub-Agent

• Use general-purpose for tasks requiring reasoning and exploration
• Use bash for pure command execution sequences
• Use tools directly for simple operations

Handle Results

Sub-agents return structured results that should be parsed:

result = task(
    description="Run tests",
    prompt="Run pytest and report results",
    subagent_type="bash"
)

if "Task Succeeded" in result:
    # Extract and use the results
    print("Tests passed!")
else:
    # Handle failure
    print(f"Tests failed: {result}")

---

Technical Details

Context Inheritance

Sub-agents inherit from parent:

• Sandbox state and environment
• Thread data (workspace, uploads, outputs paths)
• Model configuration
• Available tools (with restrictions)

Disallowed Tools

Sub-agents cannot use:

• task: Prevents recursive nesting
• ask_clarification: Sub-agents must work autonomously
• present_files: Only parent can present files to user

Timeout Handling

• Default timeout: 900 seconds (15 minutes)
• Enforced at thread pool level
• Polling timeout includes 60-second buffer
• Status checked every 5 seconds

Tracing

All sub-agent executions are traced:

• Unique trace ID propagated to sub-agent
• Logs include trace ID for correlation
• Task ID matches tool call ID for traceability