Skip to main content

​
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

DimensionMain AgentSub-Agent
ContextFull System Prompt + conversation historyMinimal context + task description
ToolsAll available toolsInherits main Agent’s tool set
ModelUser-configured modelInherits main Agent’s model
LifecycleSession-levelSingle task, destroyed on completion
MiddlewareFull middleware stackLightweight middleware stack
TodosHas its own task listwrite_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

ParameterTypeDescription
descriptionstringShort task description (used for UI display)
promptstringDetailed 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

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

​
Use Cases

ScenarioExample
Code DevelopmentDelegate frontend components, backend APIs, and database schemas to separate sub-agents
Data AnalysisSplit data cleaning, statistical analysis, and visualization into parallel subtasks
Information ResearchSearch multiple sources simultaneously, each sub-agent retrieves independently before aggregation
Document WritingDelegate different sections to different sub-agents for parallel authoring
Batch OperationsApply the same operation to multiple files or data sources in parallel