> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 子 Agent
> 将任务交给可在前台或后台运行的独立子 Agent
子 Agent 让主 Agent 能够生成独立的工作单元来处理子任务。子 Agent 会与父 Agent 共享工具和代码库上下文，但会在自己的对话链中运行——不会继承父 Agent 的对话历史。这对于那些适合专注、独立处理的任务尤其有用——例如探索代码库、运行测试，或并行实现某项功能。
你可以明确要求 Agent 使用子 Agent (例如“在子 Agent 中调研认证机制的工作方式”) ，或者当 Agent 判断某项任务适合独立处理时，也可能自行决定交给子 Agent。
根据我们的测量，**子 Agent** **既能** **提升整体编码效率** **又能** **降低成本**。
***
## 子 Agent 的工作方式
当 Agent 生成子 Agent 时，会从可用的**子 Agent Profile**中选择一个，并决定该子 Agent 在前台还是后台运行。子 Agent 可以按以下两种模式运行：
在你的当前会话中内联运行。父 Agent 会暂停，并等待子 Agent 完成后再继续。你可以在工具调用出现时逐个批准或拒绝。
在父 Agent 继续工作的同时并行运行。子 Agent 完成后，父 Agent 会自动收到通知。未经批准的工具调用会被自动拒绝。
你无法直接看到子 Agent 的原始输出。子 Agent 完成后，父 Agent 会读取结果，并为你总结关键发现和执行的操作。
### 子 Agent 成本
子 Agent 会作为独立的 Agent 会话运行，每个都有自己的上下文窗口和推理调用，因此会独立于父级产生费用。父级的支出只覆盖其自身的工作；它生成的每个子 Agent 都会在此基础上增加各自的用量。
对于按提示计费的套餐，每个子 Agent 都会像用户消息一样消耗额外积分。消耗的积分数量取决于子 Agent 使用的模型，因此，生成多个子 Agent 的任务 (或将它们 [嵌套](/zh/cli/subagents#nesting-depth)) 会消耗更多积分。
由于成本会随子 Agent 数量增加而上升，因此，拆分出大量子 Agent (或对其进行[嵌套](#nesting-depth)) 的任务成本也会更高。只有在并行处理或聚焦上下文确实值得额外支出时，才应谨慎使用子 Agent。
***
## 子 Agent 使用哪个模型？
子 Agent 并不都会使用你在模型选择器中选定的模型。每个 Profile 都决定了它的模型来源：
| Profile | 使用的模型 | 对配额 / 积分的影响 |
| ------------------ | ----------------------------------------------------------- | ------------------------------------------------- |
| `subagent_explore` | **默认子 Agent 模型**——一种快速、低成本的模型 (默认为 SWE-1.6) | 成本较低：SWE-1.6 的用量按 SWE 费率计费，而不是按你的主模型费率计费 |
| `subagent_general` | **与父 Agent 相同的模型**——也就是你在模型选择器中选择的模型 (例如 Claude Opus、GPT-5) | 与父 Agent 费率相同：一个通用子 Agent 的成本相当于在你所选模型上额外开启一个完整会话 |
| 自定义子 Agent | 如果设置了 `AGENT.md` 中的 `model` 字段，则使用该字段；否则使用**默认子 Agent 模型** | 取决于你固定的模型 |
`subagent_general` 会继承父 Agent 的模型。如果你运行的是高级模型，那么每个通用子 Agent 也都会运行在该高级模型上，并拥有各自独立的上下文窗口和推理调用——因此，一个拆分为多个通用子 Agent 的 task 会成倍增加你的支出。当工作内容是研究而不是代码修改时，请要求使用 explore 子 Agent (或使用固定了更便宜 `model:` 的[自定义子 Agent](#custom-subagents)) 。
**默认子 Agent 模型**不是一个固定的模型名称——它会在 spawn 时通过路由器解析，Admin 也可以对其进行覆盖 (见下文) 。在默认的 **子 Agent router** 设置下，它会解析为 SWE-1.6 (根据你的套餐层级，可能是速度更快或更慢的 SWE-1.6 变体) 。
CLI 目前不会在子 Agent 面板中标明正在运行的子 Agent 使用的是哪个模型。
### 影响模型
你无法在提示中为子 Agent 指定模型——`run_subagent` 工具接收的是 *Profile*，不是模型。你有两种控制方式：
1. **用自然语言指定 Profile。** 请求一个 explore 子 Agent (“在 explore 子 Agent 中研究 auth 的工作方式”) 会让任务继续使用成本较低的默认子 Agent 模型。请求代码修改则会使用 `subagent_general`，它会在你选定的模型上运行。
2. **在[自定义子 Agent](#custom-subagents) Profile 中固定模型。** `AGENT.md` 中的 `model:` 是让具备 *write-capable* 能力的子 Agent 运行在不同于父 Agent 的模型上的唯一方式。在子 Agent 中运行的 [skill](/zh/cli/extensibility/skills) 也可以在其 frontmatter 中设置 `model:`，以覆盖该 Profile 的模型。
### 企业控制
管理员可通过组织/企业设置中的 **Default 子 Agent model** 设置，决定子 Agent 使用哪种模型，以及是否允许子 Agent 运行。此设置控制 `subagent_explore` 以及未固定 `model:` 的自定义子 Agent 所使用的模型——但不会更改 `subagent_general`，后者始终遵循父 Agent 的模型。
它有三个选项：
| 选项 | 行为 |
| ---------------------------- | -------------------------------------------------------- |
| **子 Agent router (default)** | 默认子 Agent 模型会在生成时由路由器选择。当前会解析为 SWE-1.6 (具体变体取决于你的套餐层级) 。 |
| **A specific model** | 对于所有不使用父 Agent 模型运行的子 Agent，都会将默认子 Agent 模型固定为所选模型。 |
| **None** | 完全禁用子 Agent——Devin 不会生成任何子 Agent。 |
***
## 子 Agent Profile
每个子 Agent 都会以特定的 Profile 运行，该 Profile 决定其能力。有两个内置 Profile：
| Profile | 说明 | 工具访问权限 | 模型 |
| ------------------ | ------------- | -------------------------------------------- | -------------------------- |
| `subagent_explore` | 只读的代码库探索与研究 | 只读代码库工具以及网页搜索；无法编辑文件，也无法抓取任意 URL (无论在前台还是后台) | 默认子 Agent 模型 (默认为 SWE-1.6) |
| `subagent_general` | 包括代码修改在内的通用任务 | 完整工具访问权限 (前台) 或仅可使用预先批准的工具 (后台) | 与父 Agent 相同的模型 |
Agent 会根据任务自动选择合适的 Profile。探索型子 Agent 非常适合用于研究和理解，而通用子 Agent 则可以进行修改。关于每个 Profile 如何选择其模型，请参阅 [子 Agent 使用哪个模型？](#which-model-does-a-subagent-use)——这两个 Profile **并非**运行在同一个模型上。
你也可以自定义子 Agent Profile——请参阅下方的 [自定义子 Agent](#custom-subagents)。
***
## 工具权限
工具权限的运作方式取决于子 Agent 是在前台还是后台运行：
* **前台子 Agent** 的行为与主 Agent 类似——你会像往常一样收到提示，批准或拒绝工具调用。
* **后台子 Agent** 会继承你在当前会话中已授予的工具权限。任何未预先批准的工具都会被自动拒绝。后台子 Agent 无法提示你授予新权限。
如果后台子 Agent 因所需工具被拒绝而失败，你可以在前台恢复它，以批准所需权限。请参阅下方的 [恢复子 Agent](#resuming-subagents)。
***
## 子 Agent 监控
### 子 Agent 指示器
当后台 子 Agent 运行时，输入区域下方会显示一个指示器，用于显示其状态。你可以在输入区域按 ↓ 将焦点移动到该指示器，然后按 Enter 打开 子 Agent 面板。
当前台 子 Agent 运行时，加载指示器会显示 **"Subagent 正在运行 · Ctrl+B 可切换到后台运行"**。
### 子 Agent 面板
子 Agent 面板可让你查看和管理所有活跃中和已完成的子 Agent。它会显示每个子 Agent 的 Profile、标题、状态、耗时以及工具调用次数。
***
## 前台 / 后台切换
你可以在子 Agent 运行时在前台和后台之间切换：
* **将前台子 Agent 切换到后台：** 在前台子 Agent 运行时，按 Ctrl+B。子 Agent 会继续在后台运行，父 Agent 则恢复执行。
* **将后台子 Agent 切换到前台：** 打开子 Agent 面板，在正在运行的后台子 Agent 上按 f。子 Agent 的输出将以内联方式显示。
当你将子 Agent 移到后台时，父 Agent 的工具调用已经返回，因此父 Agent 会继续独立执行。子 Agent 的结果不会再反馈到父 Agent 当前的处理流程中，但它完成时你会收到通知。
***
## 取消子 Agent
你可以通过以下两种方式取消正在运行的子 Agent：
1. **通过子 Agent 面板：** 打开面板，然后在正在运行的子 Agent 上按 x。
2. **前台子 Agent：** 按 Ctrl+C 或 Esc，取消当前正在运行的前台子 Agent。
***
## 恢复子 Agent
已取消、失败或已完成的子 Agent都可以通过新的提示恢复。你可以让 Agent 恢复某个子 Agent，它会从中断处继续。恢复后的子 Agent始终在**前台**运行，因此你可以批准此前被拒绝的任何工具调用。
这在以下情况下尤其有用：
* 后台子 Agent因某个必需工具被拒绝而失败——可在前台恢复它，以授予所需权限。
* 某个子 Agent已完成，但你希望它根据其发现继续执行额外的后续工作。
* 某个子 Agent被过早取消，而你希望它继续执行。
***
## 嵌套深度
默认情况下，子 Agent 无法再生成自己的子 Agent——只有根 Agent 可以。为防止出现无限嵌套，子 Agent 内会禁用子 Agent 工具 (`run_subagent` 和 `read_subagent`) 。
不过，**自定义子 Agent 的 Profile** 可以通过在其 frontmatter 中设置 `max-nesting` 字段来启用嵌套生成。该值会覆盖默认的最大深度；只要树结构不超过这个限制，子 Agent 就可以生成子级。
例如，`max-nesting: 3` 允许出现如下链式结构：
```
Root agent（深度 0）
└── Custom subagent（深度 1）— 可以生成子 Agent
└── Child subagent（深度 2）— 可以生成子 Agent
└── Grandchild subagent（深度 3）— 无法生成（已达深度上限）
```
嵌套子 Agent 可能会显著增加成本。每增加一层嵌套，都会生成额外的 Agent，并带有各自的上下文窗口和推理调用。请谨慎使用此功能。
***
## 自定义子 Agent
自定义子 Agent 是**实验性**功能。其格式、行为和配置选项可能会在后续版本中发生变化。
除了内置的 `subagent_explore` 和 `subagent_general` Profile 外，你还可以定义自己的自定义子 Agent Profile。自定义子 Agent 可让你创建专用工作单元，并为其设置各自的系统提示、工具限制、模型覆盖和权限，以适配工作流程中的特定任务。这也是获得具有写入能力且**不会**在你的 (可能成本较高的) 主模型上运行的子 Agent 的方式：为它指定一个 `model:` 以及所需的工具。
### 创建自定义子 Agent
自定义子 Agent 通过在 `agents/` 下的具名目录中放置 `AGENT.md` 文件来定义。目录名称将作为该 Profile 的标识符。
```text theme={null}
.devin/agents/
└── reviewer/
└── AGENT.md
```
也支持：
```text theme={null}
.agents/agents/
└── reviewer/
└── AGENT.md
```
```text theme={null}
# Linux/macOS
~/.config/devin/agents/
└── reviewer/
└── AGENT.md
# Windows
%APPDATA%\devin\agents\
└── reviewer\
└── AGENT.md
```
### AGENT.md 格式
`AGENT.md` 文件使用与技能相同的 YAML frontmatter，随后是子 Agent 的系统提示：
```markdown theme={null}
---
name: reviewer
description: Reviews code changes for correctness and style
model: sonnet
allowed-tools:
- read
- grep
- glob
- exec
permissions:
allow:
- Exec(git diff)
- Exec(git log)
deny:
- write
- edit
---
You are a code review subagent. Your job is to review code changes
thoroughly and report findings back to the parent agent.
Focus on:
1. Correctness — logic errors, edge cases, off-by-one mistakes
2. Security — potential vulnerabilities
3. Style — consistency with the rest of the codebase
4. Performance — obvious inefficiencies
Always cite specific file paths and line numbers in your findings.
```
### Frontmatter 字段
| 字段 | 类型 | 默认值 | 描述 |
| --------------- | ------- | ---------------------------------------------- | --------------------------------------------------------------- |
| `name` | string | 目录名 | 该 Profile 的标识符 (不得与内置 Profile 冲突) |
| `description` | string | 无 | 在选择 Profile 时向 Agent 显示 |
| `model` | string | 默认子 Agent 模型 (默认为 SWE-1.6) — **不是**父 Agent 的模型 | 覆盖该子 Agent 使用的模型 |
| `allowed-tools` | 列表 | 所有工具 | 限制该子 Agent 可使用的工具。不能授予 `ask_user_question`，因为子 Agent 始终无法使用该工具。 |
| `permissions` | object | 继承 | 权限覆盖 (`allow`、`deny`、`ask`) |
| `max-nesting` | integer | 无 | 覆盖最大嵌套深度，使该子 Agent 能够生成自己的子 Agent |
### 自定义子 Agent 的使用方式
定义完成后，自定义子 Agent 的 Profile 会与内置 Profile 一起显示。Agent 会看到每个可用 Profile 的说明，并在创建子 Agent 时选择最合适的一个。你也可以要求 Agent 按名称使用特定的 Profile (例如：“使用 reviewer 子 Agent 审查这段代码”) 。
如果自定义子 Agent 的 Profile 名称与内置 Profile 名称冲突 (例如 `subagent_explore`、`subagent_general`) ，则会跳过该 Profile 并显示警告。
### 从其他工具导入
自定义子 Agent 也可以从 Claude Code 的 Agent 格式中导入：
| 来源 | 文件匹配模式 |
| --------------------- | ---------------------------------- |
| `.claude/agents/*.md` | 每个 `.md` 文件都会成为一个子 Agent 的 Profile |
Claude Code 的 Agent 文件在 `frontmatter` 中使用 `tools`，而不是 `allowed-tools`。这两种格式都会被自动支持。
### 示例
#### 只读调研 Agent
```markdown theme={null}
---
name: researcher
description: Deep codebase research and architecture analysis
model: sonnet
allowed-tools:
- read
- grep
- glob
---
You are a research subagent specializing in codebase exploration.
Your job is to thoroughly investigate a topic and report back with:
- Relevant files and their purposes
- Architecture patterns and dependencies
- Code flow traces with specific line references
Be exhaustive — search broadly and follow references.
```
#### 测试执行 Agent
```markdown theme={null}
---
name: test-runner
description: Runs tests and reports results
allowed-tools:
- read
- grep
- glob
- exec
permissions:
allow:
- Exec(npm run test)
- Exec(cargo nextest)
- Exec(pytest)
---
你是一个测试运行 子 Agent。运行相关的 test suites 并报告：
- 哪些测试通过，哪些失败
- 失败信息和 stack traces
- 针对失败的修复建议
```