---
title: "子 Agent"
description: "主 Agent 可以启动子 Agent 来并行工作或委派专业任务。理解三种子 Agent 路径、工具池隔离、Fork 的缓存优化和异步生命周期管理。"
keywords: ["子 Agent", "AgentTool", "任务委派", "子进程隔离"]
---

## 核心问题

单个 Agent 的上下文窗口是有限的。当需要同时研究多个方向、并行执行多个操作时，一个 Agent 做不过来。

子 Agent 让主 Agent 可以启动独立的 AI 实例来并行工作——每个子 Agent 有自己的上下文窗口和工具集。

## 三种子 Agent 路径

系统根据参数和配置走三条不同的路径：

| 路径 | 触发条件 | 上下文 | 设计目的 |
|------|---------|--------|---------|
| **命名 Agent** | 指定 `subagent_type` | 仅任务描述 | 专业任务委派 |
| **Fork 子进程** | 启用 Fork + 未指定类型 | 继承父 Agent 完整对话 | Prompt Cache 优化 |
| **通用回退** | 未启用 Fork + 未指定类型 | 仅任务描述 | 通用任务处理 |

### 命名 Agent：专业委派

系统预定义了几个内置 Agent，各有明确的职责：

| Agent | 模型 | 工具 | 用途 |
|-------|------|------|------|
| **Explore** | Haiku（轻量快速） | 只读（Read/Grep/Glob） | 代码库搜索与探索 |
| **Plan** | 继承父模型 | 只读 | 为 Plan Mode 收集信息 |
| **General-purpose** | 继承父模型 | 全部工具 | 复杂通用任务 |

**设计考量**：Explore Agent 使用 Haiku 模型（更便宜、更快），因为搜索任务不需要 Opus 的推理能力。模型选择是成本和能力的权衡——不是每个子任务都需要最强的模型。

### Fork 子进程：缓存优化

Fork 路径的核心设计是 **Prompt Cache 共享**：所有 fork 子进程共享父 Agent 的完整对话历史，只有最后的指令不同。这使得 API 请求的前缀完全一致，最大化缓存命中。

**为什么不用命名 Agent**？命名 Agent 只拿到任务描述，缺乏父 Agent 的完整上下文。Fork 让子进程"看到"父 Agent 看到的一切，代价是更高的 token 消耗——但通过 Prompt Cache，这部分消耗被大幅降低。

Fork 有两道防线防止递归创建子 Agent：检查查询来源标记和扫描消息中的特殊标签。

### 模型解析优先级

子 Agent 的模型选择遵循优先级链：

```
环境变量覆盖 > 每次调用参数 > Agent 定义的模型 > 继承父对话模型
```

`inherit` 不是简单的模型传递——它经过运行时解析，确保 plan mode 下的模型映射正确生效。

## 工具池隔离

子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装。

**设计考量**：父 Agent 可能处于受限模式（如 Plan Mode），但子 Agent 可能需要完整的工具集来执行任务。独立的工具池让子 Agent 的权限不受父 Agent 限制。

Fork 子进程例外——它直接继承父 Agent 的工具池，以保持 Prompt Cache 中工具定义的字节一致性。

### Agent 级 MCP 服务器

子 Agent 可以额外连接专属的 MCP 服务器。如果 Agent 声明了 `requiredMcpServers`，系统会等待这些服务器连接完成（最长 30 秒），确保工具可用后才启动。

## Worktree 隔离

`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作：

```
创建 worktree → 子 Agent 在独立副本中工作 → 完成
  → 有变更：保留 worktree，返回路径
  → 无变更：自动删除
```

**设计目的**：子 Agent 的实验性修改不应该影响主分支。Worktree 提供了文件系统级别的隔离，同时保持对完整代码库的访问。

## 生命周期：同步 vs 异步

### 异步 Agent（后台运行）

异步 Agent 立即返回 `async_launched` 状态，主 Agent 可以继续工作。后台 Agent 完成后通过通知机制汇报结果。

异步 Agent 获得独立的 AbortController——用户取消主线程不会杀掉后台 Agent。这确保长时间运行的构建/测试任务不会被意外中断。

### 同步 Agent（前台运行）

同步 Agent 有一个"可后台化"机制：如果执行超过阈值（默认 120 秒），系统自动将其转为后台运行。这防止了一个慢子 Agent 阻塞整个工作循环。

## 适用场景

<CardGroup cols={2}>
  <Card title="并行研究" icon="magnifying-glass">
    多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀
  </Card>
  <Card title="专业委派" icon="code-branch">
    使用命名 Agent 执行专业任务，受限工具集 + 独立权限
  </Card>
  <Card title="隔离实验" icon="flask">
    worktree 隔离中尝试方案，不影响主分支
  </Card>
  <Card title="后台构建" icon="layer-group">
    异步启动长时间构建/测试，主 Agent 继续工作
  </Card>
</CardGroup>

## 接下来

- **协调者与蜂群** — 理解多 Agent 的高级编排模式
- **Worktree 隔离** — 深入理解文件系统隔离机制
- **任务管理** — 理解支撑多 Agent 的任务追踪