跳转到主要内容

​
概述

SubAgent 是 Zeus 的任务委托机制。主 Agent 通过调用 task 工具，将子任务分派给独立的子智能体执行。每个子智能体拥有自己的上下文和推理循环，执行完毕后将结果作为 Tool Result 返回给主 Agent。 核心能力：
  • 任务分解 — 将复杂任务拆解为独立的子任务
  • 上下文隔离 — 每个子智能体拥有独立上下文，互不干扰
  • 并行执行 — 多个子任务可并行处理，提升效率
  • 结果汇总 — 子智能体完成后，结果返回主 Agent 继续推理

​
架构

​
主 Agent 与子智能体对比

维度主 Agent子智能体
上下文完整 System Prompt + 对话历史精简上下文 + 任务描述
工具集全部可用工具继承主 Agent 的工具集
模型用户配置的模型继承主 Agent 的模型
生命周期会话级别单次任务，完成即销毁
中间件完整中间件栈精简中间件栈
Todos有独立的任务列表write_todos 调用被跳过

​
task 工具

主 Agent 通过 task 工具触发子智能体。该工具由 DeepAgents 框架的 SubAgentMiddleware 自动注入。

​
参数

参数类型说明
descriptionstring任务的简短描述（用于 UI 展示）
promptstring详细的任务指令，子智能体以此为上下文执行

​
调用示例

​
SubAgentMiddleware

SubAgent 能力由 DeepAgents 框架的 SubAgentMiddleware 提供。在 Agent 创建时自动注册，将 task 工具注入主 Agent 的工具集。

​
后端配置

在 BaseService._create_agent() 中配置： 
SubAgentMiddleware(
    default_model=model,           # 子智能体继承主 Agent 的模型
    default_tools=tools,           # 子智能体继承主 Agent 的工具集
    subagents=subagents,           # 子智能体配置列表
    default_middleware=[           # 子智能体使用精简的中间件栈
        TodoListMiddleware(),
        SummarizationMiddleware(),
        AnthropicPromptCachingMiddleware(),
        PatchToolCallsMiddleware(),
    ],
    default_interrupt_on=interrupt_on,
    general_purpose_agent=True,
)

​
执行流程

​
前端集成

​
SSE 事件流

子智能体的执行通过标准 SSE 事件流传输到前端。前端通过事件中的 tool_name 和 tool_call_id 区分主 Agent 和子智能体的消息。

​
消息隔离

子智能体产生的消息（工具调用、文本）通过 subAgentTaskId 字段标记，不在主聊天流中显示：
  • 聊天区：子智能体的工具调用只展示在对应的 TaskToolCallCard 内部，不会出现在主消息流
  • 任务分组：groupMessagesIntoTasks 在处理前过滤掉 subAgentTaskId 消息，不影响主任务状态
  • Todos：子智能体的 write_todos 调用会被完全跳过，不影响主 Agent 的任务列表

​
TaskToolCallCard

每个 task 工具调用在聊天区渲染为一张可展开的卡片：
  • 收起状态：显示状态图标、任务描述、进度（如 5/11）、当前活动
  • 展开状态：列出子智能体内部所有工具调用及其状态
  • 运行中：蓝色边框高亮，带旋转加载图标
  • 支持点击 “View in trajectory →” 跳转到对应的轨迹标签页
并行的子智能体会各自显示独立的 TaskToolCallCard，分别展示进度。

​
轨迹区标签页

当存在子智能体时，轨迹区顶部显示标签页切换栏：
  • Main — 主 Agent 的工具执行历史
  • SubAgent — 每个子智能体拥有独立标签页，显示各自的工具执行历史
每个标签页有独立的步骤滑块（step slider），互不影响。切换标签页时，轨迹区内容和代码预览同步更新。

​
并行执行

主 Agent 可以在同一轮中调用多个 task 工具，触发并行子智能体： 
Main Agent
├── task("数据清洗")  → SubAgent A → read → bash → write → 完成
├── task("统计分析")  → SubAgent B → read → bash → write → 完成
└── task("生成图表")  → SubAgent C → read → bash → write → 完成
前端使用栈模型（subAgentStack）追踪当前活跃的子智能体上下文，将后续的工具调用事件路由到正确的子智能体轨迹中。

​
设计原则

原则说明
最小化上下文子智能体只接收任务描述，不继承完整对话历史，减少 token 消耗
工具继承子智能体自动继承主 Agent 的工具集，无需额外配置
独立执行子智能体拥有独立的推理循环，不阻塞主 Agent
结果透传执行结果作为标准 Tool Result 返回，主 Agent 无感知差异
错误隔离子智能体失败不会导致主 Agent 崩溃，错误信息作为 Tool Result 返回
UI 隔离子智能体的消息和工具调用仅在 TaskToolCallCard 和对应的轨迹标签页展示

​
使用场景

场景示例
代码开发将前端组件、后端 API、数据库 Schema 分别交给独立子智能体生成
数据分析数据清洗、统计分析、可视化拆分为并行子任务
信息调研同时搜索多个来源，各子智能体独立检索后汇总结果
文档编写不同章节委托给不同子智能体并行编写
批量操作对多个文件或数据源执行相同操作，并行处理