Indice

1. Para Quem e Este Guia de Migracao

Como apresentado no artigo de lancamento do Claude Opus 4.7, o 4.7 e o sucessor direto do 4.6. Porem, no nivel da API ha varios breaking changes aplicados ao mesmo tempo, e trocar apenas o nome do modelo pode resultar em 400 Bad Request.

Este artigo e voltado a:

  • Desenvolvedores que chamam claude-opus-4-6 via Anthropic API / SDK
  • Times que usam Claude via Bedrock / Vertex AI
  • Quem parou em Opus 4.5 ou 4.1 e quer saltar direto para o 4.7
  • Quem usa extended thinking (thinking: enabled) ou temperature em producao

Usamos como fonte primaria o guia oficial de migracao da Anthropic e organizamos os pontos em que os desenvolvedores costumam travar. Para informacoes oficiais, veja o guia de migracao em platform.claude.com.

Visao geral do guia de migracao do Claude Opus 4.7

2. Resumo em 3 Linhas -- Pegue o Essencial

Para quem esta sem tempo, o TL;DR:

  1. Trocar o nome do modelo: claude-opus-4-6 -> claude-opus-4-7 (e atualizar a versao do SDK)
  2. Tres breaking changes principais: fim do extended thinking enabled (vira adaptive + effort); remocao de temperature/top_p/top_k; novo tokenizador (ate 1,35x mais tokens no mesmo texto)
  3. O que voce ganha em troca: melhor desempenho em coding, 1M de contexto no preco padrao e novo nivel de esforco xhigh

Detalhes a partir do proximo capitulo.

3. Atualizar o Nome do Modelo

Primeira acao: simples. So trocar o identificador do modelo.

# Antes
model = "claude-opus-4-6"

# Depois
model = "claude-opus-4-7"

Se voce mantem o modelo em variavel de ambiente ou arquivo de configuracao, reflita em um unico lugar -- vai facilitar a proxima migracao tambem.

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

Porem, o detalhe desta migracao e que trocar so o nome geralmente nao basta. Veja os breaking changes a seguir.

4. Breaking Change 1: Extended Thinking Removido -> Adaptive

No Opus 4.6, para ativar o extended thinking voce usava thinking: {type: "enabled", budget_tokens: N}. No 4.7, esse formato retorna erro 400.

Agora usa-se o "adaptive thinking", em que o modelo ajusta sozinho a quantidade de pensamento. E ainda: o padrao no 4.7 e thinking OFF; omitir o campo thinking significa rodar sem pensar. Para ter o raciocinio profundo de antes, e preciso opt-in explicito.

Antes (4.6) / Depois (4.7)

# Antes: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# Depois: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Antes: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// Depois: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

Pontos importantes

  • Nao precisa mais controlar "quanto pensar" via budget_tokens
  • Agora voce indica "com que seriedade pensar" via output_config.effort
  • Sem o campo thinking, o modelo responde sem pensar (comportamento diferente do 4.6)

5. Breaking Change 2: Parametros de Sampling Removidos

Passar temperature, top_p ou top_k com valor diferente do padrao retorna erro 400. E a postura da Anthropic: "controle o comportamento via prompt".

# Antes
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# Depois
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k removidos completamente
    messages=[...],
)

Quem usava temperature=0.2 para "saida estavel" passa a escrever no prompt algo como "responda a mesma pergunta da forma mais consistente possivel", ou combina com structured outputs (JSON schema).

Quem usava temperature=1.2 para "mais criativo" agora adiciona instrucoes de tom no prompt, do tipo "use metaforas e expressoes inesperadas".

6. Breaking Change 3: Thinking Oculto por Padrao

No 4.6, ao ativar thinking, por padrao chegava um "thinking resumido (summarized)" no stream. Muitos apps exibiam isso como "pensando..." na UI.

No 4.7, isso mudou silenciosamente: o bloco thinking existe, mas o campo thinking volta vazio. Para receber o conteudo, e preciso opt-in explicito.

Sintoma

O indicador "pensando..." da UI fica girando sem parar e demora absurdamente ate a resposta comecar. Quando o usuario reclama "travou?", geralmente e esse caso.

Como resolver

# Para enviar o resumo do thinking a UI, como no 4.6
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # explicite isto
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

Se for processamento no backend e a UI nao mostra thinking, sem problema deixar o display sem definir.

7. Breaking Change 4: Novo Tokenizador (~1,35x)

O Opus 4.7 usa um novo tokenizador. Ele contribui para o ganho de qualidade, mas o numero de tokens no mesmo texto cresce 1,0 a 1,35x em relacao ao 4.6.

O que isso causa:

  • Processos com max_tokens no limite podem ser truncados
  • Estimativas de tokens no cliente (tipo tiktoken) usadas em cobranca e checagem de tamanho ficam imprecisas
  • O resultado de /v1/messages/count_tokens difere entre 4.6 e 4.7
  • Mesmo prompt passa a ter custo e latencia um pouco maiores

Como resolver

# Antes: buffer de saida de 16k baseado no 4.6
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# Depois: 1,35x de folga como referencia
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ~= 21600 -> arredondado para cima
    messages=[...],
)

Alem disso, no 4.7 a janela de 1M de contexto e disponivel no preco padrao da API (sem adicional). Sim, o consumo de tokens sobe, mas em troca voce tem margem para "jogar tudo dentro" com mais liberdade.

8. Breaking Change 5: Prefill Removido

Breaking change que veio do 4.6. O prefill de mensagem assistant -- inserir no fim do messages algo como {role: "assistant", content: "```json"} para forcar a resposta a comecar de JSON -- volta com erro 400.

# Antes: prefill para forcar saida em JSON
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "Me retorne dados do usuario em JSON"},
        {"role": "assistant", "content": "```json\n{"},  # prefill
    ],
)

# Depois: usar structured outputs
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "Me retorne dados do usuario em JSON"},
    ],
)

Alternativas ao prefill sao tres:

  1. Structured outputs (output_config.format) -- restringir formato com JSON schema
  2. Prompt de sistema dizendo "retorne apenas JSON, sem markdown ou introducao"
  3. Tool use -- receber como chamada de funcao (os argumentos ja chegam como JSON estruturado)
Os 5 breaking changes do Opus 4.7 -- Antes / Depois

9. Como Escolher o Effort (xhigh Novo)

Os valores aceitos em output_config.effort sao 5. No 4.7 chega o novo xhigh.

effortPosicionamentoUsos principais
maxPensar sem limiteBenchmarks e problemas dificeis -- cuidado com overthinking e retorno decrescente
xhigh (novo)Otimo para coding / agentesPadrao para Claude Code e agentes autonomos
highEquilibradoPiso para tarefas intelectualmente exigentes
mediumFoco em custoAceita alguma perda de qualidade para priorizar preco e velocidade
lowTarefas curtas e repetitivasClassificar, formatar, resumir -- quando latencia e prioridade

Quem vinha definindo budget_tokens na mao no 4.6 agora apenas escolhe o effort no 4.7. Heuristicas uteis:

  • Agente de coding (tipo Claude Code): comece em xhigh
  • Chat de Q&A / resposta de RAG: high e seguro
  • Workers leves de tagging, extracao de JSON, classificacao: medium ou low
  • max so em casos pontuais, quando precisa aprofundar sem olhar o custo

10. Lidando com as Mudancas de Comportamento

Mesmo com a API compativel, a maneira do modelo responder a prompts mudou em relacao ao 4.6. Quem migra sem saber disso costuma ouvir dos usuarios "ficou meio seco".

10.1 Comprimento da resposta se adapta a tarefa

O 4.7 ajusta o comprimento conforme a complexidade. Nao ha mais "sempre 3 paragrafos" por padrao. Na pratica, remova primeiro os prompts de controle de tamanho existentes e veja o comportamento.

10.2 Interpretacao mais literal

Mais visivel com effort baixo. "De forma sucinta" vira resposta realmente sucinta; "me cite 3" nao adiciona um quarto item. Util, mas aquele "ler nas entrelinhas" do 4.6 diminuiu.

10.3 Tom mais direto

Frases de validacao ("otima pergunta!"), emojis decorativos e saudacoes no inicio diminuem. Para manter um tom amigavel, deixe isso explicito no prompt de sistema.

10.4 Progresso embutido no tracking do agente

Se em uso de agente voce montou andaimes para o modelo escrever "estou fazendo isso" ou "estou fazendo aquilo", saiba que o 4.7 emite esses updates nativamente -- da para simplificar a scaffolding.

10.5 Sub-agentes e tool calls mais comedidos

Por padrao o modelo dispara menos sub-agentes e usa menos tools. Quando consegue resolver no raciocinio, resolve sem ferramenta. Atualize suas expectativas no design do agente.

10.6 Salvaguardas de ciberseguranca em tempo real

Mesmo trabalho ofensivo legitimo (red team, PoC de vulnerabilidade) pode ser recusado conforme o contexto. Se seguranca e seu uso em producao, inscreva-se no Cyber Verification Program da Anthropic.

10.7 Suporte a imagens em alta resolucao

Imagens ate 2576px ja sao processadas direto. Porem, cada imagem em HD consome cerca de 3x mais tokens. Em cargas pesadas de imagem, opte por (a) redistribuir max_tokens ou (b) reduzir a imagem antes de enviar.

Daqui para a frente, itens que "funcionam mesmo sem, mas vale fazer":

  1. Reavaliar max_tokens: com o novo tokenizador, a saida tambem cresce. Re-teste com valores 1,2 a 1,35x maiores que os atuais
  2. Auditar a estimativa de tokens no cliente: se voce calcula cobranca e tamanho por conta propria, migre para a API count_tokens ou reajuste o coeficiente
  3. Introduzir task_budgets (beta): para agentes. Inclua o header task-budgets-2026-03-13, com minimo de 20k. Lembre que e limite consultivo, nao hard cap
  4. Definir max_tokens >= 64k: ao usar xhigh/max, recomenda-se total (thinking + saida) de 64k ou mais
  5. Downsampling de imagens: se alta resolucao nao e necessaria, reduza antes de enviar para economizar tokens e custo

11.1 Exemplo minimo de task_budgets (SDK oficial em Python)

Como task_budgets esta em beta, use o endpoint client.beta.messages.create e passe o argumento betas explicitamente. E diferente dos recursos ja em GA.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

Pontos-chave:

  • Minimo 20.000 tokens. Valores menores sao rejeitados
  • max_tokens e hard cap por requisicao (nao visivel ao modelo); task_budget e limite consultivo do loop todo do agente (o modelo reconhece a contagem regressiva)
  • Para restringir custo com rigor: max_tokens. Para equilibrar qualidade e eficiencia: task_budget
  • Em trabalho aberto onde qualidade > velocidade, nao defina task_budget -- ele tende a cortar curto demais

12. Migrando Direto de Opus 4.5/4.1

Se pular o 4.6 e ir direto de 4.5 / 4.1 para o 4.7, alem do acima voce precisa:

  • Remover parametros de sampling: quem vinha do Claude 3.x geralmente usa temperature. Remover totalmente
  • Limpar beta headers: effort-2025-11-24, fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14 etc. ja foram incorporados ao core -- podem ser removidos
  • Trocar o endpoint: onde chamava client.beta.messages.create, passe para client.messages.create
  • Migrar output_format -> output_config.format: a chave mudou de nome
  • Parsing de argumentos de tool: desde o 4.6, o comportamento de escape de JSON mudou em alguns casos. Nao faca parsing manual de string; use JSON.parse / json.loads de verdade

Para novidades do Opus 4.7 propriamente, veja tambem o artigo anterior: Claude Opus 4.7: novidades, benchmarks e preco.

13. Checklist Completo de Migracao

Checklist de migracao para Opus 4.7

Para voce imprimir e distribuir no time:

13.1 Obrigatorio (sem isso, da erro 400 ou comportamento errado)

  • [ ] Atualizar o nome do modelo: claude-opus-4-6 -> claude-opus-4-7
  • [ ] Remover temperature / top_p / top_k
  • [ ] Substituir thinking: {type: "enabled", budget_tokens: N} por {type: "adaptive"} + output_config.effort
  • [ ] Remover prefill de assistant e migrar para structured outputs / prompt de sistema
  • [ ] Se a UI exibe thinking, definir thinking.display: "summarized" explicitamente

13.2 Tuning (otimizacao de custo e qualidade)

  • [ ] Re-benchmark de custo e latencia com o novo tokenizador
  • [ ] Ajustar max_tokens multiplicando por ~1,35
  • [ ] Re-testar a logica de estimativa de tokens no cliente
  • [ ] Se usar imagens, redistribuir tokens para contar o HD
  • [ ] Se usa xhigh/max, definir max_tokens >= 64k
  • [ ] Para agentes, considerar task_budgets (beta)

13.3 Revisao de prompts e operacao

  • [ ] Validar comprimento adaptado, interpretacao literal e mudanca de tom em prompts reais
  • [ ] Remover prompts de controle de tamanho e refazer a baseline
  • [ ] Para uso em seguranca, inscrever-se no Cyber Verification Program
  • [ ] Simplificar scaffoldings do agente (updates de progresso etc.)
  • [ ] Vindo de 4.5 ou anterior: remover beta headers e migrar para client.messages.create

14. Ferramentas Automaticas de Migracao

Se voce usa Claude Code, a skill Claude API oferecida pela Anthropic automatiza a parte mecanica do rewrite. Basta chamar a skill dentro do Claude Code com uma instrucao como:

/claude-api migrate

Migre todo o projeto de Claude Opus 4.6 para 4.7.
- Trocar o nome do modelo
- Remover temperature / top_p / top_k
- Substituir thinking: enabled por adaptive + effort: high
- Se houver prefill, substituir por structured outputs

A skill varre o repositorio, identifica arquivos que importam o SDK anthropic e propoe as mudancas. Mas ajuste fino de prompts e re-medicao de benchmarks nao da para automatizar -- feche com o checklist.

FAQ

P. So trocar o nome do modelo funciona?

Se seu codigo nao usa temperature, top_p, top_k, thinking: {type: "enabled"} nem prefill, funciona. Mesmo assim, o novo tokenizador pode truncar a saida no meio; vale revisar o max_tokens uma vez.

P. Se eu nao definir o campo thinking, o 4.7 nao pensa?

Isso mesmo, no 4.7 thinking vem OFF por padrao. E igual ao "OFF padrao" que havia no 4.6, mas a mudanca de comportamento vindo do adaptive so aparece se voce fizer opt-in. Para ativar, use thinking: {type: "adaptive"} e defina a intensidade em output_config.effort.

P. Se eu remover temperature, vou ter a mesma saida toda vez?

Nao. O Claude continua gerando respostas de forma probabilistica, entao o mesmo prompt pode variar um pouco. Para consistencia forte, use (a) structured outputs (JSON schema) para fixar o formato, (b) instrucoes no prompt como "para a mesma entrada, produza a mesma saida" e "mantenha a ordem dos itens".

P. task_budgets e hard cap?

Nao. E um "limite consultivo" para o modelo -- nao ha garantia de que a execucao fique dentro. Para cortar custo de verdade, combine com max_tokens e logica de timeout/interrupcao do seu lado. Uso em beta requer o header task-budgets-2026-03-13.

P. O comportamento via Claude Code e via API direta e o mesmo?

A especificacao da API e a mesma. Mas o Claude Code costuma ter defaults recomendados (ex.: xhigh como padrao em coding) e skills que definem task_budgets por tras. Se sentir diferenca entre um e outro, logue o JSON de request em ambos e compare -- e o caminho mais rapido para achar a divergencia.

P. App com muitas imagens estourou o consumo de tokens. Como lidar?

(1) Reduzir para menos de 2576px antes de enviar, (2) juntar varias imagens em um "contact sheet", (3) fazer OCR da imagem no cliente e mandar so o texto. So use resolucao maxima onde e realmente necessaria (imagem medica, desenho tecnico) e aumente max_tokens com esse trafego em mente.

P. Uso via Bedrock / Vertex AI -- os passos sao os mesmos?

As mudancas de parametros sao iguais. O ID do modelo (ex.: anthropic.claude-opus-4-7 no Bedrock) e a data de disponibilidade seguem o anuncio de cada nuvem. Ja a estrutura de thinking e output_config e a mesma em qualquer plataforma.

P. Ate onde da para confiar na ferramenta automatica de migracao?

A skill Claude API (/claude-api migrate) e otima para a parte mecanica: troca do nome do modelo, remocao de sampling, reescrita do extended thinking. Ja tom de prompt, controle de tamanho e re-avaliacao de benchmarks dependem de decisao humana. Depois da rodada automatica, passe pelo checklist deste artigo linha a linha.

Este artigo foi elaborado com base no guia oficial de migracao do Claude Opus 4.7 da Anthropic (abril de 2026). Como a especificacao da API pode mudar, confira a documentacao oficial antes de colocar em producao.