Gemini CLI Subagents

O que são subagents no Gemini CLI?

Subagents são agentes especialistas que operam ao lado da sua sessão principal do Gemini CLI. Quando você dá ao Gemini CLI uma tarefa ampla ou complexa, o agente principal pode delegar subtarefas específicas ao subagent mais relevante, atuando como orquestrador.

Cada subagent executa em isolamento com sua própria janela de contexto separada, instruções de sistema personalizadas e um conjunto curado de ferramentas. Seu trabalho — possivelmente envolvendo muitas chamadas de ferramentas, buscas ou execuções de testes — é consolidado em uma única resposta retornada à sessão principal.

Principais Recursos

• Delegação a especialistas: O Gemini CLI pode dividir uma grande tarefa em subtarefas e roteá-las para subagents direcionados.
• Ambientes de execução isolados: Cada subagent executa com sua própria janela de contexto, instruções de sistema e ferramentas curadas, ajudando a manter a sessão principal sem sobrecarga.
• Consolidação de ferramentas e contexto: Etapas intermediárias realizadas por subagents são consolidadas em uma única resposta para o agente principal.
• Execução paralela de subagents: O Gemini CLI suporta a execução simultânea de múltiplos subagents (diferentes subagents ou múltiplas instâncias do mesmo subagent).
• Definições personalizadas de subagents: Você pode criar seus próprios subagents usando arquivos Markdown simples com YAML frontmatter.

Como Usar Subagents no Gemini CLI

1. Crie uma definição de subagent usando um arquivo Markdown (.md) com YAML frontmatter que especifica campos como name, description, tools e model (como mostrado no exemplo fornecido para um “frontend-specialist”).
2. Adicione a definição em um dos locais suportados:
   • Para fluxos pessoais: ~/.gemini/agents
   • Para compartilhamento em equipe/projeto: .gemini/agents
   • Para extensões: inclua arquivos Markdown de definição de agente no diretório agents/ da extensão.
3. Use o Gemini CLI como de costume: forneça sua tarefa geral na sessão principal do Gemini CLI; o Gemini CLI pode então despachar subagents para lidar com subtarefas relevantes.
4. (Se necessário) execute trabalho em paralelo: quando tarefas se dividem naturalmente em múltiplos fluxos independentes de pesquisa/refatoração/testes, o Gemini CLI pode despachar múltiplos subagents ao mesmo tempo.

Casos de Uso

• Pesquisa em múltiplos tópicos: Delegue threads de pesquisa separados a diferentes subagents e execute-os em paralelo, recebendo saídas consolidadas de volta na sessão principal.
• Refatoração de múltiplos componentes: Divida uma refatoração em tarefas distintas de nível de componente e deixe subagents especialistas trabalharem em cada área sem encher a janela de contexto principal.
• Exploração e análise de código: Use subagents especialistas para investigar seções de código e retornar resumos ou resultados formatados, enquanto o agente principal mantém a tomada de decisões e síntese final.
• Testes e validação: Descarregue sequências de etapas relacionadas a testes (que podem envolver muitas chamadas de ferramentas) para subagents, mantendo a sessão principal responsiva.
• Automação específica de workflow com personas personalizadas: Crie um agente especialista reutilizável (ex.: uma persona frontend/UI-UX) para impor abordagem consistente e uso de ferramentas em workflows de projeto repetidos.

FAQ

Como os subagents diferem da sessão principal do Gemini CLI?
Subagents são agentes especialistas que executam ao lado da sua sessão principal. Eles operam em isolamento com sua própria janela de contexto, instruções de sistema e ferramentas, e retornam resultados consolidados.

O Gemini CLI pode executar mais de um subagent ao mesmo tempo?
Sim. O Gemini CLI suporta execução paralela, incluindo o spawn de múltiplos subagents ou múltiplas instâncias do mesmo subagent simultaneamente.

Como configurar subagents personalizados?
Subagents personalizados são definidos com arquivos Markdown (.md) que incluem YAML frontmatter. Você pode colocá-los em ~/.gemini/agents para uso pessoal, .gemini/agents para compartilhamento em nível de projeto ou no diretório agents/ de uma extensão.

O que acontece com o trabalho intermediário realizado pelos subagents?
Subagents podem executar muitas chamadas de ferramentas, buscas em arquivos ou execuções de testes, mas sua execução é consolidada em uma única resposta de volta ao agente principal.

Os subagents têm suas próprias ferramentas e instruções de sistema?
Sim. Cada subagent executa com seu próprio conjunto curado de ferramentas e instruções de sistema personalizadas, distintas da sessão principal.

Alternativas

• Prompting de agente único sem delegação: Você pode pedir ao Gemini CLI para lidar com tudo em um único contexto. Isso evita a configuração de agentes personalizados, mas pode exigir prompts longos ou sofrer com o crescimento do contexto.
• Divisão manual de fluxos de trabalho: Você pode executar prompts separados e independentes para cada subtarefa e depois mesclar os resultados manualmente. Isso pode simular delegação, mas você gerencia a orquestração e consolidação.
• Frameworks multi-agente de propósito geral: Abordagens multi-agente baseadas em ferramentas ou frameworks também podem rotear tarefas para papéis especializados, embora o fluxo de trabalho e a configuração sejam diferentes das definições de subagentes e do modelo de isolamento do Gemini CLI.
• Papéis de agente baseados em chat (não subagentes): Se o seu caso de uso for principalmente assistência baseada em papéis em vez de execução paralela de ferramentas isoladas, prompts de papéis mais simples podem ser suficientes, com menos controle sobre isolamento e saídas de subtrabalhos consolidadas.