Subagents: Delegate Complex Tasks with the task Tool

Have you ever run into this situation: a task is too large, and handing it to a single agent causes its context to fill up quickly — because it has to simultaneously remember "what big task am I doing" and "all the details of this small subtask right now."

It's like having one person act as both PM and engineer, needing to think about architecture design while also remembering every line of code in detail — mistakes eventually happen not because they're not smart enough, but because the context of two different things is interfering with each other.

Deep Agents' solution: let the main agent focus on the big picture, and delegate concrete subtasks to subagents.

What the `task` Tool Is

task is one of Deep Agents' built-in tools. It lets the agent:

Create a new subagent
Give it a specific subtask
The subagent has its own independent context, and returns results to the main agent when done

The main agent's context only holds: "task description + final results." It doesn't need to carry all the intermediate details of the subtask. The subagent's context only has its own piece of work, letting it focus and do it thoroughly.

A Concrete Example

Suppose you're doing a "competitive analysis" task involving three subtasks: analyze Company A, analyze Company B, and finally integrate a report.

Without subagents: the main agent handles all three things sequentially, with all intermediate data piling up in one context.

With subagents:

from deepagents import create_deep_agent
 
def analyze_company(company: str) -> str:
    """Analyze a specified company's basic info, products, and market strategy."""
    return f"Analysis of {company}: 25% market share, low-price strategy..."
 
def write_report(content: str, filename: str) -> str:
    """Write a report to a file."""
    return f"Report saved to {filename}"
 
agent = create_deep_agent(
    tools=[analyze_company, write_report],
    system_prompt="""You are a strategy analyst.
    
    When handling multi-company analysis tasks, use the task tool to delegate each company's
    analysis to a subagent. After subagents return their results, integrate them into a final report.
    """,
)
 
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "Analyze the competitive dynamics between Company A and Company B, and compile a comparison report."}
    ]
})

The main agent will use the task tool to create two subagents — one to deeply analyze A and one for B — then take both analysis results and integrate them into a final report.

The main agent's context only holds: task description + subtask requests + subtask results. No need to carry all the intermediate details from analyzing each company.

Can Subagents Have Their Own Tools and Configuration?

Yes — a subagent is a complete agent with its own toolset and system prompt:

from deepagents import create_deep_agent, create_subagent
 
def deep_research(query: str) -> str:
    """Deep research on a specified topic."""
    return f"Deep research results on {query}..."
 
# Subagent: specialized for research
research_subagent = create_subagent(
    tools=[deep_research],
    system_prompt="You are a research expert, skilled at deep analysis and data integration.",
)
 
# Main agent: manages the overall task
main_agent = create_deep_agent(
    tools=[write_report],
    subagents={"researcher": research_subagent},
    system_prompt="You are a project lead, coordinating research tasks and delegating complex research to the researcher subagent.",
)

This design lets different agents specialize — the main agent handles planning and integration, while subagents each excel at specific domains or toolsets.

The Design Value of Context Isolation

The most important property of subagents is context isolation — not "making tasks run faster."

Here are the practical benefits isolation provides:

Avoiding Contamination: Large amounts of data from subtask A won't interfere with the judgment of subtask B. This is especially important for comparative analysis — if A and B's data are all in the same context, the agent will easily mix up details from both.

Greater Depth: The subagent's context only has its own subtask. It can go deeper — read more related documents, do more detailed analysis — without worrying about context being consumed by other things.

Reusability: The same subagent can be called multiple times, each time starting with a clean context.

Which Scenarios Are Worth Using Subagents For

Particularly valuable scenarios:

Need to process multiple independent subtasks in parallel or sequence (analyzing multiple companies, processing multiple documents)
A subtask is itself complex enough to warrant isolation for thorough handling
The main agent needs to integrate results from multiple sources without needing to know all the details of each source

Scenarios where it might not be necessary:

The task is linear and singular with no subtasks worth delegating
Subtasks are too simple — the overhead of creating a subagent isn't worth it
Tasks require all steps to share a tightly coupled state (tasks with strong dependencies aren't suitable for delegation)

Multi-Level Subagents

Subagents can spawn their own subagents — Deep Agents supports multi-level agent hierarchies. But this capability should be used carefully: the more levels, the higher the coordination cost and debugging difficulty. Generally recommended to stay within two levels: main agent → subagent. Three levels or more usually means the task design needs rethinking.

Previous: Pluggable Backends: In-Memory, Disk, LangGraph Store, or Sandbox — How to Choose Next: Long-Term Memory: Let the Agent Remember Important Information Across Conversations

What the task Tool Is