Quando delegar a especialistas de contexto limpo, quando manter no agente principal, e como configurar certo — checado contra a documentação oficial.
Orquestrar > ExecutarO agente que tenta fazer tudo numa conversa só tem um teto: contexto que incha, tokens que sobem, foco que dispersa.
Subagentes mudam o jogo. O agente principal deixa de executar e vira orquestrador: delega tarefas fechadas a especialistas de contexto limpo, roda o que é independente em paralelo, e recebe de volta só o resultado. Velocidade, economia de tokens e controle — sem inflar a conversa principal. Mas não serve para tudo: o resto desta entrega é quando usar, quando evitar e como configurar certo.
Um subagente é uma sessão paralela com janela de contexto própria — com seu próprio system prompt, suas próprias ferramentas e suas próprias permissões. Pode até rodar num modelo diferente do principal.
O detalhe que muda tudo: o agente pai recebe só a mensagem final do subagente; todas as chamadas e resultados intermediários ficam dentro dele. Exemplo da doc oficial: um subagente pode vasculhar dezenas de arquivos sem entupir a conversa principal — o pai recebe apenas um resumo conciso.
Pense num especialista que você aciona para uma tarefa: ele faz a investigação inteira no contexto dele e te entrega o relatório pronto.
Toda conversa com um agente acumula contexto: arquivos lidos, comandos rodados, respostas longas. Esse acúmulo custa tokens e atrapalha o raciocínio do modelo.
O subagente quebra esse acúmulo: começa do zero, faz o trabalho sujo no contexto dele e devolve só o essencial. A conversa principal segue limpa, focada na decisão — não nos detalhes da execução.
O ganho não é só de contexto — é de tempo. Tarefas que não dependem uma da outra rodam ao mesmo tempo, cada uma na sua sessão isolada, e o orquestrador só costura os resultados no fim.
O orquestrador roda num modelo forte e delega N tarefas independentes a subagentes especialistas. Cada um trabalha em contexto isolado, ao mesmo tempo, e devolve apenas o resultado final. O lote inteiro termina no tempo da tarefa mais lenta — não na soma de todas.
| Use subagente quando | Evite subagente quando | |
|---|---|---|
| Trabalho | Output verboso que você não quer no contexto principal (ex.: explorar dezenas de arquivos). | Pede idas-e-vindas e refinamento iterativo — você ajusta o resultado a cada passo. |
| Contexto | A tarefa é autocontida e devolve um resumo fechado. | As fases compartilham muito contexto entre si (planejar → implementar → testar). |
| Paralelização | Tarefas independentes que rodam ao mesmo tempo — terminam no tempo da mais lenta. | É uma mudança rápida e pontual — não compensa o setup. |
| Governança | Você precisa impor restrições de ferramentas ou permissões a uma tarefa. | Latência importa — o subagente começa do zero e adiciona atraso. |
| Reúso | O padrão se repete e vale virar especialista versionado no git. | Você quer um fluxo reutilizável dentro do próprio contexto — para isso, use Skills. |
Regra de bolso: subagente é para trabalho fechado que devolve um resumo. Se a tarefa pede conversa contínua, mantenha no agente principal.
Como o subagente pode rodar num modelo próprio, você roteia tarefa por tarefa — nem tudo precisa do modelo mais caro. A doc oficial recomenda mandar tarefas para modelos mais rápidos e baratos quando dá; o subagente built-in Explore, por exemplo, roda em Haiku. Exemplo oficial de configuração dinâmica: opus para revisões de alto risco, sonnet para o padrão.
Por que Haiku para subagentes? O Haiku 4.5 é o modelo mais rápido da linha — cerca de 4 a 5x mais rápido que o Sonnet 4.5, a aproximadamente US$ 1 por milhão de tokens de entrada e US$ 5 de saída, com 73,3% no SWE-bench Verified. A Anthropic descreve que ele se destaca em execução paralelizada e subagentes.
Tarefa de exploração ou busca em massa não precisa de Opus — roteie para Haiku e a conta cai.
Duas práticas oficiais para o time:
.claude/agents/ e compartilhe com o time; o padrão fica igual para todos, auditável e evolui por PR.Para validação mais fina, existem o campo permissionMode e os hooks PreToolUse — dá para, por exemplo, permitir apenas comandos SELECT num subagente que toca banco.
Projeto em .claude/agents/ (versione no git p/ o time); usuário em ~/.claude/agents/ (vale em qualquer projeto). Precedência quando há nomes iguais: managed (org) > --agents da sessão > projeto > usuário > plugin.
Campos oficiais: name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, color. Grafia camelCase: disallowedTools e maxTurns, nunca com underscore.
O Claude decide delegar com base no description. Escreva-o bem: frases como "use proactively" encorajam o acionamento proativo.
Aceita sonnet, opus, haiku, fable; ou ID completo (ex.: claude-opus-4-8, claude-sonnet-4-6); ou inherit. Omitido → default inherit (mesmo modelo da conversa principal).
tools é allowlist (omitir herda todas); disallowedTools é denylist. Só-leitura: liste Read, Grep, Glob (sem Edit/Write/Bash).
O campo skills pré-carrega conteúdo no contexto inicial; e o subagente ainda pode invocar Skills durante a execução.
Linguagem natural ("Use the code-reviewer subagent to…"), @-mention (@agent-nome), ou delegação automática. /agents é o comando interativo para criar/gerenciar.
Três embutidos reais: Explore (só-leitura, Haiku, busca/exploração de código), Plan (só-leitura, plan mode), general-purpose (todas as ferramentas, multi-step). Não existe built-in "researcher".
disallowed_tools/max_turns com underscore → o certo é disallowedTools/maxTurns; com underscore falha em silêncio.inherit.claude --agent dispara um worker pontual" → não; faz a sessão INTEIRA assumir aquele agente. Para worker pontual: linguagem natural, @-mention ou delegação automática.tools: readonly" → não existe; read-only = Read, Grep, Glob.memory: none" no frontmatter → só aceita user/project/local ("none" só na UI do /agents).Quando você precisa orquestrar muitos subagentes, a delegação turn-by-turn fica curta. Para isso existe o conceito oficial de Dynamic Workflows: um script JS — escrito pelo próprio Claude — orquestra os subagentes, executado por um runtime em background.
Diferença: na delegação turn-by-turn o Claude orquestra a cada turno, com poucos agentes; no workflow o script segura o loop e o branching, e só a resposta final volta ao contexto. A escala vai de dezenas a centenas de agentes — até 16 concorrentes ao mesmo tempo, com teto de 1.000 por execução. Há também um /deep-research embutido.
Na prática: a maioria dos casos resolve com delegação simples; workflows entram quando o trabalho é grande, repetitivo e ramificado.
Use subagente quando a tarefa é fechada, devolve um resumo e pode rodar isolada — de preferência em paralelo e no modelo mais barato que dê conta.
Mantenha no agente principal o que pede conversa contínua. Para fluxo reutilizável dentro do contexto, use Skills. E sempre: permissões mínimas, frontmatter em camelCase, e os subagentes do projeto versionados no git para o time inteiro herdar o mesmo padrão.
A Teavox pode mapear onde a delegação economiza tokens e ganha velocidade no seu fluxo, montar a biblioteca de subagentes especialistas com permissões enxutas e versionados no git, e deixar o roteamento de modelo (Haiku para o massivo, Opus para o crítico) já configurado. Padrão único, auditável, pronto para o time usar no mesmo dia.
Solicitar diagnóstico