---
title: Guia de migração para o Claude Opus 5.5
url: https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide
description: Mude para o Claude Opus 5.5 a partir de modelos Opus anteriores ou do Claude Sonnet 5 com este guia de migração. As orientações para habilitar o Claude Opus 5.5 incluem configurações de requisição que retornam erros, blocos de pensamento em todas as respostas e uma checklist para cada modelo de origem.
---
Este guia aborda a migração de código da [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages). Se você usa o [Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview), nenhuma alteração além da atualização do nome do modelo é necessária.
**Automatize sua migração com a skill Claude API.** No Claude Code, execute `/claude-api migrate` para invocar a [skill Claude API](https://platform.claude.com/docs/pt-BR/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model) incluída. Ela funciona com qualquer modelo Claude atual como destino:
Deixe o Claude Code migrar seu código para você
```text
/claude-api migrate este projeto para claude-opus-5-5
```
A skill aplica a troca do ID do modelo e, conforme necessário, as alterações incompatíveis de parâmetros, a substituição de prefill e a calibração de esforço para o seu modelo de destino em toda a sua base de código, e então produz uma lista de verificação de itens para conferir manualmente. Ela pede que você confirme o escopo da migração (todo o diretório de trabalho, um subdiretório ou uma lista específica de arquivos) antes de editar qualquer arquivo. A skill também detecta clientes do Amazon Bedrock e do Claude Platform on AWS e ajusta os formatos de ID de modelo e as alterações de recursos para essas plataformas.
Esta página lista as alterações de código para migrar para o Claude Opus 5.5 a partir do [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), do [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), do [Claude Opus 4.7](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-47), do [Claude Opus 4.6 e modelos Opus anteriores](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) ou do [Claude Sonnet 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-sonnet-5). Todo leitor precisa de [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements) e de [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response). Em seguida, vá para a seção do seu modelo atual: a primeira frase dela indica as outras seções que se aplicam a você. O [checklist de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist) lista todas as alterações por modelo de origem.
O Claude Opus 5.5 custa menos que o Claude Opus 5 ($4 / $20 USD por milhão de tokens de entrada / saída, em comparação com $5 / $25; consulte [preços do Claude](https://platform.claude.com/docs/pt-BR/about-claude/pricing)). Para o suporte a recursos, consulte [O que há de novo no Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#feature-support). Para diferenças de comportamento e padrões de prompting específicos do modelo, consulte [Prompting do Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5).
## O que toda requisição ao Claude Opus 5.5 deve atender
Seja qual for o modelo de origem, uma requisição para `claude-opus-5-5` deve atender aos itens a seguir. Quando um item diz que uma configuração é rejeitada, a API retorna um erro 400.
* **ID do modelo:** Use `claude-opus-5-5`, um ID de modelo fixo sem sufixo de data. No Amazon Bedrock, na Claude Platform on AWS, no Google Cloud e no Microsoft Foundry, use o ID de modelo dessa plataforma; consulte [Disponibilidade](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#availability).
* **Pensamento:** Não envie nenhum campo `thinking`, ou envie `thinking: {"type": "adaptive"}`, que é equivalente: o [adaptive thinking](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) (pensamento adaptativo) está sempre ativado. `thinking: {"type": "disabled"}` e orçamentos manuais de pensamento (`thinking: {"type": "enabled", "budget_tokens": N}`) são rejeitados. Consulte o [antes e depois para o pensamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-cant-be-disabled).
* **Esforço:** Controle a profundidade do pensamento com o [parâmetro "effort" (esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort), o único parâmetro de requisição que a controla. Todos os cinco níveis (`low`, `medium`, `high`, `xhigh`, `max`) são suportados, e o padrão é `medium`. Consulte [Níveis de esforço recomendados para o Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5).
* **Escolha de ferramenta:** Use `tool_choice` `{"type": "auto"}` (o padrão) ou `{"type": "none"}`. Forçar uma chamada de ferramenta com `{"type": "any"}` ou `{"type": "tool", "name": "..."}` é rejeitado. Consulte o [antes e depois para a escolha de ferramenta](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#forced-tool-use).
* **Parâmetros de amostragem:** Omita `temperature`, `top_p` e `top_k`, ou deixe-os em seus valores padrão: qualquer outro valor é rejeitado. Use prompts para orientar o comportamento do modelo.
* **Prefill:** Não termine `messages` com um turno do assistente pré-preenchido ("prefill"): isso é rejeitado. Use [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) ou instruções no prompt do sistema. No Amazon Bedrock, as saídas estruturadas não estão disponíveis para o Claude Opus 5.5, então use instruções no prompt do sistema nessa plataforma.
* **Uso de computador:** Na Claude API e no Google Cloud, declare o "computer use" (uso de computador) como o toolset `computer_toolset_20260801`; a ferramenta anterior `computer_20251124` é rejeitada nessas plataformas. Consulte a [mudança incompatível do uso de computador](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#computer-use-toolset).
* **Janela de contexto:** Nenhum cabeçalho beta de "context window" (janela de contexto) é necessário. A [janela de contexto de 1M tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/context-windows) é o padrão, e um cabeçalho enviado para modelos mais antigos não tem efeito.
A requisição a seguir atende a todos os itens da lista: o esforço está definido e não há campo `thinking`. As abas de SDK que imprimem texto o selecionam pelo tipo de bloco, porque os blocos `thinking` vêm primeiro.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures"
}],
"output_config": {
"effort": "medium"
}
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--output-config '{effort: medium}' \
--message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content: "Analyze the trade-offs between microservices and monolithic architectures"
}
],
output_config: {
effort: "medium"
}
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
Content = "Analyze the trade-offs between microservices and monolithic architectures"
}
],
OutputConfig = new OutputConfig
{
Effort = Effort.Medium
}
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
import com.anthropic.models.messages.OutputConfig;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-5-5',
outputConfig: ['effort' => 'medium'],
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{ role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
],
output_config: {
effort: "medium"
}
)
message.content.each do |block|
puts block.text if block.type == :text
end
```
## Lidar com o pensamento em todas as respostas
O pensamento é executado em toda requisição ao Claude Opus 5.5, então toda resposta pode começar com blocos `thinking`, e `max_tokens` abrange o pensamento mais o texto. Se o seu código já é executado com o pensamento ativado, os itens 1 a 3 provavelmente já estão implementados: verifique os itens 4 e 5. Se ele era executado sem pensamento, em qualquer modelo anterior, cada item é uma alteração.
1. **`max_tokens` abrange o pensamento mais o texto:** No Claude Opus 4.8 e em modelos Opus anteriores, requisições sem um campo `thinking` são executadas sem pensamento. O Claude Opus 5 e o Claude Sonnet 5 aceitam `thinking: {"type": "disabled"}`. No Claude Opus 5.5, toda requisição é executada com [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking). `max_tokens` continua sendo um limite rígido para a saída total, pensamento mais texto da resposta, então revise-o para cargas de trabalho que eram executadas sem pensamento. Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado a você, então essa carga de trabalho pode produzir mais tokens de saída por requisição. Consulte [Controle de custo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#cost-control). Para gastar menos tokens com pensamento, reduza o nível de [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort). Se você executa com esforço `xhigh` ou `max`, defina um `max_tokens` grande para que o modelo tenha espaço para pensar e agir; comece com 64k tokens e ajuste a partir daí. Se seus prompts foram ajustados para execução sem pensamento, consulte [Prompts escritos para pensamento desativado](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled).
2. **As respostas começam com blocos de pensamento:** Uma resposta pode começar com um ou mais blocos `thinking` antes do primeiro bloco `text`. Código que lê a resposta por posição, como `content[0].text` ou um manipulador de stream que trata o primeiro evento `content_block_start` como texto, falha nessas respostas. Em vez disso, selecione os blocos de conteúdo pelo campo `type`: leia `text` dos blocos cujo `type` é `"text"` e ramifique com base no tipo de bloco ao lidar com eventos de stream.
3. **Retorne os blocos de pensamento sem modificações em loops de uso de ferramentas:** Se você executa um loop de "tool use" (uso de ferramentas), passe os blocos `thinking` de cada resposta do assistente de volta para a API completos e sem modificações ao retornar resultados de ferramentas, incluindo blocos cujo campo `thinking` está vazio. Reenvie a mensagem do assistente como foi recebida, em vez de filtrar seus blocos de conteúdo por tipo ou reconstruí-la: a API rejeita blocos de pensamento editados, reordenados ou parcialmente descartados com um erro 400. Consulte [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks).
4. **O texto do pensamento é omitido por padrão:** `thinking.display` tem como padrão `"omitted"`, então os blocos `thinking` chegam com um campo `thinking` vazio junto com sua `signature`. Trate o campo `thinking` apenas como texto de exibição. Para receber resumos legíveis, defina `thinking.display` como `"summarized"`:
```python Python
thinking = {
"type": "adaptive",
"display": "summarized",
}
```
```typescript TypeScript
const thinking = {
type: "adaptive",
display: "summarized"
};
```
```csharp C#
var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };
```
```go Go
thinking := anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{
Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,
},
}
```
```java Java
ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()
.display(ThinkingConfigAdaptive.Display.SUMMARIZED)
.build();
```
```php PHP
$thinking = ['type' => 'adaptive', 'display' => 'summarized'];
```
```ruby Ruby
thinking = {
type: "adaptive",
display: "summarized"
}
```
Se o seu produto transmite o raciocínio aos usuários via streaming, o padrão aparece como uma longa pausa antes do início da saída; defina `display: "summarized"` para restaurar o progresso visível durante o pensamento. Consulte [Controlando a exibição do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display).
5. **O texto entre chamadas de ferramentas chega em blocos de pensamento:** As notas curtas que o modelo escreve entre chamadas de ferramentas retornam como blocos `thinking`, que ficam vazios na exibição padrão. Consulte [O texto entre chamadas de ferramentas é retornado em blocos de pensamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#text-between-tool-calls).
## Checklist de migração por modelo de origem
Percorra os grupos de cima para baixo e pare após aquele que nomeia seu modelo atual: todos os itens até esse ponto se aplicam a você. Se você está no Claude Opus 5, o primeiro grupo é a lista completa. Se você está no Claude Sonnet 5, aplique o primeiro grupo e o último.
### Todos os modelos de origem
* Atualize o ID do modelo para `claude-opus-5-5`.
* Remova `thinking: {"type": "disabled"}` e `thinking: {"type": "enabled", ...}`; em vez disso, escolha um nível de esforço.
* Defina `effort` explicitamente: o padrão é `medium`, enquanto o do Claude Opus 5 é `high`.
* Substitua os tipos de `tool_choice` `any` e `tool` por `auto` mais uso estrito de ferramentas ou saídas estruturadas, ou apenas por `auto` no Amazon Bedrock.
* Se você usa a ferramenta de uso de computador na Claude API ou no Google Cloud, declare `computer_toolset_20260801` (sem cabeçalho beta) em vez de `computer_20251124` e atualize seu loop de agente para o toolset. No Amazon Bedrock, mantenha `computer_20251124`; verifique a seção [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#compatibility) da ferramenta de uso de computador para outras plataformas.
* Se um roteador ou fallback puder mover uma conversa do Claude Opus 5.5 para outro modelo, espere que esse modelo seja executado sem os blocos de pensamento do Claude Opus 5.5 (o Claude Fable 5.1 e o Claude Mythos 5.1 na Claude API são a exceção e os mantêm). O próprio Claude Opus 5.5 lê o pensamento do Claude Opus 5, de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos.
* Leia os blocos de conteúdo por `type` e passe os blocos `thinking` de volta sem modificações em loops de uso de ferramentas.
* Se sua interface renderiza texto entre chamadas de ferramentas, defina `display: "updates"` (beta) ou `"summarized"` e renderize os blocos `thinking` não vazios.
* Se seu código edita turnos anteriores, o prompt `system` ou `tools` no meio da conversa, siga [Pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking).
* Trate `stop_reason: "refusal"` e configure o fallback.
* Restabeleça a linha de base de custo e latência no nível de esforço escolhido.
* Se seu código desativava o pensamento, revise `max_tokens`, que abrange o pensamento mais o texto da resposta; com esforço `xhigh` ou `max`, comece com 64k. Consulte [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response).
### Claude Opus 4.8 ou anterior
* Revise as cargas de trabalho que eram executadas sem um campo `thinking`: no Claude Opus 5.5 elas são executadas com pensamento, e o pensamento não pode ser desativado. Revise `max_tokens`, que continua sendo um limite rígido para a saída total (pensamento mais texto da resposta), e reduza `effort` onde você quiser menos pensamento. Tokens de pensamento são cobrados como tokens de saída, então essas cargas de trabalho podem produzir mais tokens de saída por requisição.
* Verifique se qualquer código que analisa o campo `thinking` o trata apenas como texto de exibição. Defina `display: "summarized"` para receber resumos legíveis.
* Revise os prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais podem criar entradas de cache.
* Se sua organização tem um compromisso de [Priority Tier](https://platform.claude.com/docs/pt-BR/api/service-tiers#supported-models), planeje a capacidade separadamente: o Priority Tier não é suportado no Claude Opus 5.5.
* Se você executa com esforço `xhigh` ou `max`, aumente `max_tokens` para pelo menos 64k como ponto de partida.
* Para cargas de trabalho agênticas, considere [orçamentos de tarefa](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets) (beta) e alterações de ferramentas no meio da conversa (beta).
### Claude Opus 4.7 ou anterior
* Execute uma nova varredura de [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) em suas próprias avaliações em vez de manter uma configuração ajustada para um modelo anterior.
* Remova qualquer cabeçalho beta de janela de contexto.
* Se você reconstrói o histórico da conversa para atualizar instruções, considere mudar para uma mensagem de sistema no meio da conversa para preservar os acertos de cache de prompt.
* Verifique se o seu tratamento de motivos de parada lê `stop_details` em recusas.
* Se você quiser o modo rápido, que o Claude Opus 4.7 rejeita, defina `speed: "fast"` nas suas requisições à Claude API. O Claude Opus 5.5 não precisa de cabeçalho beta.
### Claude Opus 4.6 ou anterior
* Remova `temperature`, `top_p` e `top_k` dos payloads de requisição.
* Substitua `thinking: {"type": "enabled", "budget_tokens": N}` por `thinking: {"type": "adaptive"}` mais o [parâmetro effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort), ou remova o campo `thinking` inteiramente; o pensamento adaptativo está sempre ativado.
* Se sua UI exibe conteúdo de pensamento, opte explicitamente pela sumarização do pensamento.
* Refaça o benchmark de custo e latência de ponta a ponta com a tokenização atualizada.
* Reajuste `max_tokens` para levar em conta a tokenização atualizada, incluindo os gatilhos de compactação.
* Teste novamente quaisquer estimativas de contagem de tokens do lado do cliente.
* Se sua aplicação envia imagens, refaça o orçamento para o [suporte a imagens de alta resolução](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) (até aproximadamente 3x mais tokens de imagem por imagem em resolução total). Reduza a resolução antes de enviar se você não precisar da fidelidade adicional.
* Se você consome coordenadas de apontamento ou de caixas delimitadoras do modelo, remova qualquer conversão de fator de escala; as coordenadas são 1:1 com os pixels reais da imagem no Claude Opus 4.7 e em modelos posteriores.
* Revise as [mudanças de comportamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#behavior-changes) que começaram no Claude Opus 4.7.
* Se seu produto realiza trabalho legítimo de segurança, inscreva-se no [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) para ter acesso a restrições menores sobre conteúdo cibernético.
### Claude Opus 4.5 ou anterior
* Remova quaisquer prefills de mensagem do assistente; o Claude Opus 4.6 já os rejeita.
* Verifique se a análise do JSON de chamadas de ferramentas usa um parser JSON padrão.
* Migre de `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) para `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`): o pensamento adaptativo e o esforço não precisam de namespace beta.
* Remova o cabeçalho beta `effort-2025-11-24` (o parâmetro effort não o exige).
* Remova o cabeçalho beta `fine-grained-tool-streaming-2025-05-14`.
* Remova o cabeçalho beta `interleaved-thinking-2025-05-14` (o pensamento adaptativo ativa o pensamento intercalado automaticamente).
* Migre `output_format` para `output_config.format` (se aplicável).
### Claude 4.1 ou anterior
* Atualize as versões das ferramentas (`text_editor_20250728`, `code_execution_20260521`).
* Trate o motivo de parada `refusal`.
* Trate o motivo de parada `model_context_window_exceeded`.
* Verifique o tratamento de parâmetros de string de ferramentas quanto a quebras de linha finais.
* Remova cabeçalhos beta legados (`token-efficient-tools-2025-02-19`, `output-128k-2025-02-19`).
* Revise e atualize os prompts seguindo as [melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).
### Somente Claude Sonnet 5
* Se você reconstrói o histórico da conversa para atualizar instruções, considere mudar para uma mensagem de sistema no meio da conversa para preservar os acertos de cache de prompt.
* Revise os prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais podem criar entradas de cache.
## Migrando para o Claude Opus 5.5 a partir do Claude Opus 5
Primeiro, percorra [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements) e [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response). Todo modelo de origem precisa das alterações desta seção. Elas são as configurações de requisição que o Claude Opus 5.5 rejeita e as mudanças de resposta que vêm com ele. O checklist desta seção é o primeiro grupo do [checklist de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist).
### Atualize o nome do seu modelo
```python
model = "claude-opus-5" # Before
model = "claude-opus-5-5" # After
```
`claude-opus-5-5` é um ID de modelo fixo sem sufixo de data, o mesmo esquema de `claude-opus-5`. No Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry, use o ID de modelo dessa plataforma; consulte [Disponibilidade](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#availability).
### Mudanças incompatíveis
Cada mudança é explicada em [O que há de novo no Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#breaking-changes); esta seção apresenta a alteração de código para cada uma.
#### O pensamento não pode ser desativado
`thinking: {"type": "disabled"}` e `thinking: {"type": "enabled", "budget_tokens": N}` retornam um erro 400 (`"thinking.type.disabled" is not supported for this model.` ou `"thinking.type.enabled" is not supported for this model.`). Remova o campo `thinking` e escolha um nível de ["effort" (esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort); onde você desativava o "thinking" (pensamento) para economizar tokens, use um nível mais baixo. As respostas então começam com blocos `thinking`, portanto selecione os blocos de conteúdo por `type` e devolva os blocos `thinking` sem modificações junto com os resultados de ferramentas. Consulte [O pensamento não pode ser desativado](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#thinking-cant-be-disabled).
Antes. O Claude Opus 5 aceita esta requisição, e o Claude Opus 5.5 a rejeita com um erro 400:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 16000,
"thinking": {"type": "disabled"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 16000 \
--thinking '{type: disabled}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
thinking: { type: "disabled" },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Thinking = new ThinkingConfigDisabled(),
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000L)
.thinking(ThinkingConfigDisabled.builder().build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 16000,
thinking: ThinkingConfigDisabled::with(),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 16000,
thinking: Anthropic::ThinkingConfigDisabled.new,
messages: [{ role: "user", content: "..." }]
)
```
Depois:
```bash cURL
# o pensamento está sempre ativo; o controle é feito pelo effort
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"output_config": {"effort": "low"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
# o pensamento está sempre ativo; o controle é feito pelo effort
ant messages create \
--model claude-opus-5-5 \
--max-tokens 16000 \
--output-config '{effort: low}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
output_config={"effort": "low"}, # thinking is always on; effort is the control
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
output_config: { effort: "low" }, // thinking is always on; effort is the control
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
OutputConfig = new() { Effort = Effort.Low }, // thinking is always on; effort is the control
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow, // thinking is always on; effort is the control
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
// o pensamento está sempre ativo; o controle é feito pelo effort
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 16000,
// o pensamento está sempre ativo; o controle é feito pelo effort
outputConfig: OutputConfig::with(effort: Effort::LOW),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
# o pensamento está sempre ativo; o controle é feito pelo effort
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
```
#### O uso forçado de ferramentas não é suportado
Os tipos de `tool_choice` `any` e `tool` retornam um erro 400 (`tool_choice: type "tool" and "any" are not supported for this model.`), inclusive no endpoint de contagem de tokens. Use `auto` com [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) ou [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) e diga no prompt quando a ferramenta se aplica. O uso estrito de ferramentas aceita um subconjunto do JSON Schema, então verifique o `input_schema` de cada ferramenta antes de adicionar `strict: true`. Todo objeto no schema deve definir `additionalProperties: false`; consulte [Limitações do JSON Schema](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs#json-schema-limitations). No Amazon Bedrock, as saídas estruturadas, que incluem o uso estrito de ferramentas, não estão disponíveis para o Claude Opus 5.5. Nessa plataforma, envie `auto` sem `strict`, diga no prompt quando a ferramenta se aplica e valide a entrada da ferramenta no seu código. Consulte [O uso forçado de ferramentas não é suportado](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#forced-tool-use-is-not-supported).
Antes. O Claude Opus 5 aceita esta requisição, e o Claude Opus 5.5 a rejeita com um erro 400:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
}
}],
"tool_choice": {"type": "tool", "name": "get_weather"},
"messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
tool_choice:
type: tool
name: get_weather
messages:
- role: user
content: What's the weather in Paris?
YAML
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [.. tools],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.tools(tools)
.toolChoice(ToolChoiceTool.of("get_weather"))
.addUserMessage("What's the weather in Paris?")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 1024,
tools: $tools,
toolChoice: ToolChoiceTool::with(name: 'get_weather'),
messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 1024,
tools: tools,
tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
messages: [{ role: "user", content: "What's the weather in Paris?" }]
)
```
Depois:
```bash cURL
# uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}],
"tool_choice": {"type": "auto"},
"messages": [{
"role": "user",
"content": "What'\''s the weather in Paris? Use the get_weather tool."
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
# uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
strict: true
tool_choice:
type: auto
messages:
- role: user
content: What's the weather in Paris? Use the get_weather tool.
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
# uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
// uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
tools: tools.map((tool) => ({ ...tool, strict: true })),
tool_choice: { type: "auto" },
messages: [
{
role: "user",
content: "What's the weather in Paris? Use the get_weather tool."
}
]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
// uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
Tools = [.. tools.Select(tool => tool with { Strict = true })],
ToolChoice = new ToolChoiceAuto(),
Messages =
[
new()
{
Role = Role.User,
Content = "What's the weather in Paris? Use the get_weather tool.",
},
],
});
```
```go Go
// uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
var strictTools []anthropic.ToolUnionParam
for _, tool := range tools {
strictTool := *tool.OfTool
strictTool.Strict = anthropic.Bool(true)
strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
}
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: strictTools,
ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
// uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
.tools(tools.stream()
.map(tool -> tool.tool()
.map(customTool -> customTool.toBuilder().strict(true).build())
.map(ToolUnion::ofTool)
.orElse(tool))
.toList())
.toolChoice(ToolChoiceAuto.builder().build())
.addUserMessage("What's the weather in Paris? Use the get_weather tool.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
// uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
toolChoice: ToolChoiceAuto::with(),
messages: [
[
'role' => 'user',
'content' => "What's the weather in Paris? Use the get_weather tool.",
],
],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
# uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
tools: tools.map { |tool| tool.merge(strict: true) },
tool_choice: Anthropic::ToolChoiceAuto.new,
messages: [
{ role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
]
)
```
#### Os blocos de pensamento estão vinculados ao modelo e à conversa
Na Claude API, o Claude Fable 5.1 e o Claude Mythos 5.1 leem os blocos de pensamento do Claude Opus 5.5; nenhum outro modelo os lê. Um roteador ou fallback que move uma conversa do Claude Opus 5.5 para qualquer outro modelo executa esses turnos sem eles. Na outra direção, o Claude Opus 5.5 lê blocos de pensamento do Claude Opus 5, de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos. Mantenha a conversa somente com acréscimos (sem edições no prompt `system`, em `tools` ou em mensagens anteriores no meio da conversa) para que os blocos continuem válidos; o Claude Code, o claude.ai, o Claude Managed Agents e o Claude Agent SDK já fazem isso. A aplicação dessa regra é igual à do Claude Fable 5.1 em todas as plataformas: para contas criadas a partir de 31 de agosto de 2026, 00:00 UTC, reenviar um bloco de pensamento após tal edição retorna um erro 400 por padrão. Não há alteração de código para integrações somente com acréscimos. Consulte [Os blocos de pensamento estão vinculados ao modelo e à conversa](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them) e [Pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking).
#### A ferramenta de uso de computador `computer_20251124` não é suportada na Claude API e no Google Cloud
Na Claude API e no Google Cloud, uma entrada em `tools` do tipo `computer_20251124` retorna um erro 400 (`'claude-opus-5-5' does not support tool types: computer_20251124.`, seguido dos tipos de ferramenta que o modelo aceita). Em vez disso, declare o "toolset" (conjunto de ferramentas) `computer_toolset_20260801`: remova o cabeçalho beta e envie a entrada sem `name` nem dimensões de exibição. No seu loop de agente, trate os blocos `tool_use` dos membros (a ação é o `name` do bloco, não `input.action`), vários deles por turno, e repita `toolset_name` em cada resultado. A alteração na requisição é mostrada abaixo; as alterações no loop de agente estão listadas em [Migrar de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). No Amazon Bedrock, a ferramenta anterior `computer_20251124` continua funcionando no Claude Opus 5.5 como funciona no Claude Opus 5, portanto nenhuma alteração é necessária lá; para outras plataformas, consulte a seção [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#compatibility) da ferramenta de "computer use" (uso de computador). Consulte [A ferramenta de uso de computador `computer_20251124` não é suportada na Claude API e no Google Cloud](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#computer-20251124-is-not-supported).
Antes. O Claude Opus 5 aceita esta requisição e, na Claude API e no Google Cloud, o Claude Opus 5.5 a rejeita com um erro 400:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: computer-use-2025-11-24" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 4096,
"tools": [{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768
}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
ant beta:messages create \
--model claude-opus-5 \
--max-tokens 4096 \
--beta computer-use-2025-11-24 \
--tool '{
type: computer_20251124,
name: computer,
display_width_px: 1024,
display_height_px: 768
}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["computer-use-2025-11-24"],
tools=[
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}
],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.beta.messages.create({
model: "claude-opus-5",
max_tokens: 4096,
betas: ["computer-use-2025-11-24"],
tools: [
{
type: "computer_20251124",
name: "computer",
display_width_px: 1024,
display_height_px: 768
}
],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Betas = [AnthropicBeta.ComputerUse2025_11_24],
Tools =
[
new BetaToolComputerUse20251124
{
DisplayWidthPx = 1024,
DisplayHeightPx = 768,
},
],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaComputerUse2025_11_24},
Tools: []anthropic.BetaToolUnionParam{
{OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{
DisplayWidthPx: 1024,
DisplayHeightPx: 768,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.COMPUTER_USE_2025_11_24)
.addTool(BetaToolComputerUse20251124.builder()
.displayWidthPx(1024L)
.displayHeightPx(768L)
.build())
.addUserMessage("Open the display settings.")
.build();
client.beta().messages().create(params);
```
```php PHP
$client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 4096,
betas: [AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
BetaToolComputerUse20251124::with(
displayWidthPx: 1024,
displayHeightPx: 768,
),
],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
Anthropic::Beta::BetaToolComputerUse20251124.new(
name: :computer,
display_width_px: 1024,
display_height_px: 768
)
],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
Depois:
```bash cURL
# sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"tools": [{"type": "computer_toolset_20260801"}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
# sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--tool '{type: computer_toolset_20260801}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
# sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
tools=[{"type": "computer_toolset_20260801"}],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
// sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
tools: [{ type: "computer_toolset_20260801" }],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
// sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
Tools = [new ComputerToolset20260801()],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
// sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
.addTool(ComputerToolset20260801.builder().build())
.addUserMessage("Open the display settings.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
// sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
tools: [ComputerToolset20260801::with()],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
# sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
tools: [Anthropic::ComputerToolset20260801.new],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
### O texto entre chamadas de ferramentas é retornado em blocos de pensamento
No Claude Opus 5, o texto que o modelo escreve entre chamadas de ferramentas volta como blocos `text`. No Claude Opus 5.5, assim como no Claude Fable 5.1, essa narração volta como [blocos `thinking` de atualização de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates), no máximo um antes de cada chamada de ferramenta. Com o valor padrão `"omitted"` de `thinking.display`, o campo `thinking` desses blocos fica vazio. Nenhuma requisição falha, mas uma aplicação que faz streaming desse texto para seus usuários como atualizações de progresso fica em silêncio entre as chamadas de ferramentas. Para restaurar as atualizações, leia-as dos blocos `thinking` e defina um valor de `display` que retorne o texto delas: `"updates"` (beta, cabeçalho `thinking-display-updates-2026-08-18`) retorna as atualizações de progresso enquanto o raciocínio permanece oculto, e `"summarized"` retorna ambos, misturados. Em seguida, renderize cada bloco `thinking` não vazio antes do bloco `tool_use` que ele precede e devolva os blocos inalterados com o restante do turno do assistente. Consulte [Atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates).
### Classificadores de segurança e fallback
O Claude Opus 5.5 pode retornar `stop_reason: "refusal"` com uma categoria em `stop_details`. Seus classificadores cobrem um conjunto mais amplo de categorias do que os do Claude Opus 5, então espere valores de `stop_details.category` como `"bio"` além de `"cyber"` e `"reasoning_extraction"`; consulte a [tabela de categorias de recusa](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#refusal-response). Lide com as recusas e configure o [fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback) ou sua própria nova tentativa (o fallback no lado do servidor não tenta novamente requisições recusadas com `"reasoning_extraction"`; essa recusa é retornada a você); consulte [Recusas e fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback) e [Recusas de salvaguardas](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals).
### Mudanças recomendadas
1. **Execute novamente sua varredura de esforço.** O esforço é o único controle de pensamento no Claude Opus 5.5, e seu padrão é `medium`, enquanto o do Claude Opus 5 é `high`; portanto, uma requisição que omite `effort` agora é executada em `medium`. Reduza o nível onde a qualidade se mantiver e aumente-o para o trabalho mais exigente. Consulte [Esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort).
2. **Reavalie as instruções de prompt específicas do modelo.** Instruções ajustadas para o comportamento do Claude Opus 5 podem não ser mais necessárias; consulte [Prompting do Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5). Se você executava com o pensamento desativado, consulte também [Prompts escritos para pensamento desativado](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled).
3. **Teste em um ambiente de desenvolvimento** antes de migrar o tráfego de produção.
## Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.8
Primeiro, percorra [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response) e [Migrando para o Claude Opus 5.5 a partir do Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Use `claude-opus-4-8` como o ID de modelo que você substitui. Essa última seção se aplica ao código no Claude Opus 4.8 tal como está escrita, porque o Claude Opus 4.8, assim como o Claude Opus 5:
* Aceita `thinking: {"type": "disabled"}`, escolha forçada de ferramenta e a ferramenta `computer_20251124`.
* Retorna o texto entre chamadas de ferramentas como blocos `text`.
* Tem esforço `high` como padrão.
Esta seção acrescenta o que mudou entre o Claude Opus 4.8 e o Claude Opus 5. Para um checklist, consulte os dois primeiros grupos do [checklist de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist).
### O que mudou
1. **O pensamento é executado em requisições que o omitiam:** No Claude Opus 4.8, o pensamento fica desativado a menos que você o solicite. No Claude Opus 5.5, uma requisição sem campo `thinking` é executada com pensamento, então cada item em [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response) é uma alteração para esse código. Se seu código nunca enviou um campo `thinking`, não há nada a remover no [antes e depois para o pensamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-cant-be-disabled).
2. **Mínimo menor de "prompt caching" (cache de prompt):** O comprimento mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens do Claude Opus 4.8. Prompts que eram curtos demais para cache no Claude Opus 4.8 podem criar entradas de cache, sem necessidade de alterações de código. Consulte [Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#cache-limitations) para os mínimos por modelo.
3. **O Priority Tier não é suportado:** O [Priority Tier](https://platform.claude.com/docs/pt-BR/api/service-tiers#supported-models) não é suportado no Claude Opus 5.5, enquanto o Claude Opus 4.8 o mantém. Se sua organização tem um compromisso de Priority Tier, planeje a capacidade separadamente.
### Mudanças recomendadas
Estas alterações não são obrigatórias, mas melhorarão sua experiência:
1. **Considere orçamentos de tarefa (beta):** Para cargas de trabalho agênticas, os [orçamentos de tarefa](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets) informam ao modelo quantos tokens ele tem para um loop agêntico completo. Eles exigem o cabeçalho beta `task-budgets-2026-03-13`.
2. **Considere alterações de ferramentas no meio da conversa (beta):** As alterações de ferramentas no meio da conversa permitem adicionar ou remover ferramentas entre os turnos de uma conversa sem invalidar os acertos do [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) em turnos anteriores. Alterar o próprio array `tools` invalida o prefixo em cache. Na Claude API, envie o cabeçalho beta `inline-tools-2026-09-15`. O cabeçalho mais antigo `mid-conversation-tool-changes-2026-07-01` ainda funciona para alterações que referenciam uma ferramenta pelo nome, na Claude API, no Amazon Bedrock e no Google Cloud.
## Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.7
Primeiro, percorra [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response), [Migrando para o Claude Opus 5.5 a partir do Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5) e [Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8). Use `claude-opus-4-7` como o ID de modelo que você substitui. Essas seções se aplicam ao código no Claude Opus 4.7 tal como estão escritas. Assim como o Claude Opus 4.8, ele aceita `thinking: {"type": "disabled"}`, escolha forçada de ferramenta e a ferramenta `computer_20251124`. Ele tem esforço `high` como padrão e é executado sem pensamento a menos que você o solicite.
Esta seção acrescenta o que mudou após o Claude Opus 4.7. Se seu código está no Claude Opus 4.6 ou anterior, continue com [Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.6 e modelos Opus anteriores](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) após esta seção. A seção do Claude Opus 4.6 acrescenta as mudanças incompatíveis que entraram em vigor no Claude Opus 4.7. Para um checklist, consulte os três primeiros grupos do [checklist de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist).
### O que mudou
Nenhum destes itens acrescenta uma mudança incompatível às das seções anteriores; vale a pena verificá-los depois de trocar o ID do modelo.
1. **Níveis de esforço recalibrados:** A alocação de tokens por trás de cada nível de esforço muda no Claude Opus 5.5 em comparação com o Claude Opus 4.7. O padrão é `medium`, enquanto o do Claude Opus 4.7 é `high`. Execute uma nova varredura de esforço em suas próprias avaliações em vez de manter uma configuração ajustada para o Claude Opus 4.7. Consulte [Esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort).
2. **A janela de contexto de 1M é o padrão:** O Claude Opus 5.5 oferece a [janela de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/context-windows) completa de 1M tokens por padrão, sem cabeçalho beta. Se seu cliente passa um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, remova-o.
3. **Mensagens de sistema no meio da conversa:** Na Claude API, no Amazon Bedrock e no Google Cloud, o Claude Opus 5.5 aceita mensagens `role: "system"` imediatamente após um turno do usuário no array `messages` (sujeito às [regras de posicionamento](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages#limitations)). Use o campo `system` de nível superior para instruções que se aplicam desde o início. O Claude Opus 4.7 rejeita `role: "system"` em `messages` com um erro 400. Se você mantém caminhos de código que reconstroem todo o histórico de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) em turnos anteriores.
4. **Detalhes de parada em recusas:** Quando o modelo recusa uma requisição, o Claude Opus 5.5 retorna um objeto `stop_details` que nomeia a categoria da recusa, junto com o motivo de parada `refusal`. O Claude Opus 4.7 retorna o mesmo objeto, então isso só importa se o seu tratamento de motivos de parada ainda não o lê. Nenhum cabeçalho beta é necessário, e não há opção de desativação. Se o seu tratamento de motivos de parada ainda não o lê, consulte [Tratando motivos de parada](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons). O Claude Opus 5.5 recusa em mais categorias; consulte [Classificadores de segurança e fallback](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#safety-classifiers-and-fallback).
5. **Modo rápido:** O Claude Opus 5.5 suporta o [modo rápido](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode) na Claude API. O modo rápido não está disponível no Claude Opus 4.7, onde requisições com `speed: "fast"` retornam um erro. Defina `speed: "fast"` nas suas requisições. O Claude Opus 5.5 não precisa de cabeçalho beta.
6. **Toolset de uso de computador e ferramenta de uso do navegador:** Na Claude API e no Google Cloud, o Claude Opus 5.5 suporta o [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) como o toolset `computer_toolset_20260801` e a [ferramenta de uso do navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) para tarefas dentro de páginas web. O Claude Opus 4.7 não suporta nenhum dos dois. Nessas plataformas, o Claude Opus 5.5 não aceita a ferramenta anterior `computer_20251124`; consulte a [mudança incompatível do uso de computador](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#computer-use-toolset).
## Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.6 e modelos Opus anteriores
Primeiro, percorra todas as seções anteriores, na ordem da página. Elas são [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response) e as seções do [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), do [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8) e do [Claude Opus 4.7](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-47). Essas seções se aplicam ao código no Claude Opus 4.6 tal como estão escritas. Assim como o Claude Opus 4.7, ele aceita `thinking: {"type": "disabled"}`, escolha forçada de ferramenta e a ferramenta `computer_20251124`. Ele tem esforço `high` como padrão e é executado sem pensamento a menos que você o solicite. O Claude Opus 4.5 e modelos Opus anteriores também aceitam `thinking: {"type": "disabled"}` e escolha forçada de ferramenta, e são executados sem pensamento a menos que você o solicite, então essas seções também se aplicam a eles.
Esta seção acrescenta o que mudou no Claude Opus 4.7, com `claude-opus-4-6` como o ID de modelo que você substitui. Suas duas subseções acrescentam o que mudou antes disso, para leitores no [Claude Opus 4.5 ou anterior](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-45) e no [Claude 4.1 ou anterior](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier). Para um checklist, consulte o [checklist de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist) até o grupo que nomeia seu modelo.
### Mudanças incompatíveis
1. **"Extended thinking" (pensamento estendido) removido:** `thinking: {"type": "enabled", "budget_tokens": N}` não é mais suportado no Claude Opus 4.7 e em modelos posteriores e retorna um erro 400. Mude para o ["adaptive thinking" (pensamento adaptativo)](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`) e use o ["effort parameter" (parâmetro de esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) para controlar a profundidade do pensamento. No Claude Opus 5.5, o pensamento adaptativo está sempre ativado: `thinking: {"type": "adaptive"}` é válido e equivale a omitir completamente o campo `thinking`.
Antes (Claude Opus 4.6):
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: { type: "enabled", budget_tokens: 10000 },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{ role: "user", content: "..." }
]
)
```
Depois (Claude Opus 5.5), em que as linhas do ID do modelo, de `thinking` e de `output_config` diferem:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 16000
thinking:
type: adaptive
output_config:
effort: high
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
.build())
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "high" # or "max", "xhigh", "medium", "low"
},
messages: [
{ role: "user", content: "..." }
]
)
```
O pensamento adaptativo pode ser direcionado por meio de prompts e do [parâmetro de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort), que substitui o orçamento de pensamento como a forma de controlar o quanto o modelo raciocina. Execute uma varredura de níveis de esforço nas suas próprias avaliações em vez de converter um valor de `budget_tokens`. A [tabela de níveis de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#effort-levels) descreve quando usar cada nível, e [Níveis de esforço recomendados para o Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5) aborda este modelo.
2. **Parâmetros de amostragem removidos:** Definir `temperature`, `top_p` ou `top_k` com qualquer valor diferente do padrão no Claude Opus 4.7 e em modelos posteriores, incluindo o Claude Opus 5.5, retorna um erro 400. O SDK Python (v1.0 e posteriores) não os define, e passá-los gera um `TypeError`. O caminho de migração mais seguro é omitir completamente esses parâmetros dos payloads das requisições. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5.5. Se você estava usando `temperature = 0` para obter determinismo, observe que isso nunca garantiu saídas idênticas nos modelos anteriores.
3. **Conteúdo do pensamento omitido por padrão:** Os blocos de pensamento ainda aparecem no stream de resposta no Claude Opus 4.7 e em modelos posteriores, mas o campo `thinking` deles fica vazio, a menos que você opte explicitamente por recebê-lo. Esta é uma mudança silenciosa em relação ao Claude Opus 4.6, em que o padrão era retornar o texto resumido do pensamento. Para restaurá-lo, consulte o item 4 de [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response).
4. **Contagem de tokens atualizada:** O Claude Opus 4.7 introduziu um novo tokenizador, que os modelos Opus posteriores, incluindo o Claude Opus 5.5, também usam. Ele contribui para um desempenho melhor em uma ampla variedade de tarefas e pode usar aproximadamente de 1x a 1,35x mais tokens ao processar texto em comparação com os modelos anteriores ao Claude Opus 4.7 (até \~35% a mais, variando conforme o conteúdo).
[`/v1/messages/count_tokens`](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) retorna um número de tokens diferente para o Claude Opus 5.5 do que retornava para o Claude Opus 4.6. A eficiência de tokens pode variar conforme o formato da carga de trabalho.
Atualize seus parâmetros `max_tokens` para dar margem adicional, incluindo os gatilhos de compactação, e teste novamente qualquer caminho de código que estime tokens no lado do cliente ou que presuma uma proporção fixa entre tokens e caracteres. Use o [endpoint de contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) para verificar. Intervenções nos prompts, [`task_budget`](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets) e [`effort`](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) podem ajudar a controlar os custos; esses controles podem ter como contrapartida a inteligência do modelo.
5. **Remoção do prefill (já em vigor no Claude Opus 4.6):** Preencher previamente mensagens do assistente retorna um erro 400 no Claude Opus 4.6 e em modelos Opus posteriores, incluindo o Claude Opus 5.5, portanto isso só é uma mudança se você vier do Claude Opus 4.5 ou anterior. Em vez disso, use [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) ou instruções no prompt do sistema. No Amazon Bedrock, as saídas estruturadas não estão disponíveis para o Claude Opus 5.5, então use instruções no prompt do sistema nesse caso.
### Mudanças de comportamento
O Claude Opus 4.7 introduziu diferenças de comportamento em relação ao Claude Opus 4.6 que não são mudanças incompatíveis da API. Estas três afetam o código ou a estrutura de suporte:
1. **Atualizações de progresso integradas em rastros agênticos:** O Claude Opus 4.7 fornece atualizações mais regulares e de maior qualidade ao usuário ao longo de rastros agênticos longos. Se você adicionou estruturas de suporte para forçar mensagens de status intermediárias ("Após cada 3 chamadas de ferramenta, resuma o progresso"), experimente removê-las. No Claude Opus 5.5, essas atualizações chegam em blocos `thinking`, que ficam vazios com o `thinking.display` padrão. Para recebê-las, consulte [O texto entre chamadas de ferramentas é retornado em blocos de pensamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#text-between-tool-calls). Para definir o tamanho e o conteúdo delas, consulte [Atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates).
2. **Salvaguardas de cibersegurança em tempo real:** Adicionadas no Claude Opus 4.7, requisições que envolvem tópicos proibidos ou de alto risco podem resultar em recusas. Para trabalhos de segurança legítimos, como testes de penetração, pesquisa de vulnerabilidades ou red-teaming, inscreva-se no [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) para solicitar restrições reduzidas. A forma de inscrição depende de como você acessa o Claude.
3. **Suporte a imagens de alta resolução:** O Claude Opus 4.7 é o primeiro modelo Claude com suporte a imagens de alta resolução. A resolução máxima de imagem é de 2.576 pixels no lado maior, acima dos 1.568 pixels dos modelos anteriores. Isso gera ganhos em cargas de trabalho com uso intenso de visão e é particularmente valioso para uso de computador, compreensão de capturas de tela e análise de documentos.
O suporte a alta resolução é automático e não requer cabeçalho beta nem opt-in do lado do cliente. Duas coisas para planejar:
* Imagens em resolução total podem usar até aproximadamente 3x mais tokens de imagem do que nos modelos anteriores (até 4.784 tokens por imagem, em comparação com o limite anterior de aproximadamente 1.600 tokens por imagem). Refaça o orçamento de `max_tokens` e as expectativas de custo para cargas de trabalho com muitas imagens, ou reduza a resolução antes de enviar se você não precisa da fidelidade adicional.
* As coordenadas de apontamento e de caixas delimitadoras retornadas pelo modelo são 1:1 com os pixels reais da imagem no Claude Opus 4.7, portanto nenhuma conversão de fator de escala é necessária.
Consulte [Suporte a imagens de alta resolução no Claude Opus 4.7](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7) para detalhes.
Para diferenças relacionadas aos prompts, consulte [Prompting do Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) e [Melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).
### Migrando do Claude Opus 4.5 ou anterior
Se você está migrando do Claude Opus 4.5, do Claude Opus 4.1 ou de um modelo anterior diretamente para o Claude Opus 5.5, leia esta página desde o início: primeiro, percorra todas as seções anteriores, na ordem da página. Em seguida, percorra as [mudanças incompatíveis para migrar do Claude Opus 4.6](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#opus-46-breaking-changes), apresentadas anteriormente nesta seção. Depois, aplique as seguintes mudanças cumulativas, que entraram em vigor entre o Claude Opus 4.5 e o Claude Opus 4.7. Se você está no Claude Opus 4.1 ou anterior, continue com [Migrando do Claude 4.1 ou anterior](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier) após esta subseção.
#### Mudanças incompatíveis
1. A **remoção do prefill** é abordada nas [mudanças incompatíveis para migrar do Claude Opus 4.6](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#opus-46-breaking-changes).
2. **Aspas em parâmetros de ferramentas:** O Claude Opus 4.6 e modelos posteriores podem produzir escape de strings JSON ligeiramente diferente nos argumentos de chamadas de ferramentas (por exemplo, tratamento diferente de escapes Unicode ou escape de barras). Se você analisa o `input` da chamada de ferramenta como uma string bruta em vez de usar um parser JSON, verifique sua lógica de análise. Parsers JSON padrão (como `json.loads()` ou `JSON.parse()`) lidam com essas diferenças automaticamente.
#### Mudanças recomendadas
O primeiro item é obrigatório no Claude Opus 5.5; os demais são recomendados.
1. **Migre para o pensamento adaptativo (obrigatório):** `thinking: {"type": "enabled", "budget_tokens": N}` retorna um erro 400 no Claude Opus 4.7 e em modelos posteriores. O antes e depois está no item 1 das [mudanças incompatíveis para migrar do Claude Opus 4.6](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#opus-46-breaking-changes). A migração também passa de `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) para `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`): o pensamento adaptativo e o esforço não exigem o namespace beta do SDK nem quaisquer cabeçalhos beta.
2. **Remova o cabeçalho beta de effort:** O parâmetro effort não requer um cabeçalho beta. Remova o beta `effort-2025-11-24` das suas requisições.
3. **Remova o cabeçalho beta de streaming de ferramentas de granularidade fina:** O streaming de ferramentas de granularidade fina não requer um cabeçalho beta. Remova o beta `fine-grained-tool-streaming-2025-05-14` das suas requisições.
4. **Remova o cabeçalho beta de pensamento intercalado:** Com o pensamento adaptativo, o pensamento intercalado é automático em todos os modelos que suportam pensamento adaptativo. Remova o beta `interleaved-thinking-2025-05-14` das suas requisições.
5. **Migre para output\_config.format:** Se estiver usando saídas estruturadas, atualize `output_format={...}` para `output_config={"format": {...}}`. O parâmetro `output_format` está descontinuado e será removido no futuro. Para usá-lo mesmo assim, adicione o cabeçalho beta `structured-outputs-2025-11-13`. Sem ele, a API retorna um erro 400. O SDK Python (v1.0 e posteriores) não aceita `output_format={...}` em `client.beta.messages.create()` nem em `count_tokens()`. O argumento `output_format=Model` dos helpers `parse()` e `stream()` permanece inalterado.
### Migrando do Claude 4.1 ou anterior
Se você está migrando do Claude Opus 4.1 ou de modelos anteriores diretamente para o Claude Opus 5.5, primeiro aplique tudo o que está em [Migrando do Claude Opus 4.5 ou anterior](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-45). Essa subseção começa com todas as seções anteriores, então, na prática, você lê esta página desde o início. Em seguida, aplique as mudanças adicionais desta subseção.
#### Mudanças incompatíveis adicionais
1. **Remova os parâmetros de amostragem:** Abordado em [Parâmetros de amostragem removidos](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#opus-46-breaking-changes).
2. **Atualize as versões das ferramentas**
Esta é uma mudança incompatível ao migrar de modelos Claude 3.x.
Atualize para as versões atuais das ferramentas. Remova qualquer código que use o comando `undo_edit`.
```python Python
# Antes
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# Depois
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
```
```typescript TypeScript
// Antes
const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }];
// Depois
const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];
```
```csharp C#
var parameters = new MessageCreateParams
{
// Antes: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Depois:
Tools = [new ToolTextEditor20250728()],
// ...
};
```
```go Go
params := anthropic.MessageNewParams{
// Antes: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Depois:
Tools: []anthropic.ToolUnionParam{
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
},
// ...
}
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
// Antes: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// Depois:
.addTool(ToolTextEditor20250728.builder().build())
// ...
.build();
```
```php PHP
$message = $client->messages->create(
// Antes: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']
// Depois:
tools: [new ToolTextEditor20250728()],
// ...
);
```
```ruby Ruby
# Antes
legacy_tools = [{type: "text_editor_20250124", name: "str_replace_editor"}]
# Depois
tools = [{type: "text_editor_20250728", name: "str_replace_based_edit_tool"}]
```
* **Editor de texto:** Use `text_editor_20250728` e `str_replace_based_edit_tool`. Consulte a documentação da [ferramenta de editor de texto](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool) para obter detalhes.
* **Execução de código:** Atualize para `code_execution_20260521`. Consulte a documentação da [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) para obter instruções de migração.
* **Uso de computador:** Na Claude API e no Google Cloud, o Claude Opus 5.5 aceita o uso de computador apenas como o toolset `computer_toolset_20260801`: as ferramentas anteriores `computer_20250124` e `computer_20251124` são rejeitadas nessas plataformas. Consulte a [mudança incompatível do uso de computador](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#computer-use-toolset).
3. **Trate o motivo de parada `refusal`**
Atualize sua aplicação para [tratar motivos de parada `refusal`](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals):
```python Python
response = client.messages.create(...)
if response.stop_reason == "refusal":
# Trate a recusa adequadamente
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "refusal") {
// Trate a recusa adequadamente
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Value() == StopReason.Refusal)
{
// Trate a recusa adequadamente
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == anthropic.StopReasonRefusal {
// Trate a recusa adequadamente
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.REFUSAL)) {
// Trate a recusa adequadamente
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'refusal') {
// Trate a recusa adequadamente
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :refusal
# Trate a recusa adequadamente
end
```
4. **Trate o motivo de parada `model_context_window_exceeded`**
O Claude 4.5 e modelos posteriores retornam um motivo de parada `model_context_window_exceeded` quando a geração é interrompida por atingir o limite da "context window" (janela de contexto), e não o limite de `max_tokens` solicitado. Atualize sua aplicação para lidar com esse novo motivo de parada:
```python Python
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# Trate o limite da janela de contexto adequadamente
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "model_context_window_exceeded") {
// Trate o limite da janela de contexto adequadamente
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// Trate o limite da janela de contexto adequadamente
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// Trate o limite da janela de contexto adequadamente
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
// Trate o limite da janela de contexto adequadamente
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'model_context_window_exceeded') {
// Trate o limite da janela de contexto adequadamente
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :model_context_window_exceeded
# Trate o limite da janela de contexto adequadamente
end
```
5. **Verifique o tratamento de parâmetros de ferramentas (quebras de linha finais)**
O Claude 4.5 e modelos posteriores preservam as quebras de linha finais nos parâmetros de string das chamadas de ferramenta, que antes eram removidas. Se suas ferramentas dependem de correspondência exata de strings com os parâmetros das chamadas de ferramenta, verifique se sua lógica lida corretamente com as quebras de linha finais.
6. **Atualize seus prompts para as mudanças comportamentais**
O Claude 4 e modelos posteriores têm um estilo de comunicação mais conciso e direto e exigem orientações explícitas. Revise as [melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices) para obter orientações de otimização.
#### Mudanças recomendadas adicionais
* **Remova cabeçalhos beta legados:** Remova `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`. Todos os modelos Claude 4 e posteriores têm "tool use" (uso de ferramentas) eficiente em tokens integrado, e esses cabeçalhos não têm efeito.
## Migrando para o Claude Opus 5.5 a partir do Claude Sonnet 5
Percorra [O que toda requisição ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lidar com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response) e [Migrando para o Claude Opus 5.5 a partir do Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Use `claude-sonnet-5` como o ID do modelo que você substitui. Essa última seção se aplica ao código no Claude Sonnet 5 tal como está escrito, porque o Claude Sonnet 5, assim como o Claude Opus 5:
* É executado com o pensamento ativado por padrão e aceita `thinking: {"type": "disabled"}`, no caso dele em qualquer nível de esforço.
* Aceita escolha forçada de ferramenta e a ferramenta `computer_20251124`.
* Retorna o texto entre chamadas de ferramentas como blocos `text`.
* Usa o esforço `high` por padrão.
O pensamento estendido manual, parâmetros de amostragem diferentes do padrão e o prefill do assistente retornam um erro 400 em ambos os modelos, portanto nada muda nesse aspecto. Nenhuma das mudanças obrigatórias nas seções do Claude Opus 4.8, do Claude Opus 4.7 e do Claude Opus 4.6 se aplica a você.
### O que mudou
1. **Mensagens de sistema no meio da conversa:** Na Claude API, no Amazon Bedrock e no Google Cloud, o Claude Opus 5.5 aceita mensagens `role: "system"` imediatamente após um turno do usuário no array `messages` (sujeito às [regras de posicionamento](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages#limitations)). Este recurso não está disponível no Claude Sonnet 5. Se você mantém caminhos de código que reconstroem todo o histórico de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de ["prompt cache" (cache de prompt)](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) em turnos anteriores.
2. **Mínimo menor para cache de prompt:** O tamanho mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens do Claude Sonnet 5. Prompts que eram curtos demais para serem armazenados em cache no Claude Sonnet 5 podem criar entradas de cache, sem necessidade de alterações no código. Consulte [Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#cache-limitations) para ver os mínimos por modelo.