Deep agent는 작업을 위임하기 위해 subagent를 생성할 수 있습니다. subagents 파라미터에서 커스텀 subagent를 지정할 수 있습니다. Subagent는 context quarantine (메인 agent의 컨텍스트를 깔끔하게 유지)와 특화된 지시사항 제공에 유용합니다.

​
왜 subagent를 사용하나요?

Subagent는 컨텍스트 비대화 문제를 해결합니다. Agent가 대용량 출력을 가진 도구(웹 검색, 파일 읽기, 데이터베이스 쿼리)를 사용할 때, 컨텍스트 윈도우는 중간 결과로 빠르게 채워집니다. Subagent는 이러한 세부 작업을 격리합니다—메인 agent는 그것을 생성한 수십 개의 tool 호출이 아닌 최종 결과만 받습니다. Subagent를 사용해야 하는 경우:
  • ✅ 메인 agent의 컨텍스트를 어지럽힐 수 있는 다단계 작업
  • ✅ 커스텀 지시사항이나 도구가 필요한 특화된 도메인
  • ✅ 다른 model 기능이 필요한 작업
  • ✅ 메인 agent가 고수준 조정에 집중하도록 유지하고 싶을 때
Subagent를 사용하지 말아야 하는 경우:
  • ❌ 간단한 단일 단계 작업
  • ❌ 중간 컨텍스트를 유지해야 할 때
  • ❌ 오버헤드가 이점보다 클 때

​
Configuration

subagents는 dictionary 리스트 또는 CompiledSubAgent 객체여야 합니다. 두 가지 타입이 있습니다:

​
SubAgent (Dictionary 기반)

대부분의 사용 사례에서는 subagent를 dictionary로 정의합니다: 필수 필드:
  • name (str): Subagent의 고유 식별자. 메인 agent는 task() tool을 호출할 때 이 이름을 사용합니다.
  • description (str): 이 subagent가 수행하는 작업. 구체적이고 행동 지향적으로 작성하세요. 메인 agent는 이를 사용하여 위임 시점을 결정합니다.
  • system_prompt (str): Subagent를 위한 지시사항. Tool 사용 가이드와 출력 형식 요구사항을 포함하세요.
  • tools (List[Callable]): Subagent가 사용할 수 있는 도구. 최소한으로 유지하고 필요한 것만 포함하세요.
선택적 필드:
  • model (str | BaseChatModel): 메인 agent의 model을 재정의합니다. "provider:model-name" 형식을 사용하세요 (예: "openai:gpt-4o").
  • middleware (List[Middleware]): 커스텀 동작, 로깅 또는 rate limiting을 위한 추가 middleware.
  • interrupt_on (Dict[str, bool]): 특정 tool에 대한 human-in-the-loop을 구성합니다. Checkpointer가 필요합니다.

​
CompiledSubAgent

복잡한 워크플로우의 경우, 미리 빌드된 LangGraph graph를 사용하세요: 필드:
  • name (str): 고유 식별자
  • description (str): 이 subagent가 수행하는 작업
  • runnable (Runnable): 컴파일된 LangGraph graph (먼저 .compile()을 호출해야 함)

​
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 override, defaults to main agent model
}
subagents = [research_subagent]

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

​
CompiledSubAgent 사용하기

더 복잡한 사용 사례의 경우, 미리 빌드된 LangGraph graph를 subagent로 제공할 수 있습니다: 
from deepagents import create_deep_agent, CompiledSubAgent
from langchain.agents import create_agent

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

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

subagents = [custom_subagent]

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[internet_search],
    system_prompt=research_instructions,
    subagents=subagents
)

​
범용 subagent

사용자 정의 subagent 외에도, deep agent는 항상 general-purpose subagent에 접근할 수 있습니다. 이 subagent는:
  • 메인 agent와 동일한 system prompt를 가집니다
  • 동일한 모든 tool에 접근할 수 있습니다
  • 동일한 model을 사용합니다 (재정의되지 않는 한)

​
언제 사용하나요

범용 subagent는 특화된 동작 없이 컨텍스트 격리에 이상적입니다. 메인 agent는 복잡한 다단계 작업을 이 subagent에 위임하고 중간 tool 호출로 인한 비대화 없이 간결한 결과를 받을 수 있습니다.

예시

메인 agent가 10번의 웹 검색을 수행하고 결과로 컨텍스트를 채우는 대신, 범용 subagent에 위임합니다: task(name="general-purpose", task="Research quantum computing trends"). Subagent는 모든 검색을 내부적으로 수행하고 요약만 반환합니다.

​
Best practice

​
명확한 description 작성하기

메인 agent는 description을 사용하여 어떤 subagent를 호출할지 결정합니다. 구체적으로 작성하세요: ✅ 좋음: "Analyzes financial data and generates investment insights with confidence scores" ❌ 나쁨: "Does finance stuff"

​
System prompt를 상세하게 유지하기

Tool 사용 방법과 출력 형식에 대한 구체적인 가이드를 포함하세요: 
research_subagent = {
    "name": "research-agent",
    "description": "Conducts in-depth research using web search and synthesizes findings",
    "system_prompt": """You are a thorough researcher. Your job is to:

    1. Break down the research question into searchable queries
    2. Use internet_search to find relevant information
    3. Synthesize findings into a comprehensive but concise summary
    4. Cite sources when making claims

    Output format:
    - Summary (2-3 paragraphs)
    - Key findings (bullet points)
    - Sources (with URLs)

    Keep your response under 500 words to maintain clean context.""",
    "tools": [internet_search],
}

​
Tool set 최소화하기

Subagent에게 필요한 tool만 제공하세요. 이는 집중도와 보안을 향상시킵니다: 
# ✅ Good: Focused tool set
email_agent = {
    "name": "email-sender",
    "tools": [send_email, validate_email],  # Only email-related
}

# ❌ Bad: Too many tools
email_agent = {
    "name": "email-sender",
    "tools": [send_email, web_search, database_query, file_upload],  # Unfocused
}

​
작업별로 model 선택하기

다른 model은 다른 작업에서 뛰어납니다: 
subagents = [
    {
        "name": "contract-reviewer",
        "description": "Reviews legal documents and contracts",
        "system_prompt": "You are an expert legal reviewer...",
        "tools": [read_document, analyze_contract],
        "model": "anthropic:claude-sonnet-4-20250514",  # Large context for long documents
    },
    {
        "name": "financial-analyst",
        "description": "Analyzes financial data and market trends",
        "system_prompt": "You are an expert financial analyst...",
        "tools": [get_stock_price, analyze_fundamentals],
        "model": "openai:gpt-4o",  # Better for numerical analysis
    },
]

​
간결한 결과 반환하기

Subagent에게 원시 데이터가 아닌 요약을 반환하도록 지시하세요: 
data_analyst = {
    "system_prompt": """Analyze the data and return:
    1. Key insights (3-5 bullet points)
    2. Overall confidence score
    3. Recommended next actions

    Do NOT include:
    - Raw data
    - Intermediate calculations
    - Detailed tool outputs

    Keep response under 300 words."""
}

​
일반적인 패턴

​
여러 특화된 subagent

다른 도메인을 위한 특화된 subagent를 생성하세요: 
from deepagents import create_deep_agent

subagents = [
    {
        "name": "data-collector",
        "description": "Gathers raw data from various sources",
        "system_prompt": "Collect comprehensive data on the topic",
        "tools": [web_search, api_call, database_query],
    },
    {
        "name": "data-analyzer",
        "description": "Analyzes collected data for insights",
        "system_prompt": "Analyze data and extract key insights",
        "tools": [statistical_analysis],
    },
    {
        "name": "report-writer",
        "description": "Writes polished reports from analysis",
        "system_prompt": "Create professional reports from insights",
        "tools": [format_document],
    },
]

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    system_prompt="You coordinate data analysis and reporting. Use subagents for specialized tasks.",
    subagents=subagents
)
워크플로우:
  1. 메인 agent가 고수준 계획 생성
  2. data-collector에 데이터 수집 위임
  3. 결과를 data-analyzer에 전달
  4. 인사이트를 report-writer에 전송
  5. 최종 출력 컴파일
각 subagent는 자신의 작업에만 집중하는 깨끗한 컨텍스트로 작업합니다.

​
문제 해결

​
Subagent가 호출되지 않음

문제: 메인 agent가 위임하는 대신 작업을 직접 수행하려고 합니다. 해결책:
  1. Description을 더 구체적으로 만들기: 
    # ✅ Good
{"name": "research-specialist", "description": "Conducts in-depth research on specific topics using web search. Use when you need detailed information that requires multiple searches."}

# ❌ Bad
{"name": "helper", "description": "helps with stuff"}
  2. 메인 agent에게 위임하도록 지시하기: 
    agent = create_deep_agent(
    system_prompt="""...your instructions...

    IMPORTANT: For complex tasks, delegate to your subagents using the task() tool.
    This keeps your context clean and improves results.""",
    subagents=[...]
)

​
컨텍스트가 여전히 비대해짐

문제: Subagent를 사용함에도 불구하고 컨텍스트가 채워집니다. 해결책:
  1. Subagent에게 간결한 결과를 반환하도록 지시하기: 
    system_prompt="""...

IMPORTANT: Return only the essential summary.
Do NOT include raw data, intermediate search results, or detailed tool outputs.
Your response should be under 500 words."""
  2. 대용량 데이터에 filesystem 사용하기: 
    system_prompt="""When you gather large amounts of data:
1. Save raw data to /data/raw_results.txt
2. Process and analyze the data
3. Return only the analysis summary

This keeps context clean."""

​
잘못된 subagent가 선택됨

문제: 메인 agent가 작업에 부적절한 subagent를 호출합니다. 해결책: Description에서 subagent를 명확하게 구분하세요: 
subagents = [
    {
        "name": "quick-researcher",
        "description": "For simple, quick research questions that need 1-2 searches. Use when you need basic facts or definitions.",
    },
    {
        "name": "deep-researcher",
        "description": "For complex, in-depth research requiring multiple searches, synthesis, and analysis. Use for comprehensive reports.",
    }
]
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I