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