> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 子智能体

> Zeus SubAgent — 任务委托与并行执行

## 概述

SubAgent 是 Zeus 的**任务委托机制**。主 Agent 通过调用 `task` 工具，将子任务分派给独立的子智能体执行。每个子智能体拥有自己的上下文和推理循环，执行完毕后将结果作为 Tool Result 返回给主 Agent。

核心能力：

* **任务分解** — 将复杂任务拆解为独立的子任务
* **上下文隔离** — 每个子智能体拥有独立上下文，互不干扰
* **并行执行** — 多个子任务可并行处理，提升效率
* **结果汇总** — 子智能体完成后，结果返回主 Agent 继续推理

***

## 架构

```mermaid theme={null}
graph TD
    subgraph MainAgent["主 Agent"]
        direction TB
        plan["1. 分析任务"]
        delegate["2. 调用 task 工具"]
        collect["3. 收集 Tool Result"]
        synthesize["4. 综合推理"]
    end

    subgraph SubAgents["子智能体"]
        direction TB
        sa1["SubAgent A<br/>独立上下文 · 继承工具"]
        sa2["SubAgent B<br/>独立上下文 · 继承工具"]
        sa3["SubAgent C<br/>独立上下文 · 继承工具"]
    end

    plan --> delegate
    delegate --> sa1 & sa2 & sa3
    sa1 & sa2 & sa3 --> collect
    collect --> synthesize
```

### 主 Agent 与子智能体对比

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

***

## `task` 工具

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

### 参数

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

### 调用示例

```mermaid theme={null}
sequenceDiagram
    participant User as 用户
    participant Main as 主 Agent
    participant SA1 as SubAgent (分析)
    participant SA2 as SubAgent (可视化)

    User->>Main: "分析数据并生成报告"
    Main->>Main: 规划任务拆分

    par 并行执行
        Main->>SA1: task(description="数据分析", prompt="分析 sales.csv...")
        SA1->>SA1: read → bash → write
        SA1-->>Main: Tool Result: 分析结果
    and
        Main->>SA2: task(description="生成图表", prompt="根据数据生成可视化...")
        SA2->>SA2: read → bash → write
        SA2-->>Main: Tool Result: 图表结果
    end

    Main->>Main: 综合分析 + 图表
    Main-->>User: 完整报告
```

***

## SubAgentMiddleware

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

### 后端配置

在 `BaseService._create_agent()` 中配置：

```python theme={null}
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,
)
```

### 执行流程

```mermaid theme={null}
flowchart TD
    A["主 Agent 调用 task()"] --> B["SubAgentMiddleware 拦截"]
    B --> C["创建子 Agent 实例"]
    C --> D["注入任务描述 + 继承工具集"]
    D --> E["子 Agent 独立推理循环"]
    E --> F["子 Agent 调用工具<br/>read / write / bash / ..."]
    F --> E
    E --> G{"执行完成?"}
    G -->|"完成"| H["返回结果给主 Agent"]
    G -->|"失败"| I["返回错误信息"]
    H --> J["主 Agent 继续推理"]
    I --> J
```

***

## 前端集成

### SSE 事件流

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

```mermaid theme={null}
sequenceDiagram
    participant Backend as 后端
    participant Handler as 消息处理器
    participant Store as trajectoryStore
    participant UI as 前端 UI

    Backend->>Handler: tool_call (task)
    Handler->>Store: createAgentTrajectory(taskId)
    Handler->>Store: enterSubAgent(taskId)
    Store->>UI: 新增子智能体标签页

    loop 子智能体执行
        Backend->>Handler: tool_call (read/write/bash...)
        Handler->>Store: addToolExecutionToAgent(taskId, exec)
        Store->>UI: 更新 TaskToolCallCard + 轨迹区
    end

    Backend->>Handler: tool_call_result (task)
    Handler->>Store: exitSubAgent(taskId)
    Handler->>Store: completeAgentTrajectory(taskId)
    Store->>UI: 标记完成，切回主标签
```

### 消息隔离

子智能体产生的消息（工具调用、文本）通过 `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 分别交给独立子智能体生成 |
| 数据分析 | 数据清洗、统计分析、可视化拆分为并行子任务                |
| 信息调研 | 同时搜索多个来源，各子智能体独立检索后汇总结果              |
| 文档编写 | 不同章节委托给不同子智能体并行编写                    |
| 批量操作 | 对多个文件或数据源执行相同操作，并行处理                 |