Subagents

Subagents 是專門角色。它們適合把複雜任務拆給不同職責的 agent，而不是讓一個通用 agent 從頭包到尾。

Subagent 和 Skill 的區別是：Skill 是給當前 agent 載入專門流程；Subagent 是把一段任務委託給另一個獨立上下文的 specialist。Subagent 有自己的 system prompt、工具集和上下文視窗，完成後把結果回傳給主 agent。

官方也支援自定義 agent：專案級可放 .gemini/agents/*.md，使用者級可放 ~/.gemini/agents/*.md。這類配置會影響任務委託方式，適合團隊明確角色邊界後再引入。

常用命令

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

可以顯式用 @agent_name 強制委託，例如：

@codebase_investigator 分析 AgentRegistry 和 LocalAgentExecutor 的关系。

這種寫法會給主模型一個強提示，讓它優先呼叫對應 subagent。

適合場景

• 程式碼審查 agent。
• 測試修復 agent。
• 文件整理 agent。
• 安全檢查 agent。
• 大專案中分工掃描。
• 大量上下文檢索，不想汙染主會話。
• 專門工具集和主 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：

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

驗收方式

用一個適合該 agent 的小任務測試，例如讓 codebase_investigator 只讀分析一個模組。驗收重點不是“它回答了”，而是它是否真的隔離了上下文、是否只用了允許的工具、回傳結果是否能被主 agent 繼續執行。

主 agent 不能把 subagent 結果原樣當最終答案。它要檢查證據、整合衝突、補足驗證步驟，並說明哪些結論來自 subagent、哪些是自己再次確認的判斷。

安全驗收要看工具隔離是否真的生效。給只讀分析 agent 的工具集不應包含寫檔案、shell 釋出或高許可權 MCP；給 browser agent 的配置要限制域名、檔案上傳和敏感動作確認。否則 subagent 只是換了一個名字繼續擁有過寬許可權。

接下來去哪

官方來源

• Gemini CLI subagents