Fast Guide to LangChain DeepAgents: How SubAgents Work

Core Value of SubAgents

When a task grows in steps, a single agent’s context can become bloated, hurting performance and causing the model to lose focus. DeepAgents solves this by letting the main agent delegate subtasks to SubAgents, which isolates their context and lets each SubAgent specialize in a specific responsibility, improving efficiency and success rate.

Execution Principle

During construction DeepAgents automatically injects a task tool that selects the appropriate SubAgent for a given subtask. The SubAgent runs in an isolated context; only its final result is returned to the main agent, keeping the main agent’s context clean for high‑level planning.

Creating SubAgents

Method 1 – Dictionary‑Based Creation

Define model and tool objects (e.g., a DeepSeek model and a simulated internet_search tool), then build a Python dictionary with required fields such as name, description, system_prompt, and tools. Optional fields include model, middleware, and interrupt_on. Finally pass the list of dictionaries to create_deep_agent.

from dotenv import load_dotenv
from deepagents import create_deep_agent
from langchain_core.tools import tool
from langchain_deepseek import ChatDeepSeek

load_dotenv()

@tool
def internet_search():
    print('模拟网络搜索功能')

model = ChatDeepSeek(model="deepseek-chat")

internet_subagent = {
    'name': 'internet_agent',
    'description': '实用网络工具从网络中搜索信息',
    'system_prompt': '你是一个网络搜索智能体，擅长从网络中搜索主智能体需要的关键信息',
    'tools': [internet_search],
    'model': model
}

agent = create_deep_agent(model=model, subagents=[internet_subagent])

Method 2 – Compiled SubAgent

First create a standard LangChain agent with create_agent, then wrap it with CompiledSubAgent, providing a name and description. The compiled object can be passed to create_deep_agent just like a dictionary‑based SubAgent.

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

custom_agent = create_agent(model=model, tools=[internet_search], system_prompt='你是一个网络搜索智能体')
summary_agent = create_agent(model=model, system_prompt='你用来根据现有资料总结并提供用户想要的短篇报告')
summary_subagent = CompiledSubAgent(name='summary-agent', description='用来根据提供的新闻或搜索信息编写短篇报告，500字以内', runnable=summary_agent)

agent = create_deep_agent(model=model, subagents=[custom_agent, summary_subagent])

Practical Demo – International Intelligence Analyst

The author builds a demo called “International Intelligence Analyst”. After installing the tavily search tool and defining an internet_search function, two SubAgents are created: a research SubAgent that performs deep web searches, and a summary SubAgent that writes a short report. The main agent streams a query about the Iran‑US conflict on 2026‑04‑03, delegates the search to the research SubAgent, then passes the results to the summary SubAgent, which produces a concise analysis.

step_num=0
query = "请分析2026年4月3日伊朗和美国战事的情况，并撰写短篇报告分析为什么美国注定失败，500字以内的报告"
for event in agent.stream({"messages": [{"role": "user", "content": query}]}, stream_mode="values"):
    ...

Applicable Scenarios

Multi‑step tasks – prevents a single agent’s context from becoming messy.

Domain‑specific subtasks – allows specialized tools and prompts.

Mixed‑model pipelines – combines different models for overall performance.

High‑level coordination – lets the main agent focus on planning while SubAgents handle details.

When Not to Use SubAgents

Simple single‑step tasks – added complexity outweighs benefits.

Tasks that heavily rely on intermediate details – context isolation may drop needed information.

Cost‑sensitive workloads – duplicated context in SubAgents can increase token usage.

Important Notes

Every DeepAgents object includes a default SubAgent named general_purpose that shares the main agent’s model, tools, and system prompt. If a custom SubAgent’s description is unclear, the main agent may fall back to the default SubAgent, leading to unexpected behavior.

Conclusion

DeepAgents SubAgents provide context isolation and responsibility separation, effectively tackling context bloat in complex workflows. Two creation approaches—dictionary configuration and compiled SubAgents—are demonstrated with a search‑and‑report use case. While SubAgents boost efficiency in multi‑step, domain‑specific, or multi‑model scenarios, they should be avoided for simple or cost‑sensitive tasks, and each SubAgent’s description must be explicit.