---
title: "Subagents"
description: "Gemini CLI Subagents 的用途：专门角色、任务分工、模型配置、启用禁用和适用边界。"
verifiedAt: "2026-05-09"
---

Subagents 是专门角色。它们适合把复杂任务拆给不同职责的 agent，而不是让一个通用 agent 从头包到尾。

> [!NOTE]
> Subagent 适合隔离上下文和职责，不适合把不清楚的任务甩给另一个 agent。主 agent 仍然要负责整合结果和最终判断。

Subagent 和 Skill 的区别是：Skill 是给当前 agent 加载专门流程；Subagent 是把一段任务委托给另一个独立上下文的 specialist。Subagent 有自己的 system prompt、工具集和上下文窗口，完成后把结果回传给主 agent。

官方也支持自定义 agent：项目级可放 `.gemini/agents/*.md`，用户级可放 `~/.gemini/agents/*.md`。这类配置会影响任务委托方式，适合团队明确角色边界后再引入。

## 常用命令

```text
/agents list
/agents reload
/agents enable <agent-name>
/agents disable <agent-name>
/agents config <agent-name>
```

可以显式用 `@agent_name` 强制委托，例如：

```text
@codebase_investigator 分析 AgentRegistry 和 LocalAgentExecutor 的关系。
```

这种写法会给主模型一个强提示，让它优先调用对应 subagent。

## 适合场景

- 代码审查 agent。
- 测试修复 agent。
- 文档整理 agent。
- 安全检查 agent。
- 大项目中分工扫描。
- 大量上下文检索，不想污染主会话。
- 专门工具集和主 agent 不同的任务。

## 不适合场景

- 简单单文件问题。
- 任务目标不清楚。
- 需要统一上下文强一致的操作。
- 需要马上人工判断的高风险操作。

| 需求 | Skill | Subagent |
| --- | --- | --- |
| 给当前 agent 加流程 | 适合 | 不必要 |
| 大量只读扫描 | 可辅助 | 适合 |
| 独立 specialist 角色 | 不适合 | 适合 |
| 需要隔离上下文 | 不适合 | 适合 |
| 需要主 agent 统一执行 | 适合 | 谨慎 |

## 内置 subagents

Gemini CLI 官方文档列出的内置 agent 包括：

- `codebase_investigator`：分析代码库、依赖关系和复杂实现。
- `cli_help`：回答 Gemini CLI 自身命令、配置和文档问题。
- `generalist`：通用型隔离上下文，适合大输出、多步骤、资源密集型任务。
- `browser_agent`：实验性浏览器自动化 agent，默认关闭。

`browser_agent` 的边界要特别谨慎。它可以持久 profile、临时 profile 或连接已有 Chrome；可设置 `allowedDomains`、`maxActionsPerTask`、`confirmSensitiveActions`、`blockFileUploads` 等安全项。涉及账号后台、表单、上传、脚本执行时，不应默认放开。

官方文档还强调 subagent 不能递归调用其他 subagent，这是为了避免委托链失控。主 agent 仍然要负责检查结果、整合冲突、决定是否继续执行。

## 配置入口

Subagent 的启用、禁用、模型和 turn 限制可以在 `settings.json` 的 `agents.overrides` 中覆盖。例如只给 `codebase_investigator` 增加轮数，不影响主 agent：

```json
{
  "agents": {
    "overrides": {
      "codebase_investigator": {
        "runConfig": { "maxTurns": 50 }
      }
    }
  }
}
```

## 验收方式

用一个适合该 agent 的小任务测试，例如让 `codebase_investigator` 只读分析一个模块。验收重点不是“它回答了”，而是它是否真的隔离了上下文、是否只用了允许的工具、回传结果是否能被主 agent 继续执行。

主 agent 不能把 subagent 结果原样当最终答案。它要检查证据、整合冲突、补足验证步骤，并说明哪些结论来自 subagent、哪些是自己再次确认的判断。

安全验收要看工具隔离是否真的生效。给只读分析 agent 的工具集不应包含写文件、shell 发布或高权限 MCP；给 browser agent 的配置要限制域名、文件上传和敏感动作确认。否则 subagent 只是换了一个名字继续拥有过宽权限。

## 接下来去哪

<Cards>
  <Card title="Remote agents" description="需要把 agent 能力放到远端时，继续看 A2A 和远程认证边界。" href="/docs/gemini-cli/official/04-agents-skills/45-remote-agents" />
  <Card title="激活 Skill" description="回看 Skill 和 Subagent 的职责差异。" href="/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="任务规划" description="复杂任务委托前，先用 planning 明确职责和验证。" href="/docs/gemini-cli/official/01-cli-workflow/17-task-planning" />
</Cards>

## 官方来源

- [Gemini CLI subagents](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/subagents.md)
