Como rodar os subagentes do Claude Code em outro modelo: configuração e medições ao delegar ao Sonnet e ao Haiku

Você quer manter a sessão principal do Claude Code no Opus 5, com o esforço (effort) alto. Mas rodar nesse mesmo modelo tarefas como tradução ou conferir uma pilha de arquivos parece desperdício. A dúvida, então, é: dá para rodar só os subagentes no Sonnet ou no Haiku?

Resposta direta: dá. O modelo do subagente é decidido separadamente do da sessão principal, e você pode trocá-lo pelo modelo indicado na chamada, pelo model do arquivo de definição ou por uma variável de ambiente. O esforço também pode ter um valor diferente para cada subagente.

Neste artigo, organizo o comportamento descrito na documentação oficial em 15 de setembro de 2026 e, em seguida, mostro o que aconteceu quando iniciei subagentes em outros modelos e conferi nos logs de conversa. Entreguei a mesma tradução ao Opus 5, ao Sonnet 5 e ao Haiku 4.5, duas vezes para cada um, e comparei tempo, custo e qualidade da tradução.

1. O que dá para fazer: rodar em outro modelo e com outro esforço

O subagente é um ajudante com contexto próprio, que o Claude Code inicia para delegar parte de uma tarefa. Ele não compartilha o histórico da conversa com a sessão principal e, ao terminar, devolve só o resultado (a diferença em relação aos Agent Teams é tratada em Subagents vs Agent Teams no Claude Code: qual usar).

Para os subagentes, a documentação oficial diz que você pode definir separadamente estes dois itens.

Ou seja, uma combinação como "sessão principal no Opus 5 com esforço high, tradutor no Sonnet 5 com esforço medium" pode ser montada tal como está, dentro do comportamento oficial. Para entender o que o esforço significa, veja Configuração de esforço do Claude Code: o guia do controle deslizante.

Fonte: documentação oficial do Claude Code, "Create custom subagents" (Supported frontmatter fields), idem, "Model configuration" (prioridade do esforço)

2. A ordem em que o modelo é decidido

Como mostra a figura do início, o modelo do subagente é o primeiro que se aplica nesta ordem: "o modelo indicado na chamada" → "o model do arquivo de definição" → "a variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL" → "o modelo da sessão principal". Vale prestar atenção em três pontos.

O primeiro é que a ordem muda conforme a versão. Antes da v2.1.251, a variável de ambiente ficava no topo e sobrescrevia até o modelo indicado na chamada e o model do arquivo de definição (incluindo inherit). Se você escreveu model: sonnet na definição e não surtiu efeito, confira primeiro a versão e as variáveis de ambiente.

O segundo é que existe uma configuração à parte para forçar tudo a um único modelo. Só com a variável de ambiente, os subagentes cujo arquivo de definição tem model não obedecem. Para forçar todos, além de CLAUDE_CODE_SUBAGENT_MODEL, defina CLAUDE_CODE_SUBAGENT_MODEL_FORCE como 1 (v2.1.257 ou posterior).

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Ao forçar, o model dos arquivos de definição é ignorado, inclusive nos nativos Explore e Plan, e o Claude também deixa de poder indicar um modelo ao chamar um subagente. Há duas exceções, que continuam no modelo da sessão principal: o fork, que herda a conversa inteira, e uma skill com model: inherit executada em um subagente.

O terceiro é que o destino de sonnet e opus depende do provedor. Mesmo escrevendo o mesmo sonnet, o modelo que você recebe muda assim.

Fonte: documentação oficial do Claude Code, "Model configuration" (tabela em 15 de setembro de 2026). Para fixar uma versão específica, escreva o ID de modelo completo em vez de um alias

Se as configurações gerenciadas da sua organização restringem os modelos disponíveis (availableModels), o model dos subagentes e a variável de ambiente também ficam sujeitos a essa restrição.

3. Como configurar (5 formas)

① Escrever no arquivo de definição (para papéis que devem usar sempre o mesmo modelo)

O jeito mais prático é criar um arquivo de definição para cada papel. Coloque-o em .claude/agents/ do projeto para compartilhá-lo pelo git, ou em ~/.claude/agents/ para usá-lo em todos os seus projetos.

---
name: translator
description: Traduz artigos em japonês para o inglês. Use quando pedirem uma tradução
model: sonnet
effort: medium
tools: Read, Write, Grep
---
Você é tradutor de artigos técnicos. Não altere as tags nem os atributos HTML;
transforme em inglês natural apenas o texto visível.

Quando há várias definições com o mesmo nome, a prioridade é: configurações gerenciadas da organização, --agents na inicialização, projeto, usuário e plugins, nessa ordem. Desde a v2.1.198, o comando /agents não abre mais a tela de criação, então peça ao Claude para criar a definição ou escreva o arquivo diretamente.

② Indicar na chamada (para mudar só naquele momento)

Mesmo sem criar uma definição, o Claude pode anexar um modelo ao iniciar um subagente. Se você pedir na conversa algo como "deixe essa verificação com um subagente Haiku", o Claude inicia o subagente com esse modelo anexado à chamada. Essa indicação tem prioridade sobre o arquivo de definição. Para confirmar se ela foi mesmo anexada, use o método da seção 5.

③ Definir um padrão com variável de ambiente (para mudar de uma vez tudo o que não tem modelo indicado)

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
  }
}

Colocada em env no settings.json, ela vale para os subagentes cujo modelo não foi decidido de outra forma. Segundo a documentação oficial, os membros de Agent Teams e os agentes de workflows também são afetados. Mas, só com isso, o modelo dos nativos Explore e Plan não muda (seção 4).

④ Passar com --agents na inicialização (só para aquela sessão)

claude --agents '{
  "translator": {
    "description": "Translates Japanese articles into English.",
    "prompt": "You are a technical translator. Keep all HTML tags.",
    "model": "sonnet",
    "effort": "medium"
  }
}'

Nada é salvo em arquivo; a definição vale só enquanto durar aquela sessão.

⑤ Definir no Claude Agent SDK

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "translator": AgentDefinition(
            description="Translates Japanese articles into English.",
            prompt="You are a technical translator. Keep all HTML tags.",
            tools=["Read", "Write"],
            model="sonnet",
            effort="medium",
        ),
    }
)

No AgentDefinition do SDK, o model também aceita um alias, inherit ou um ID de modelo completo. Se você não escrever nada, a ordem acima decide. A documentação oficial também observa que o Opus 5 delega trabalho a subagentes com mais facilidade que os modelos anteriores e indica configurações para limitar quantos rodam ao mesmo tempo (20 por padrão) e quanto podem gastar.

Fonte: documentação oficial do Claude Code, "Create custom subagents" (locais e prioridade, --agents, a mudança no /agents, variáveis de ambiente), idem, "Model configuration" (a quem se aplica CLAUDE_CODE_SUBAGENT_MODEL), idem, "Subagents in the SDK" (AgentDefinition, configurações de limite)

4. Em que modelo rodam os subagentes nativos

Mesmo sem definir nada, o Claude Code já vem com alguns subagentes. O modelo de cada um é o seguinte.

Fonte: documentação oficial do Claude Code, "Create custom subagents" (Built-in subagents, em 15 de setembro de 2026)

Desde a v2.1.198, o Explore deixou de rodar sempre no Haiku. Ele herda o modelo da sessão principal, com o Opus como teto na Claude API. Se a sessão principal estiver em um modelo superior, como o Fable, o Explore roda no Opus; se estiver no Sonnet ou no Haiku, roda nesse modelo. Para voltar ao Haiku, a documentação oficial sugere criar um arquivo de definição chamado Explore com model: haiku (porque a sua definição tem prioridade sobre a nativa de mesmo nome).

Para mudar o modelo do Explore e do Plan pela variável de ambiente, é preciso definir também o CLAUDE_CODE_SUBAGENT_MODEL_FORCE da seção 2.

5. Medição 1: ele rodou mesmo naquele modelo?

Conferi se tudo funciona como documentado no meu próprio ambiente (sessão principal no Opus 5, esforço high). Entreguei ao general-purpose nativo a mesma tarefa pequena, "ler o README e resumir em três linhas", em três variações: com o modelo indicado como sonnet, como haiku e sem indicação.

Há duas formas de conferir. Enquanto ele está rodando, a lista do /tasks mostra o modelo do subagente (conforme a documentação oficial). Depois que termina, veja o message.model de cada resposta nos arquivos agent-*.jsonl da pasta subagents/ dos seus logs de conversa locais. Onde ficam os logs e como lê-los está explicado em detalhe em Claude Code: como ver o uso por sessão e descobrir qual sessão está consumindo o seu plano.

Fonte: minhas próprias medições (15 de setembro de 2026, app desktop no Windows. Todas as respostas de cada subagente registraram o mesmo modelo)

Cada um rodou no modelo indicado, e o que ficou sem indicação herdou o da sessão principal. No arquivo agent-*.meta.json da mesma pasta, o valor indicado, como "model": "sonnet", só fica registrado quando houve indicação.

6. Medição 2: dezenas de milhares de tokens só para iniciar

Os mesmos logs revelaram mais uma coisa. O subagente lê dezenas de milhares de tokens já na primeira resposta, antes de começar qualquer trabalho. O motivo é que o prompt de sistema dele, as definições das ferramentas, o CLAUDE.md e outros itens entram logo de início.

Fonte: minhas próprias medições (15 de setembro de 2026. Contagem de tokens da primeira resposta de cada subagente. Todas as escritas foram no cache de 5 minutos)

Esses números mostram três coisas.

A primeira é que subagentes do mesmo modelo leem do cache o trecho inicial que têm em comum. Na segunda inicialização, cerca de 45 mil tokens do Sonnet 5 viraram leitura de cache (0,1 vez o preço de entrada). A documentação oficial também diz que requisições no mesmo modelo com o mesmo início compartilham o cache. Por outro lado, o cache é separado para cada modelo, e os subagentes também não leem o cache da sessão principal (porque o conteúdo do início é diferente).

A segunda é que, mesmo na assinatura, o cache dos subagentes expira em 5 minutos. Segundo a documentação oficial, ao usar dentro de um plano, a conversa principal tem 1 hora, mas os subagentes têm 5 minutos. Se você esperar mais de 5 minutos para iniciar o próximo subagente, ele começa de novo pela escrita. Para passar a 1 hora, defina a configuração subagentPromptCacheTtl ou a variável de ambiente CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL como 1h (v2.1.242 ou posterior). Para decidir por subagente, escreva cacheTtl em experimental no arquivo de definição (v2.1.248 ou posterior; enquanto uma assinatura estiver usando créditos de uso adicionais (usage credits), o 1h definido ali é ignorado). No cache de 1 hora, a escrita custa 2 vezes o preço de entrada (no de 5 minutos, 1,25 vez).

A terceira é que, para o mesmo texto, o Haiku 4.5 mostra menos tokens. Segundo a página oficial de preços, os modelos a partir do Claude 4.7 usam um novo tokenizador, que conta cerca de 30% mais tokens para o mesmo texto. O Haiku 4.5 é de uma geração anterior ao 4.7 e não aparece entre os modelos que usam o novo tokenizador. Comparando os números da tabela diretamente, o Haiku parece mais leve do que realmente é.

Se você dividir tarefas pequenas entre muitos subagentes, esse "custo só de iniciar" se soma para cada um. Entregando o trabalho a um modelo mais barato, não só o trabalho em si fica mais barato, mas essa parte também.

Fonte: documentação oficial do Claude Code, "How Claude Code uses prompt caching" (cache por modelo, subagentes e cache, validade do cache), Claude Platform Docs, "Pricing" (tokenizador, multiplicadores do cache), documentação oficial do Claude Code, "Create custom subagents" (omitClaudeMd)

7. Medição 3: a mesma tradução, duas vezes em cada um de 3 modelos

Testei na prática a dúvida do início, "rebaixar só a tradução". Escolhi uma seção da versão em japonês de um artigo deste site (6.265 caracteres de HTML, com uma tabela, cards de números e trechos de código) e entreguei a cada modelo a tarefa de traduzi-la para o inglês sem alterar a estrutura das tags, duas vezes por modelo e com as mesmas instruções, 6 execuções no total. O Opus 5 e o Sonnet 5 usaram o esforço high, herdado da sessão principal (o Haiku 4.5 não suporta esforço).

Fonte: minhas próprias medições (15 de setembro de 2026. Custo pelo preço de tabela, calculado multiplicando as contagens de tokens dos logs de conversa pelos preços oficiais. A saída não está incluída; veja a nota abaixo)

A coluna de custo deixa a saída de fora porque as contagens de tokens de saída nos logs não eram confiáveis. Houve um caso em que uma resposta que gravou em arquivo uma tradução de cerca de 8.800 caracteres ficou registrada com 18 tokens de saída. O preço de saída por milhão de tokens é US$ 25 no Opus 5, US$ 10 no Sonnet 5 e US$ 5 no Haiku 4.5, e todas as traduções em inglês ficaram com cerca de 8.500 a 8.900 caracteres.

Conferi a qualidade da tradução eu mesmo, comparando frase por frase com o original em japonês.

• Em nenhuma das 6 execuções encontrei erro de sentido. Números, tabelas e links internos também foram preservados corretamente. É um texto cheio de números e listas, do tipo mais fácil de traduzir
• As diferenças apareceram na fluidez e na uniformidade dos termos. Na 1ª execução, o Haiku 4.5 misturou "my" e "the author's" para a primeira pessoa e, na 2ª, produziu uma ordem de palavras rígida, como "G from 9th rises to 6th". O Sonnet 5 escreveu um inglês natural, mas grafou "subagent" como "Sub-agent" na 1ª execução e "Subagent" na 2ª, variando de uma vez para outra. O Opus 5 manteve os termos uniformes nas duas
• O mais lento foi o mais barato, o Haiku 4.5. No Sonnet 5, as duas execuções tiveram uma diferença de quase o dobro no tempo. Como foram poucas execuções, trate a ordem de velocidade apenas como referência

8. O efeito no custo e nos limites de uso

O quanto se ganha ao rebaixar o modelo dos subagentes depende de você pagar por uso na API ou usar uma assinatura como Pro ou Max.

API com pagamento por uso: a proporção dos preços vale diretamente

Fonte: Claude Platform Docs, "Pricing" (por milhão de tokens, em 15 de setembro de 2026. O preço de lançamento do Sonnet 5 passou a ser o preço definitivo)

O preço por token do Sonnet 5 é dois quintos do Opus 5, e o do Haiku 4.5, um quinto. Nas medições da seção 7, a parte de entrada e cache do Sonnet 5 ficou em cerca de metade da do Opus 5, e a do Haiku 4.5 em cerca de um quinto. O Haiku 4.5 fica perto da proporção dos preços, enquanto o Sonnet 5 sai acima de dois quintos, porque o número de respostas e a quantidade lida em cada uma variaram conforme o modelo (o Sonnet 5 fez 4 e 6 respostas, e o Opus 5, 4 nas duas; o Haiku 4.5 também usa outro tokenizador).

Assinatura: há limites que não voltam ao trocar de modelo

No Pro e no Max, o limite da sessão e o limite semanal são comuns a todos os modelos. Depois de esgotá-los, trocar de modelo com /model não libera o uso. Além desses, existem limites por família de modelos, como o "limite do Opus" e o "limite do Sonnet", e só quando você atinge um deles dá para continuar trocando para um modelo de fora daquela família.

🟡 Não foi divulgado quanto os limites do plano duram a mais quando os subagentes rodam no Sonnet ou no Haiku. A proporção dos preços da API serve de referência, mas nada diz que os limites são consumidos nessa mesma proporção. Para ver quais subagentes consomem mais, use o detalhamento do plano no /usage (a parcela por skill, subagente, plugin e servidor MCP).

Fonte: documentação oficial do Claude Code, "Error reference" (You've hit your session limit: limites comuns a todos os modelos e limites por família de modelos), idem, "Manage costs effectively" (detalhamento do plano no /usage)

9. Que trabalho passar para um modelo mais barato

Como referência, a documentação oficial aponta que o Sonnet dá conta bem da maioria das tarefas de programação e custa menos que o Opus, que o Opus deve ficar reservado para decisões de arquitetura complexas e raciocínio em várias etapas, e que, para tarefas simples de subagentes, se deve indicar model: haiku no arquivo de definição. Para os membros de Agent Teams, o Sonnet também é o recomendado.

A partir disso, com base nas medições da seção 7 e na forma como opero este site, listo três critérios para decidir.

Na dúvida, o caminho seguro é entregar só uma das suas tarefas habituais ao modelo mais barato e comparar o resultado lado a lado com o do modelo atual. Basta mudar uma linha, o model do arquivo de definição, para testar, e se não servir dá para voltar na hora. Se o que você quer dividir é o modelo da sessão principal, e não o de um subagente, usando o Opus só para planejar e o Sonnet para implementar, o opusplan faz isso (veja O que é o opusplan do Claude Code?).

FAQ

P1. Se eu trocar o /model da sessão principal no meio da conversa, os subagentes também mudam?
Os subagentes cujo modelo é decidido pela indicação na chamada, pelo model do arquivo de definição (exceto inherit) ou pela variável de ambiente não mudam. Os que não têm nenhum desses, e os que têm inherit no arquivo de definição, seguem o modelo da sessão principal. Note que, ao trocar o modelo da sessão principal, o cache da sessão principal precisa ser recriado.

P2. Dá para baixar só o esforço, mantendo o modelo?
Dá. Escreva algo como effort: medium no arquivo de definição, e esse esforço vale só enquanto aquele subagente estiver rodando. Mas, se a variável de ambiente CLAUDE_CODE_EFFORT_LEVEL estiver definida, ela tem prioridade.

P3. No Amazon Bedrock, escrevendo model: sonnet, qual modelo eu recebo?
Segundo a documentação oficial em 15 de setembro de 2026, o Sonnet 4.5. Na Anthropic API é o Sonnet 5, então o mesmo arquivo de definição dá resultados diferentes conforme o provedor. Para fixar a versão, escreva o ID de modelo completo.

P4. Vale a pena deixar o cache dos subagentes em 1 hora?
Depende do seu uso. Se você inicia muitas vezes o mesmo tipo de subagente com intervalos de mais de 5 minutos, isso reduz as escritas repetidas. Por outro lado, no cache de 1 hora a escrita custa 2 vezes o preço de entrada (no de 5 minutos, 1,25 vez), então, se você só roda subagentes em sequência num intervalo curto, o de 5 minutos sai mais barato. As configurações para o cache de 1 hora e suas condições estão na seção 6.

P5. Indiquei um modelo, mas parece que não está fazendo efeito.
Confira nesta ordem: ① se o CLAUDE_CODE_SUBAGENT_MODEL_FORCE não está ativado (ele faz ignorar o que está no arquivo de definição); ② se você não está em uma versão anterior à v2.1.251 com a variável de ambiente definida; ③ se as configurações gerenciadas da organização permitem aquele modelo. Para saber em que modelo ele realmente rodou, use o /tasks enquanto estiver rodando, ou o message.model dos logs de conversa depois que terminar.

Fontes

• Claude Code Docs — Create custom subagents (campos do arquivo de definição, a ordem de decisão do modelo e as diferenças entre versões, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagentes nativos, locais e prioridade, --agents, omitClaudeMd, conferência pelo /tasks)
• Claude Code Docs — Model configuration (destino dos aliases, a quem se aplica CLAUDE_CODE_SUBAGENT_MODEL, prioridade do esforço, availableModels)
• Claude Code Docs — How Claude Code uses prompt caching (cache por modelo, validade do cache dos subagentes, subagentPromptCacheTtl e a definição pela variável de ambiente e pelo arquivo de definição)
• Claude Code Docs — Manage costs effectively (referência para escolher o modelo, a recomendação do Sonnet para os membros de Agent Teams, detalhamento do /usage)
• Claude Code Docs — Error reference (limites comuns a todos os modelos e limites por família de modelos)
• Claude Code Docs — Subagents in the SDK (model e effort no AgentDefinition, o Opus 5 e as configurações de limite)
• Claude Code Docs — Orchestrate teams of Claude Code sessions (como é decidido o modelo dos membros de Agent Teams)
• Claude Platform Docs — Pricing (preços por modelo, multiplicadores do cache, tokenizador)

Artigos relacionados

• Subagents vs Agent Teams no Claude Code: qual usar — o que é um subagente
• Configuração de esforço do Claude Code: o guia do controle deslizante — o que significa o esforço
• Claude Code: como ver o uso por sessão e descobrir qual sessão está consumindo o seu plano — como ler os logs de conversa
• Claude Code: o que está consumindo o seu contexto? Como medir e o que cortar primeiro — por que o CLAUDE.md é lido toda vez
• O que é o opusplan do Claude Code? — deixar a sessão principal no Opus só durante o modo de planejamento
• Dicas para Economizar Tokens no Claude Code e o Que Acontece ao Atingir o Limite — onde mais dá para cortar