Subagents & Context Isolation

When one agent tries to do everything, its context becomes a junk drawer — research notes, code, half-finished plans — and quality drops. Subagents fix this: the main agent delegates a focused subtask to a specialist that runs in its own clean context and returns just the result.

Defining a subagent

A subagent is a dict with a name, a description (so the main agent knows when to use it), a system prompt, and optionally its own tools and model:

from deepagents import create_deep_agent

def internet_search(query: str) -> str:
    """Search the web."""
    return f"results for {query}"

research_subagent = {
    "name": "research-agent",
    "description": "Use for in-depth research questions.",
    "system_prompt": "You are a thorough researcher. Search, then summarize with sources.",
    "tools": [internet_search],
    "model": "openai:gpt-5.5",   # optional: override the main model
}

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a lead agent. Delegate research to the research-agent, then write the report.",
    subagents=[research_subagent],
)

Isolated vs. fork

Subagents default to isolated mode — a fresh context, so nothing leaks in or out except the task and its result. (A fork mode copies the current context instead.) Isolation is what keeps the main agent's window clean and each specialist focused.

Design your main agent and its subagents visually — and get this code — with the Deep Agent Scaffold Generator.