DEV Community

Cover image for Como usar Claude Haiku 5.5 no Claude Code e como modelo de subagente
Lucas
Lucas

Posted on Originally published at apidog.com

Como usar Claude Haiku 5.5 no Claude Code e como modelo de subagente

#agents #ai #claude #llm

Para usar o Claude Haiku 5.5 no Claude Code, atualize para a v2.1.293 ou posterior com claude update. Em seguida, inicie uma sessão com claude --model claude-haiku-5-5 ou altere o modelo em uma sessão existente com /model claude-haiku-5-5. Para a maioria dos fluxos de desenvolvimento, a opção mais econômica é usar o Haiku como subagente para pesquisa, execução de testes, leitura de logs e resumos, enquanto Sonnet 5.5 ou Opus 5.5 lideram tarefas complexas.

Experimente o Apidog hoje

Este guia mostra a configuração, a diferença do apelido haiku entre provedores, níveis de esforço, subagentes, o limite de preço de 100K tokens e cenários em que Sonnet ou Opus continuam sendo a melhor escolha. Para entender o modelo, leia o que é o Claude Haiku 5.5. Se o seu projeto chama APIs, o Apidog pode armazenar os cenários de teste que um subagente Haiku executará.

Claude Haiku 5.5 no Claude Code

Claude Haiku 5.5 no Claude Code: resumo

Configuração Haiku 5.5
Versão mínima v2.1.293 (claude update)
ID do modelo claude-haiku-5-5
Apelido haiku Haiku 5.5 apenas na API da Anthropic
Contexto 1M nativo em todos os planos, sem sufixo [1m]
Compactação automática Cerca de 967K tokens por padrão
Esforço padrão medium (de low a max)
Pensamento Sempre ligado; não pode ser desligado no Claude Code
Preço da API US$0,10/US$0,50 até 100K tokens; US$0,50/US$2,50 acima de 100K
Planos Pro, Max, Team, Enterprise ou chave de API; não Gratuito

Passo 1: atualize o Claude Code

O Haiku 5.5 exige Claude Code v2.1.293 ou posterior. A entrada do changelog informa que ele é “agora o modelo Haiku padrão na API da Anthropic”.

claude update
Enter fullscreen mode Exit fullscreen mode

O Claude Code não está disponível no plano Gratuito. Para usá-lo, você precisa de Pro, Max, Team, Enterprise ou uma chave de API da Anthropic. Usuários gratuitos ainda podem selecionar o Haiku 5.5 nos aplicativos Claude.ai.

Passo 2: selecione o Haiku 5.5 como modelo principal

Inicie uma nova sessão diretamente com o ID completo:

claude --model claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Em uma sessão já aberta, execute:

/model claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Se sua configuração salva usa model: haiku, uma sessão anteriormente associada ao Haiku 4.5 pode ser retomada no Haiku 5.5 — mas isso depende do provedor.

Atenção: o apelido haiku não resolve para Haiku 5.5 em todos os provedores

Provedor haiku resolve para
API da Anthropic Haiku 5.5
Plataforma Claude na AWS Haiku 4.5
Amazon Bedrock Haiku 4.5
Plataforma de Agentes do Google Cloud Haiku 4.5
Microsoft Foundry Haiku 4.5

Em provedores de nuvem, /model haiku e model: haiku em subagentes podem continuar usando Haiku 4.5. Para evitar ambiguidades, fixe o ID específico do provedor:

  • Google Cloud e Claude Platform na AWS: claude-haiku-5-5
  • Microsoft Foundry: nome da implantação
  • Amazon Bedrock: um perfil de inferência, como us.anthropic.claude-haiku-5-5

Outra opção é configurar ANTHROPIC_DEFAULT_HAIKU_MODEL, mostrada no Passo 5.

Passo 3: escolha o nível de esforço

O Haiku 5.5 inclui controle de esforço:

low
medium
high
xhigh
max
Enter fullscreen mode Exit fullscreen mode

No Claude Code, o padrão é medium.

claude --model claude-haiku-5-5 --effort high
Enter fullscreen mode Exit fullscreen mode

Durante uma sessão, altere o nível com:

/effort low
Enter fullscreen mode Exit fullscreen mode

Use esta regra prática:

  • low: buscas curtas, execução de ferramentas e alto volume.
  • medium: trabalho geral e a maioria dos subagentes.
  • high: tarefas agênticas mais longas.
  • xhigh e max: somente se suas avaliações mostrarem ganho suficiente.

O pensamento permanece ativado no Claude Code. Configurações como alwaysThinkingEnabled: false e MAX_THINKING_TOKENS=0 não o desativam. Para reduzir o consumo de tokens de pensamento, diminua o esforço.

Passo 4: use o Haiku 5.5 como subagente

Subagentes são arquivos Markdown com frontmatter YAML. Crie-os em:

.claude/agents/
Enter fullscreen mode Exit fullscreen mode

Para disponibilizá-los apenas no projeto atual, ou em:

~/.claude/agents/
Enter fullscreen mode Exit fullscreen mode

Para disponibilizá-los em todos os projetos.

Os únicos campos obrigatórios são name e description. O campo model aceita sonnet, opus, haiku, fable, um ID completo de modelo ou inherit. Consulte a documentação de subagentes e o guia de subagentes do Claude Code para detalhes de escopo e ferramentas.

Substitua o Explore por um explorador econômico

O subagente integrado Explore usa o modelo da conversa principal. Se você estiver em uma sessão do Opus 5.5, cada busca feita por ele também usará Opus.

Crie um agente chamado Explore para substituí-lo e executar buscas no Haiku:

---
name: Explore
description: Pesquisa rápida e somente leitura na base de código. Use para encontrar arquivos, símbolos e locais de chamada sem editar nada.
tools: Read, Grep, Glob
model: haiku
effort: low
---

Você pesquisa a base de código e relata o que encontra. Retorne os caminhos dos arquivos com números de linha e um breve resumo de cada correspondência. Nunca edite arquivos.
Enter fullscreen mode Exit fullscreen mode

Salve o arquivo como:

.claude/agents/Explore.md
Enter fullscreen mode Exit fullscreen mode

Enquanto ele executa, use /tasks para confirmar o modelo utilizado. Em provedores de nuvem, substitua haiku pelo ID completo adequado.

Forçar todos os subagentes a usar Haiku

Para executar todos os subagentes no Haiku, incluindo o Explore, defina estas variáveis no arquivo de configurações:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}
Enter fullscreen mode Exit fullscreen mode

Usar somente CLAUDE_CODE_SUBAGENT_MODEL define um padrão. Nesse caso, um campo model definido no próprio subagente ainda terá prioridade, e o Explore integrado não será alterado.

Passo 5: direcione tarefas em segundo plano para o Haiku 5.5

A variável ANTHROPIC_DEFAULT_HAIKU_MODEL define o modelo usado por haiku e por tarefas em segundo plano, como resumir sessões anteriores em claude --resume.

A variável antiga ANTHROPIC_SMALL_FAST_MODEL está obsoleta segundo a referência de variáveis de ambiente. Substitua-a se ela ainda existir no seu perfil de shell.

Na API da Anthropic, nenhuma configuração adicional é necessária. Em provedores de nuvem, porém, tarefas em segundo plano podem usar Sonnet ou o modelo principal por padrão. Fixe explicitamente o Haiku 5.5:

# Plataforma de Agentes do Google Cloud
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

# Amazon Bedrock: ID do perfil de inferência
export ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Controle o degrau de preço de 100K tokens

O Claude Code reenvia a conversa como prompt em cada turno. Quando o contexto ultrapassa 100K tokens, o preço do Haiku 5.5 muda de:

US$0,10 / US$0,50 por milhão de tokens de entrada/saída
Enter fullscreen mode Exit fullscreen mode

Para:

US$0,50 / US$2,50 por milhão de tokens de entrada/saída
Enter fullscreen mode Exit fullscreen mode

Isso representa cinco vezes a taxa de prompts menores. Como a documentação não esclarece se tokens em cache contam para esse limite, trate-os como parte do orçamento.

A compactação automática ocorre perto de 967K tokens por padrão, então não espere que ela impeça o aumento de preço. Adote dois hábitos:

  1. Compacte antes do limite. 
   /autocompact 100k
Enter fullscreen mode Exit fullscreen mode

Isso reduz a janela de contexto e aciona a compactação próximo ao limite de preço.

  1. Envie tarefas verbosas para subagentes.

Logs de testes, resultados de busca e saídas longas ficam no contexto próprio do subagente, em vez de poluir a conversa principal.

Mesmo acima de 100K tokens, a taxa de US$0,50/US$2,50 ainda é um quarto da taxa de US$2/US$10 do Sonnet 5.5. Veja a aritmética completa no detalhamento de preços do Haiku 5.5.

Assinantes Max e Team devem observar que créditos mensais da API não cobrem o Claude Code interativo, conforme a documentação de créditos da API.

Quando manter Sonnet 5.5 ou Opus 5.5 como líderes

A Anthropic recomenda Sonnet 5.5 e Opus 5.5 para tarefas complexas de codificação agêntica. No Terminal-Bench 4.0, executado pela Anthropic no Claude Code com esforço máximo, o Haiku 5.5 atingiu 39,2%, enquanto o Sonnet 5.5 atingiu 70,6%.

Esforço Haiku 5.5 Sonnet 5.5
medium 20,3% a US$0,68 28,8% a US$0,68
high 24,8% a US$1,04 43% a US$1,46
max 39,2% a US$2,64 70,6% a US$10,44

Em medium, os dois modelos custam aproximadamente o mesmo por tentativa, mas Sonnet pontua mais alto. Portanto, não trate o Haiku como modelo principal para sessões longas e difíceis de shell ou refatorações complexas.

Em uso de computador, o custo-benefício pode ser diferente: no OSWorld 2.1, Haiku 5.5 em medium obteve 53,3% a US$0,13 por tentativa, enquanto Sonnet 5.5 em low obteve 57,9% a US$0,68.

Consulte o detalhamento dos benchmarks do Haiku 5.5 e o guia do Claude Code para Sonnet 5.5 para mais comparações.

Uma divisão prática é:

  • Sonnet 5.5 ou Opus 5.5: modelo principal.
  • Haiku 5.5: Explore, execução de testes, leitura de logs e busca de documentação.

Exemplo: subagente Haiku para executar testes no Apidog

Execuções de teste são repetitivas e geram bastante saída, o que combina bem com o Haiku. O CLI do Apidog executa cenários salvos pelo terminal, permitindo que o subagente devolva apenas um relatório curto ao modelo principal.

Crie .claude/agents/api-test-runner.md:

---
name: api-test-runner
description: Executa os cenários de teste Apidog do projeto com o CLI do Apidog após a alteração de um endpoint de API, então relata as contagens de aprovação e falha com as solicitações falhas.
tools: Bash, Read
model: haiku
effort: low
---

Execute o comando de teste do CLI do Apidog documentado no README deste repositório para o cenário que cobre o endpoint alterado. Relate as contagens de aprovação e falha.

Para cada falha, forneça o nome da solicitação, o resultado esperado e o resultado real. Não edite código. Não tente novamente uma execução falha mais de uma vez.
Enter fullscreen mode Exit fullscreen mode

A configuração do CLI, incluindo autenticação e comandos de execução, está no guia CLI do Apidog no Claude Code. Baixe o Apidog para criar os cenários que esse subagente executará.

Migre um aplicativo do Haiku 4.5

Se seu aplicativo usa Haiku 4.5 pela API, inicie a migração no Claude Code com:

/claude-api migrate this project to claude-haiku-5-5
Enter fullscreen mode Exit fullscreen mode

Espere incompatibilidades com:

  • budget_tokens de pensamento manual;
  • temperature ou top_p fora do padrão;
  • qualquer uso de top_k;
  • preenchimento automático de mensagens do assistente.

Essas configurações retornam erro 400 no Haiku 5.5. O guia Haiku 5.5 vs Haiku 4.5 lista todas as correções.

Após editar a integração:

  1. Salve as requisições antiga e nova como um par no Apidog.
  2. Armazene ANTHROPIC_API_KEY como variável de ambiente.
  3. Adicione asserções para stop_reason e usage.
  4. Faça o teste falhar se houver refusal ou um salto inesperado de tokens.

Assim, alterações de comportamento chegam ao pipeline de testes antes de chegar à produção.

Perguntas frequentes

O Haiku 5.5 é o modelo padrão no Claude Code?

Não. Ele é o modelo Haiku padrão na API da Anthropic, o que faz o apelido haiku apontar para ele nesse provedor. Para usá-lo como modelo principal, selecione-o com --model ou /model.

Posso usar Haiku 5.5 no Claude Code no plano Gratuito?

Não. O Claude Code exige plano pago ou chave de API. Usuários gratuitos podem escolher Haiku 5.5 no Claude.ai. Veja também como usar o Claude Haiku 5.5 gratuitamente.

Por que model: haiku usa Haiku 4.5?

Você provavelmente está no Bedrock, Google Cloud, Foundry, Claude Platform na AWS ou em uma versão anterior à v2.1.293. Use o ID completo do modelo ou defina ANTHROPIC_DEFAULT_HAIKU_MODEL.

Posso desativar o pensamento para economizar tokens?

Não no Claude Code. Reduza o esforço; low é a configuração mais econômica.

Próximo passo

Execute:

claude update
Enter fullscreen mode Exit fullscreen mode

Depois, adicione o subagente Explore com Haiku e mantenha Sonnet 5.5 ou Opus 5.5 como líder por uma semana. Se seu projeto expõe APIs, adicione o subagente de execução de testes em seguida.

Para integrar o modelo ao seu próprio código, comece pelo guia da API do Haiku 5.5. O Apidog é gratuito para começar e permite criar os testes reais que seus subagentes irão executar.

Top comments (0)