How the Deep Agents ‘task’ Tool Delegates Complex Work to Sub‑Agents

Conclusion

Sub‑Agents are not added to appear smarter; they define clear responsibility boundaries such as research, modification, review, and summarization.

When to consider splitting into Sub‑Agents

Three factors guide the decision:

Clear role differences between subtasks.

Subtasks require different permissions or models.

Splitting reduces context pressure on the parent Agent.

Simple single‑round Q&A tasks gain only overhead if split.

1. Position of the task tool in the toolchain

In Deep Agents, task is the sole tool that dispatches Sub‑Agents. Other built‑in tools are: write_todos → task planning ls / read / write → file system glob / grep → file search execute → command execution task → Sub‑Agent dispatch

When the parent Agent calls task, it passes a task description to a designated Sub‑Agent. The Sub‑Agent runs in its own context, returns a ToolMessage, and the parent integrates the result, updates its todo list, and decides the next step.

2. Real structure of a Sub‑Agent

In deepagents==0.5.3, SubAgent is a TypedDict with three required fields: name – unique identifier (required) description – guides the parent when to dispatch this Sub‑Agent (required) system_prompt – behavior rules for the Sub‑Agent (required)

Example definition:

from deepagents.middleware.subagents import SubAgent

researcher: SubAgent = {
    "name": "code-researcher",
    "description": (
        "代码研究员：分析代码结构、依赖和调用关系，"
        "适合了解代码、梳理调用链一类任务。"
    ),
    "system_prompt": "你是一个代码研究员，只分析代码结构，不直接修改文件。",
    "model": "anthropic:claude-sonnet-4-6",
    "tools": [...],
    "permissions": [...],
    "skills": [...],
}

The description must be specific; vague descriptions (e.g., “handles various technical tasks”) degrade dispatch quality because the parent cannot decide when to use the Sub‑Agent.

3. Pre‑defining Sub‑Agents for stability

Declare Sub‑Agents when creating the main Agent:

from deepagents import create_deep_agent
from deepagents.middleware.subagents import SubAgent

researcher: SubAgent = {
    "name": "researcher",
    "description": "分析代码结构和依赖，适合了解代码类任务。",
    "system_prompt": "你是代码研究员，专注分析结构、依赖和调用链。",
}

writer: SubAgent = {
    "name": "writer",
    "description": "把分析结果写成清晰文档，适合 README 和技术说明。",
    "system_prompt": "你是技术写手，输出简洁、准确、可执行的文档。",
}

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    subagents=[researcher, writer],
)

When a user asks “analyze this repository and write a README”, the parent Agent dispatches the researcher for analysis and the writer for documentation, then aggregates the results. This explicit role declaration is more reliable than ad‑hoc dispatch.

4. Dynamic task for one‑off jobs

If no predefined Sub‑Agent exists, a generic Sub‑Agent can handle a temporary task:

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "分析 /workspace 下的代码，然后写一份技术报告"
    }]
})

This approach works for single‑use cases but is less stable because the generic Sub‑Agent’s responsibility boundary is vague; an unclear description leads to off‑target behavior.

5. Core fields of the task tool

description

– what the Sub‑Agent should do this time. subagent_type – selects which Sub‑Agent type to use. SubAgentMiddleware filters state fields that should not be exposed to the Sub‑Agent and injects the task description as the Sub‑Agent’s new input.

6. Context isolation is not file isolation

Parent and Sub‑Agents usually share the same Backend and LangGraph state, but each Sub‑Agent has its own conversation history and todo list. Shared vs. isolated resources:

Backend file system – usually shared.

Parent Agent messages – not directly shared.

Sub‑Agent todos – independent.

Middleware stack – can be added or overridden per Sub‑Agent.

Final result – returned to the parent as a ToolMessage.

Consequently, files written by a Sub‑Agent are readable by the parent, while the Sub‑Agent’s detailed reasoning does not flood the parent’s message history, reducing context pressure.

7. When to use AsyncSubAgent

Ordinary Sub‑Agents cover most scenarios. AsyncSubAgent is for remotely deployed Sub‑Agents and requires additional fields such as graph_id, url, and headers to describe the remote graph, enabling start, query, update, and cancel operations.

Decision guide:

Local long‑running task with role split → use ordinary Sub‑Agent.

Code research, test fixing, documentation summarization → use ordinary Sub‑Agent.

Remote LangGraph/LangSmith background job → use AsyncSubAgent.

Need to query and cancel background tasks → use AsyncSubAgent.

Do not make a normal task asynchronous before verifying role boundaries.

8. Signals for when to split

More than two clearly distinct roles in the task.

Subtasks require different models.

Subtasks need tighter permissions.

Parent Agent’s context starts to bloat.

A role is likely to be reused in the future.

Signals that suggest NOT to split:

Single‑round simple task.

Subtasks heavily depend on every intermediate state of the parent.

Splitting adds only an extra call without quality gain.

Splitting merely to have “more agents”.

Typical role‑permission matrix

researcher – read‑only code.

fixer – write business files.

reviewer – read diffs and tests.

summarizer – read results and output summary.

This arrangement lets the main Agent delegate without doing everything itself, while each Sub‑Agent’s permissions are narrowed to its responsibility.

Personal evaluation criteria

After splitting, assess three outcomes:

Is the context shorter?

Are permissions tighter?

Is the output more stable?

If none improve, the split was unnecessary.