Subagents

Subagents allow deep agents to delegate tasks to specialized child agents. This provides context isolation and enables focused problem-solving for complex subtasks.

Learn more: For patterns and best practices, see the Subagents documentation.

Why Use Subagents?

• Context quarantine: Prevent the main agent's context from growing too large
• Specialization: Give subagents specific tools, models, and prompts optimized for their task
• Modularity: Build reusable subagent definitions for common tasks

Defining a SubAgent

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-4o",  # Optional model override
}

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    subagents=[research_subagent]
)

Using CompiledSubAgent

For complex workflows, use a pre-built LangGraph graph as a subagent:

from langchain.agents import create_agent
from deepagents import create_deep_agent, CompiledSubAgent

# Create a custom agent graph
custom_graph = create_agent(
    model=your_model,
    tools=specialized_tools,
    prompt="You are a specialized agent for data analysis..."
)

# Wrap it as a compiled subagent
custom_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="Specialized agent for complex data analysis tasks",
    runnable=custom_graph
)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    subagents=[custom_subagent]
)

SubAgent Configuration

Field	Type	Description
name	str	Identifier the main agent uses to invoke this subagent
description	str	Description shown to the main agent (helps it decide when to use the subagent)
system_prompt	str	System prompt for the subagent
tools	Sequence[BaseTool | Callable]	Tools available to the subagent
model	str | BaseChatModel	Optional model override (inherits from parent if not set)
middleware	list[AgentMiddleware]	Optional additional middleware
interrupt_on	dict	Optional human-in-the-loop configuration

API Reference