> ## 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

> 将任务交给可在前台或后台运行的独立子 Agent

子 Agent 让主 Agent 能够生成独立的工作单元来处理子任务。子 Agent 会与父 Agent 共享工具和代码库上下文，但会在自己的对话链中运行——不会继承父 Agent 的对话历史。这对于那些适合专注、独立处理的任务尤其有用——例如探索代码库、运行测试，或并行实现某项功能。

你可以明确要求 Agent 使用子 Agent (例如“在子 Agent 中调研认证机制的工作方式”) ，或者当 Agent 判断某项任务适合独立处理时，也可能自行决定交给子 Agent。

根据我们的测量，**子 Agent** **既能** **提升整体编码效率** **又能** **降低成本**。

***

<div id="how-subagents-work">
  ## 子 Agent 的工作方式
</div>

当 Agent 生成子 Agent 时，会从可用的**子 Agent Profile**中选择一个，并决定该子 Agent 在前台还是后台运行。子 Agent 可以按以下两种模式运行：

<CardGroup cols={2}>
  <Card title="前台" icon="display">
    在你的当前会话中内联运行。父 Agent 会暂停，并等待子 Agent 完成后再继续。你可以在工具调用出现时逐个批准或拒绝。
  </Card>

  <Card title="后台" icon="clock">
    在父 Agent 继续工作的同时并行运行。子 Agent 完成后，父 Agent 会自动收到通知。未经批准的工具调用会被自动拒绝。
  </Card>
</CardGroup>

<Note>
  你无法直接看到子 Agent 的原始输出。子 Agent 完成后，父 Agent 会读取结果，并为你总结关键发现和执行的操作。
</Note>

<div id="subagent-cost">
  ### 子 Agent 成本
</div>

子 Agent 会作为独立的 Agent 会话运行，每个都有自己的上下文窗口和推理调用，因此会独立于父级产生费用。父级的支出只覆盖其自身的工作；它生成的每个子 Agent 都会在此基础上增加各自的用量。

<Note>
  对于按提示计费的套餐，每个子 Agent 都会像用户消息一样消耗额外积分。消耗的积分数量取决于子 Agent 使用的模型，因此，生成多个子 Agent 的任务 (或将它们 [嵌套](/zh/cli/subagents#nesting-depth)) 会消耗更多积分。
</Note>

由于成本会随子 Agent 数量增加而上升，因此，拆分出大量子 Agent (或对其进行[嵌套](#nesting-depth)) 的任务成本也会更高。只有在并行处理或聚焦上下文确实值得额外支出时，才应谨慎使用子 Agent。

<div id="enterprise-controls">
  ### 企业控制
</div>

管理员可通过组织/企业设置中的 **Default subagent model** 设置，决定子 Agent 使用哪种模型，以及是否允许子 Agent 运行。

<Frame>
  <img src="https://mintcdn.com/cognitionai/d7_AE5155dfGCsnK/images/cli/default-subagent-model-setting.png?fit=max&auto=format&n=d7_AE5155dfGCsnK&q=85&s=e924249f64bf6ac6e0ffcf59b289aeb3" alt="默认子 Agent 模型设置" width="1024" height="114" data-path="images/cli/default-subagent-model-setting.png" />
</Frame>

此设置用于控制 Devin 启动的子 Agent 会话所使用的模型，共有三个选项：

| 选项                            | 行为                                |
| ----------------------------- | --------------------------------- |
| **Subagent router (default)** | Devin 会根据任务和父级模型，使用默认路由自动选择模型。    |
| **A specific model**          | 无论任务或父级模型如何，都会将每个子 Agent 固定到所选模型。 |
| **None**                      | 完全禁用子 Agent——Devin 不会生成任何子 Agent。 |

***

<div id="subagent-profiles">
  ## 子 Agent Profile
</div>

每个子 Agent 都会以特定的 Profile 运行，该 Profile 决定其能力。有两个内置 Profile：

| Profile            | 说明            | 工具访问权限                                       |
| ------------------ | ------------- | -------------------------------------------- |
| `subagent_explore` | 只读的代码库探索与研究   | 只读代码库工具以及网页搜索；无法编辑文件，也无法抓取任意 URL (无论在前台还是后台) |
| `subagent_general` | 包括代码修改在内的通用任务 | 完整工具访问权限 (前台) 或仅可使用预先批准的工具 (后台)              |

<Note>
  Agent 会根据任务自动选择合适的 Profile。探索型子 Agent 非常适合用于研究和理解，而通用子 Agent 则可以进行修改。
</Note>

你也可以自定义子 Agent Profile——请参阅下方的 [Custom Subagents](#custom-subagents)。

***

<div id="tool-permissions">
  ## 工具权限
</div>

工具权限的运作方式取决于子 Agent 是在前台还是后台运行：

* **前台子 Agent** 的行为与主 Agent 类似——你会像往常一样收到提示，批准或拒绝工具调用。
* **后台子 Agent** 会继承你在当前会话中已授予的工具权限。任何未预先批准的工具都会被自动拒绝。后台子 Agent 无法提示你授予新权限。

<Tip>
  如果后台子 Agent 因所需工具被拒绝而失败，你可以在前台恢复它，以批准所需权限。请参阅下方的 [恢复子 Agent](#resuming-subagents)。
</Tip>

***

<div id="monitoring-subagents">
  ## 子 Agent 监控
</div>

<div id="subagent-indicator">
  ### 子 Agent 指示器
</div>

当后台 子 Agent 运行时，输入区域下方会显示一个指示器，用于显示其状态。你可以在输入区域按 <kbd>↓</kbd> 将焦点移动到该指示器，然后按 <kbd>Enter</kbd> 打开 子 Agent 面板。

当前台 子 Agent 运行时，加载指示器会显示 **"Subagent 正在运行 · Ctrl+B 可切换到后台运行"**。

<div id="subagent-panel">
  ### 子 Agent 面板
</div>

子 Agent 面板可让你查看和管理所有活跃中和已完成的子 Agent。它会显示每个子 Agent 的 Profile、标题、状态、耗时以及工具调用次数。

***

<div id="foreground-background-switching">
  ## 前台 / 后台切换
</div>

你可以在子 Agent 运行时在前台和后台之间切换：

* **将前台子 Agent 切换到后台：** 在前台子 Agent 运行时，按 <kbd>Ctrl</kbd>+<kbd>B</kbd>。子 Agent 会继续在后台运行，父 Agent 则恢复执行。
* **将后台子 Agent 切换到前台：** 打开子 Agent 面板，在正在运行的后台子 Agent 上按 <kbd>f</kbd>。子 Agent 的输出将以内联方式显示。

<Note>
  当你将子 Agent 移到后台时，父 Agent 的工具调用已经返回，因此父 Agent 会继续独立执行。子 Agent 的结果不会再反馈到父 Agent 当前的处理流程中，但它完成时你会收到通知。
</Note>

***

<div id="cancelling-subagents">
  ## 取消子 Agent
</div>

你可以通过以下两种方式取消正在运行的子 Agent：

1. **通过子 Agent 面板：** 打开面板，然后在正在运行的子 Agent 上按 <kbd>x</kbd>。
2. **前台子 Agent：** 按 <kbd>Ctrl</kbd>+<kbd>C</kbd> 或 <kbd>Esc</kbd>，取消当前正在运行的前台子 Agent。

***

<div id="resuming-subagents">
  ## 恢复子 Agent
</div>

已取消、失败或已完成的子 Agent都可以通过新的提示恢复。你可以让 Agent 恢复某个子 Agent，它会从中断处继续。恢复后的子 Agent始终在**前台**运行，因此你可以批准此前被拒绝的任何工具调用。

这在以下情况下尤其有用：

* 后台子 Agent因某个必需工具被拒绝而失败——可在前台恢复它，以授予所需权限。
* 某个子 Agent已完成，但你希望它根据其发现继续执行额外的后续工作。
* 某个子 Agent被过早取消，而你希望它继续执行。

***

<div id="nesting-depth">
  ## 嵌套深度
</div>

默认情况下，子 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）— 无法生成（已达深度上限）
```

<Warning>
  嵌套子 Agent 可能会显著增加成本。每增加一层嵌套，都会生成额外的 Agent，并带有各自的上下文窗口和推理调用。请谨慎使用此功能。
</Warning>

***

<div id="custom-subagents">
  ## 自定义子 Agent
</div>

<Warning>
  自定义子 Agent 是**实验性**功能。其格式、行为和配置选项可能会在后续版本中发生变化。
</Warning>

除了内置的 `subagent_explore` 和 `subagent_general` Profile 外，你还可以定义自己的自定义子 Agent Profile。自定义子 Agent 可让你创建专用工作单元，并为其设置各自的系统提示、工具限制、模型覆盖和权限，以适配工作流程中的特定任务。

<div id="creating-a-custom-subagent">
  ### 创建自定义子 Agent
</div>

自定义子 Agent 通过在 `agents/` 下的具名目录中放置 `AGENT.md` 文件来定义。目录名称将作为该 Profile 的标识符。

<Tabs>
  <Tab title="项目级">
    ```text theme={null}
    .devin/agents/
    └── reviewer/
        └── AGENT.md
    ```

    也支持：

    ```text theme={null}
    .agents/agents/
    └── reviewer/
        └── AGENT.md
    ```
  </Tab>

  <Tab title="全局">
    ```text theme={null}
    # Linux/macOS
    ~/.config/devin/agents/
    └── reviewer/
        └── AGENT.md

    # Windows
    %APPDATA%\devin\agents\
    └── reviewer\
        └── AGENT.md
    ```
  </Tab>
</Tabs>

<div id="agentmd-format">
  ### AGENT.md 格式
</div>

`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.
```

<div id="frontmatter-fields">
  ### Frontmatter 字段
</div>

| 字段              | 类型      | 默认值          | 描述                                                              |
| --------------- | ------- | ------------ | --------------------------------------------------------------- |
| `name`          | string  | 目录名          | 该 Profile 的标识符 (不得与内置 Profile 冲突)                               |
| `description`   | string  | 无            | 在选择 Profile 时向 Agent 显示                                         |
| `model`         | string  | 默认子 Agent 模型 | 覆盖该子 Agent 使用的模型                                                |
| `allowed-tools` | 列表      | 所有工具         | 限制该子 Agent 可使用的工具。不能授予 `ask_user_question`，因为子 Agent 始终无法使用该工具。 |
| `permissions`   | object  | 继承           | 权限覆盖 (`allow`、`deny`、`ask`)                                     |
| `max-nesting`   | integer | 无            | 覆盖最大嵌套深度，使该子 Agent 能够生成自己的子 Agent                               |

<div id="how-custom-subagents-are-used">
  ### 自定义子 Agent 的使用方式
</div>

定义完成后，自定义子 Agent 的 Profile 会与内置 Profile 一起显示。Agent 会看到每个可用 Profile 的说明，并在创建子 Agent 时选择最合适的一个。你也可以要求 Agent 按名称使用特定的 Profile (例如：“使用 reviewer 子 Agent 审查这段代码”) 。

如果自定义子 Agent 的 Profile 名称与内置 Profile 名称冲突 (例如 `subagent_explore`、`subagent_general`) ，则会跳过该 Profile 并显示警告。

<div id="importing-from-other-tools">
  ### 从其他工具导入
</div>

自定义子 Agent 也可以从 Claude Code 的 Agent 格式中导入：

| 来源                    | 文件匹配模式                             |
| --------------------- | ---------------------------------- |
| `.claude/agents/*.md` | 每个 `.md` 文件都会成为一个子 Agent 的 Profile |

<Note>
  Claude Code 的 Agent 文件在 `frontmatter` 中使用 `tools`，而不是 `allowed-tools`。这两种格式都会被自动支持。
</Note>

<div id="examples">
  ### 示例
</div>

<div id="read-only-research-agent">
  #### 只读调研 Agent
</div>

```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.
```

<div id="test-runner-agent">
  #### 测试执行 Agent
</div>

```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
- 针对失败的修复建议
```