> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # 子 Agent > 在 Devin CLI 中将任务交给独立的子 Agent，它们可在前台或后台运行，并拥有各自的 Profile 和权限 子 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 模型**——除非 Admin 固定了某个模型，否则由子 Agent router 在 spawn 时选择；不是你在模型选择器中的选择 | 取决于默认子 Agent 模型，而不是你的主模型费率 | | `subagent_general` | **与父 Agent 相同的模型**——也就是你在模型选择器中选择的模型 (例如 Claude Opus、GPT-5) | 与父 Agent 费率相同：一个通用子 Agent 的成本相当于在你所选模型上额外开启一个完整会话 | | 自定义子 Agent | 如果设置了定义文件中的 `model` 字段，则使用该字段；否则使用**默认子 Agent 模型** | 取决于你固定的模型 | `subagent_general` 会继承父 Agent 的模型。如果你运行的是高级模型，那么每个通用子 Agent 也都会运行在该高级模型上，并拥有各自独立的上下文窗口和推理调用——因此，一个拆分为多个通用子 Agent 的 task 会成倍增加你的支出。当工作内容是研究而不是代码修改时，请要求使用 explore 子 Agent (或使用固定了更便宜 `model:` 的[自定义子 Agent](#custom-subagents)) 。 **默认子 Agent 模型**不是一个固定的模型名称——它会在 spawn 时通过服务端路由器解析，Admin 也可以对其进行覆盖 (见下文) 。在默认的 **子 Agent router** 设置下，路由器会从一个有序列表中选出第一个符合条件的模型，因此最终使用的模型可能会随你的套餐层级、模型可用性以及你的组织的模型策略而变化。该路由列表可能随时间变化，因此不要依赖子 Agent 总是落在某个特定模型上。 CLI 目前不会在子 Agent 面板中标明正在运行的子 Agent 使用的是哪个模型。

影响模型

你无法在提示中为子 Agent 指定模型——`run_subagent` 工具接收的是 *Profile*，不是模型。你有三种控制方式： 1. **用自然语言指定 Profile。** 请求一个 explore 子 Agent (“在 explore 子 Agent 中研究 auth 的工作方式”) 会让任务使用默认子 Agent 模型，而不是你选定的模型。请求代码修改则会使用 `subagent_general`，它会在你选定的模型上运行。 2. **在[自定义子 Agent](#custom-subagents) Profile 中固定模型。** 定义文件中的 `model:` 是让*具有写入能力*的子 Agent 运行在不同于父 Agent 的模型上的唯一方式。在子 Agent 中运行的 [技能](/zh/cli/extensibility/skills) 也可以在其 frontmatter 中设置 `model:`，以覆盖该 Profile 的模型。 3. **设置你自己的默认子 Agent 模型。** [配置文件](/zh/cli/reference/configuration/config-file#agent)中的 `agent.subagent_model` 会替换你的会话所用的默认子 Agent 模型。其优先级高于子 Agent router，也高于 Admin 固定为团队默认值的模型；但当 Admin 将该设置设为 **None** 时，它无法重新启用子 Agent： ```json theme={null} // ~/.config/devin/config.json { "agent": { "subagent_model": "swe-1-6-fast" } } ``` 该设置适用于 `subagent_explore` 以及未固定 `model:` 的自定义子 Agent；`subagent_general` 仍沿用父 Agent 的模型。所设模型必须是你的组织允许使用的模型，否则此设置将被忽略，转而使用团队默认模型。该设置仅对新会话生效。

企业控制

管理员可通过组织/企业设置中的 **默认子 Agent 模型** 设置，决定子 Agent 使用哪种模型，以及是否允许子 Agent 运行。此设置控制 `subagent_explore` 以及未固定 `model:` 的自定义子 Agent 所使用的模型——但不会更改 `subagent_general`，后者始终遵循父 Agent 的模型。 默认子 Agent 模型设置 它有三个选项： | 选项 | 行为 | | - | - | | **子 Agent router (default)** | 默认子 Agent 模型会在生成时由服务端路由器选择。所选模型取决于你的套餐层级、模型可用性以及你的组织允许使用的模型。 | | **A specific model** | 对于所有不使用父 Agent 模型运行的子 Agent，都会将默认子 Agent 模型固定为所选模型。 | | **None** | 完全禁用子 Agent——Devin 不会生成任何子 Agent。 | ***

启用和禁用子 Agent

子 Agent 默认启用。在你的[配置文件](/zh/cli/reference/configuration/config-file#subagents_enabled)中将 `subagents_enabled` 设为 `false`，即可移除 `run_subagent` 和 `read_subagent` 工具，让 Agent 自行完成所有工作： ```json theme={null} // ~/.config/devin/config.json { "subagents_enabled": false } ``` 更改会立即生效，正在运行的会话无需重启即可采用该更改。在 Devin Desktop 中，对应功能是设置中的 **子 Agent (预览) ** 开关。 Organization policy 优先：如果 Admin 将 **默认子 Agent 模型** 设为 **None**，无论此设置如何，子 Agent 都会保持禁用状态。 ***

子 Agent Profile

每个子 Agent 都会以特定的 Profile 运行，该 Profile 决定其能力。有两个内置 Profile： | Profile | 说明 | 工具访问权限 | 模型 | | - | - | - | - | | `subagent_explore` | 只读的代码库探索与研究 | 只读代码库工具以及网页搜索；无法编辑文件，也无法抓取任意 URL (无论在前台还是后台) | 默认子 Agent 模型 (由路由选择，除非 admin 固定指定) | | `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 因所需工具被拒绝而失败，你可以在前台恢复它，以批准所需权限。请参阅下方的 [恢复子 Agent](#resuming-subagents)。 ***

子 Agent 监控

子 Agent 指示器

当后台 子 Agent 运行时，输入区域下方会显示一个指示器，用于显示其状态。你可以在输入区域按 ↓ 将焦点移动到该指示器，然后按 Enter 打开 子 Agent 面板。 当前台 子 Agent 运行时，加载指示器会显示 **"Subagent 正在运行 · Ctrl+B 可切换到后台运行"**。

子 Agent 面板

子 Agent 面板可让你查看和管理所有活跃中和已完成的子 Agent。它会显示每个子 Agent 的 Profile、标题、状态、耗时以及工具调用次数。重新加载会话后，子 Agent 活动仍会保留，因此恢复后面板仍会显示你的子 Agent。 ***

前台 / 后台切换

你可以在子 Agent 运行时在前台和后台之间切换： * **将前台子 Agent 切换到后台：** 在前台子 Agent 运行时，按 Ctrl+B。子 Agent 会继续在后台运行，父 Agent 则恢复执行。 * **将后台子 Agent 切换到前台：** 打开子 Agent 面板，在正在运行的后台子 Agent 上按 f。子 Agent 的输出将以内联方式显示。 当你将子 Agent 移到后台时，父 Agent 的工具调用已经返回，因此父 Agent 会继续独立执行。子 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/` 目录下的 Markdown 文件定义，可采用以下任一结构： * **单文件** — `agents/.md` (与 Claude Code、Cursor 和其他工具采用的约定相同) 。文件名 (不含 `.md`) 会作为该 Profile 的标识符。 * **目录** — `agents//AGENT.md`。目录名会作为该 Profile 的标识符。也支持使用 `AGENTS.md`、`agent.md` 和 `agents.md` 作为文件名 (如果同时存在多个，则优先使用 `AGENT.md`，其次是 `AGENTS.md`、`agent.md`、`agents.md`) 。 在这两种结构中，frontmatter 里的 `name:` 会覆盖从路径派生出的标识符。 ```text theme={null} .devin/agents/ ├── reviewer.md └── researcher/ └── AGENT.md ``` 也支持： ```text theme={null} .agents/agents/ ├── reviewer.md └── researcher/ └── AGENT.md ``` ```text theme={null} # Linux/macOS ~/.config/devin/agents/ ├── reviewer.md └── researcher/ └── AGENT.md # Windows %APPDATA%\devin\agents\ ├── reviewer.md └── researcher\ └── AGENT.md ```

定义文件格式

子 Agent 定义文件使用与技能相同的 YAML frontmatter，随后是子 Agent 的系统提示： ```markdown theme={null} --- name: reviewer description: Reviews code changes for correctness and style model: sonnet allowed-tools: - read - grep - glob - exec --- 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 模型 (由路由自动选择，除非 Admin 固定了某个模型) — **不是**父 Agent 的模型 | 覆盖该子 Agent 使用的模型 | | `allowed-tools` | 列表 | 所有工具 | 限制该子 Agent 可使用的工具。不能授予 `ask_user_question`，因为子 Agent 始终无法使用该工具。也接受别名 `tools`。 | | `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

```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 --- You are a test runner subagent. Run the relevant test suites and report: - Which tests passed and failed - Failure messages and stack traces - Suggestions for fixing failures ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.