📝 Formato Markdown + YAML
Cada subagent = arquivo .md com frontmatter YAML; corpo do markdown é o system prompt. Familiar para quem usa Claude Code.
📊 Frontmatter
- name (lowercase, hyphens, underscores)
- description (curto)
- kind: local (default) ou remote
- tools: array com wildcards
- model: override
- temperature: 0.0-2.0
- max_turns (default 30)
- timeout_mins (default 10)
@ @nome para forçar uso
Prefixar com @subagent_name força uso explícito sem deixar o main agent escolher. Bom para debug.
✓ Auto-delegation
- ✓Main agent escolhe
- ✓Mais rápido em fluxo normal
- ✓Bom para uso geral
- ✓Reduz fricção
✗ Auto-delegation
- ✗Pode atrapalhar reproduzir bug
- ✗Não-determinístico
- ✗Difícil de testar
⚡ Paralelismo em Gemini
Gemini suporta vários subagents (ou várias instâncias) em paralelo. Padrão 'tool exposto ao agente principal' + paralelismo.
📌 Vantagens
Reduz wall-clock real.
- •Pesquisas paralelas
- •Mesmo subagent N vezes
- •Cada um com prompt diferente
- •Main agent coleta resultados
⚠️ Sem nesting
Subagent não pode invocar outro subagent (recursion protection).
🛠️ Built-ins prontos
Antes de criar subagent novo, veja se um built-in já resolve. Reduz manutenção.
📊 Built-ins disponíveis
- codebase_investigator — exploração de código
- cli_help — doc de CLIs
- generalist — task pesada genérica
- browser_agent (experimental) — interação web
🌎 Remote subagents
Subagents podem rodar remotamente (kind: remote). Útil para isolamento ou recursos diferentes.
📌 Casos para remote
Quando vale a pena.
- •Work pesado em CI
- •Privacidade local
- •Recursos especiais (GPU)
- •Compliance
💡 Observabilidade
Remote merece observabilidade extra — você não vê tudo no terminal.
🚧 Limitações principais
Subagent não pode invocar outro subagent (recursion protection). Tools restritos por allowlist. Modelagem hierárquica não funciona.
📌 Pense flat
Main agent como orquestrador.
- •Flat > nested
- •Tools whitelisted no frontmatter
- •Isolamento total de contexto
- •Main agent coordena
📌 Resumo do Módulo
Próximo módulo:
5.3 — Padrão portátil