---
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="/zh-Hant/docs/gemini-cli/official/04-agents-skills/45-remote-agents" />
  <Card title="啟用 Skill" description="回看 Skill 和 Subagent 的職責差異。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="任務規劃" description="複雜任務委託前，先用 planning 明確職責和驗證。" href="/zh-Hant/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)
