Sub-Agent

Overview

Sub-Agent is Zeus’s task delegation mechanism. The main Agent dispatches subtasks to independent sub-agents by calling the task tool. Each sub-agent has its own context and reasoning loop, and returns results to the main Agent as a standard Tool Result upon completion. Core capabilities:

Task Decomposition — Break complex tasks into independent subtasks
Context Isolation — Each sub-agent has its own isolated context
Parallel Execution — Multiple subtasks run concurrently for improved efficiency
Result Aggregation — Sub-agent results return to the main Agent for continued reasoning

Architecture

Main Agent vs Sub-Agent

Dimension	Main Agent	Sub-Agent
Context	Full System Prompt + conversation history	Minimal context + task description
Tools	All available tools	Inherits main Agent’s tool set
Model	User-configured model	Inherits main Agent’s model
Lifecycle	Session-level	Single task, destroyed on completion
Middleware	Full middleware stack	Lightweight middleware stack
Todos	Has its own task list	`write_todos` calls are skipped

The `task` Tool

The main Agent triggers sub-agents through the task tool. This tool is automatically injected by the DeepAgents framework’s SubAgentMiddleware.

Parameters

Parameter	Type	Description
`description`	string	Short task description (used for UI display)
`prompt`	string	Detailed task instructions; the sub-agent executes based on this context

Example

SubAgentMiddleware

Sub-Agent capability is provided by the DeepAgents framework’s SubAgentMiddleware. It is registered automatically during Agent creation and injects the task tool into the main Agent’s tool set.

Backend Configuration

Configured in BaseService._create_agent():

SubAgentMiddleware(
    default_model=model,           # Sub-agents inherit the main Agent's model
    default_tools=tools,           # Sub-agents inherit the main Agent's tool set
    subagents=subagents,           # Sub-agent configuration list
    default_middleware=[           # Sub-agents use a lightweight middleware stack
        TodoListMiddleware(),
        SummarizationMiddleware(),
        AnthropicPromptCachingMiddleware(),
        PatchToolCallsMiddleware(),
    ],
    default_interrupt_on=interrupt_on,
    general_purpose_agent=True,
)

Execution Flow

Frontend Integration

SSE Event Flow

Sub-agent execution is streamed to the frontend via standard SSE events. The frontend uses tool_name and tool_call_id to distinguish between main Agent and sub-agent messages.

Message Isolation

Messages produced by sub-agents (tool calls, text) are tagged with a subAgentTaskId field and excluded from the main chat flow:

Chat area: Sub-agent tool calls are only shown inside their corresponding TaskToolCallCard, not in the main message stream
Task grouping: groupMessagesIntoTasks filters out subAgentTaskId messages before processing, preventing interference with main task status
Todos: Sub-agent write_todos calls are completely skipped, leaving the main Agent’s task list unaffected

TaskToolCallCard

Each task tool call renders as an expandable card in the chat area:

Collapsed: Shows status icon, task description, progress (e.g. 5/11), and current activity
Expanded: Lists all internal tool calls with their status and parameter previews
Running state: Blue border highlight with spinning loader
Supports clicking “View in trajectory →” to jump to the corresponding trajectory tab

Parallel sub-agents each display their own independent TaskToolCallCard with individual progress tracking.

Trajectory Tabs

When sub-agents are active, the trajectory area displays a tab bar at the top:

Main — Main Agent’s tool execution history
Sub-Agent — Each sub-agent has its own tab showing its tool execution history

Each tab maintains an independent step slider, allowing users to browse different agents’ execution history without interference. Switching tabs updates the trajectory content and code preview accordingly.

Parallel Execution

The main Agent can call multiple task tools in a single turn, triggering parallel sub-agents:

Main Agent
├── task("Data cleaning")  → Sub-Agent A → read → bash → write → Done
├── task("Analysis")       → Sub-Agent B → read → bash → write → Done
└── task("Visualization")  → Sub-Agent C → read → bash → write → Done

The frontend uses a stack model (subAgentStack) to track the currently active sub-agent context, routing subsequent tool call events to the correct sub-agent trajectory.

Design Principles

Principle	Description
Minimal Context	Sub-agents receive only the task description, not the full conversation history, reducing token consumption
Tool Inheritance	Sub-agents automatically inherit the main Agent’s tool set with no extra configuration
Independent Execution	Sub-agents have their own reasoning loop and do not block the main Agent
Result Pass-through	Results are returned as standard Tool Results; the main Agent treats them like any other tool output
Error Isolation	Sub-agent failures do not crash the main Agent; errors are returned as Tool Results
UI Isolation	Sub-agent messages and tool calls are only displayed in TaskToolCallCard and the corresponding trajectory tab

Use Cases

Scenario	Example
Code Development	Delegate frontend components, backend APIs, and database schemas to separate sub-agents
Data Analysis	Split data cleaning, statistical analysis, and visualization into parallel subtasks
Information Research	Search multiple sources simultaneously, each sub-agent retrieves independently before aggregation
Document Writing	Delegate different sections to different sub-agents for parallel authoring
Batch Operations	Apply the same operation to multiple files or data sources in parallel

Get Started

Fundamentals

Core Capabilities

Infra

Channels

Overview

Architecture

Main Agent vs Sub-Agent

The `task` Tool

Parameters

Example

SubAgentMiddleware

Backend Configuration

Execution Flow

Frontend Integration

SSE Event Flow

Message Isolation

TaskToolCallCard

Trajectory Tabs

Parallel Execution

Design Principles

Use Cases

​Overview

​Architecture

​Main Agent vs Sub-Agent

​The task Tool

​Parameters

​Example

​SubAgentMiddleware

​Backend Configuration

​Execution Flow

​Frontend Integration

​SSE Event Flow

​Message Isolation

​TaskToolCallCard

​Trajectory Tabs

​Parallel Execution

​Design Principles

​Use Cases

Overview

Architecture

Main Agent vs Sub-Agent

The `task` Tool

Parameters

Example

SubAgentMiddleware

Backend Configuration

Execution Flow

Frontend Integration

SSE Event Flow

Message Isolation

TaskToolCallCard

Trajectory Tabs

Parallel Execution

Design Principles

Use Cases