---
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: Migre 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 solicitaçã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.
Deixe o Claude Code migrar seu código para você
```text
/claude-api migrate este projeto para claude-opus-5-5
```
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 solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements) e [Lide 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ê. A [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 USD; consulte [Preços do Claude](https://platform.claude.com/docs/pt-BR/about-claude/pricing)). Para o suporte a recursos, consulte [Novidades do 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 [Fazendo prompts para o Claude Opus 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5).
## O que toda solicitação ao Claude Opus 5.5 deve atender
Independentemente do modelo de origem, uma solicitação a `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, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) 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).
* **Pensamento:** Não envie nenhum campo `thinking`, ou envie `thinking: {"type": "adaptive"}`, que é equivalente: o [“adaptive thinking” (pensamento adaptativo)](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) 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 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 [“effort parameter” (parâmetro de esforço)](https://platform.claude.com/docs/pt-BR/build-with-claude/effort), o único parâmetro de requisição que o 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 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 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`. Use prompts para orientar o comportamento do modelo.
* **Preenchimento prévio:** Não termine `messages` com um turno de assistente pré-preenchido: 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 em vez disso.
* **Uso de computador:** Declare o uso de computador como o toolset `computer_toolset_20260801`. No Amazon Bedrock, `computer_20251124` também funciona. Consulte a [alteração incompatível de 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 janela de contexto é necessário. A [“context window” (janela de contexto) de 1M de 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 solicitação a seguir atende a todos os itens da lista: o esforço está definido e não há campo `thinking`. Onde o exemplo imprime texto, ele encontra o bloco de texto pelo seu tipo, 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: 2026-10-21" \
-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.type === "text");
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new UserMessageParam
{
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: Anthropic::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
```
## Lide com o pensamento em todas as respostas
O pensamento é executado em toda solicitação ao Claude Opus 5.5, então toda resposta pode começar com blocos `thinking`, e `max_tokens` cobre 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` cobre o pensamento mais o texto:** No Claude Opus 4.8 e em modelos Opus anteriores, solicitações sem o 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 solicitaçã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. Os 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 solicitação. Consulte [Controle de custos](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 com essas respostas. Em vez disso, selecione os blocos de conteúdo pelo campo `type`: leia `text` dos blocos cujo `type` é `"text"` e ramifique pelo tipo de bloco ao tratar eventos de stream.
3. **Retorne 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 quando retornar os resultados das ferramentas, incluindo blocos cujo campo `thinking` está vazio. Reenvie a mensagem do assistente como 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 removidos 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 faz streaming do raciocínio para os usuários, 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 voltam como blocos `thinking`, que ficam vazios com a 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 cita 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", ...}`; escolha um nível de esforço em vez disso.
* Defina `effort` explicitamente: o padrão é `medium`, enquanto o do Claude Opus 5 é `high`.
* Substitua os tipos `any` e `tool` de `tool_choice` por `auto` mais uso estrito de ferramentas ou saídas estruturadas.
* Se você usa uma versão anterior da ferramenta de uso de computador, declare `computer_toolset_20260801` (sem cabeçalho beta) em vez disso e atualize seu loop de agente para o toolset. No Amazon Bedrock, `computer_20251124` também funciona.
* 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 (Claude Fable 5.1 e 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 Claude Models on Google Cloud (Google managed), 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 devolva os blocos `thinking` 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 [Trate 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 o 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 quiser menos pensamento. Os 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 solicitaçã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 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
* Faça uma nova varredura de [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) nas 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 stop reason lê `stop_details` em recusas.
* Se você quer o modo rápido, que o Claude Opus 4.7 rejeita, defina `speed: "fast"` nas suas solicitaçõ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 das solicitações.
* 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` completamente; o pensamento adaptativo está sempre ativado.
* Se sua interface exibe o conteúdo do pensamento, ative explicitamente a 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 considerar a tokenização atualizada, incluindo os gatilhos de compactação.
* Teste novamente quaisquer estimativas de contagem de tokens no 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 caixa delimitadora do modelo, remova qualquer conversão por 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, candidate-se ao [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) para obter acesso a restrições mais baixas 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 das chamadas de ferramentas usa um parser JSON padrão.
* Mude 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 habilita 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 das ferramentas quanto a quebras de linha no final.
* Remova os cabeçalhos beta `token-efficient-tools-2025-02-19` e `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).
### Apenas 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 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 solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements) e [Lide com o pensamento em todas as respostas](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response). Todos os modelos de origem precisam das alterações desta seção. Elas são as configurações de solicitação que o Claude Opus 5.5 rejeita e as mudanças nas respostas que vêm com ele. A checklist desta seção é o primeiro grupo da [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, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed), no Claude Models on Google Cloud (Google managed) 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).
### Alterações incompatíveis
Cada alteração é explicada em [Alterações incompatíveis](https://platform.claude.com/docs/pt-BR/models/opus-5-5/whats-new-opus-5-5#breaking-changes) em Novidades do Claude Opus 5.5; 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 [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort); onde você desativava o pensamento para economizar tokens, use um nível mais baixo. As respostas passam então a começar com blocos `thinking`, então selecione os blocos de conteúdo por `type` e passe os blocos `thinking` de volta sem modificações com os resultados das 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 solicitaçã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: 2026-10-21" \
-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 UserMessageParam { 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 ativado; o esforço é o controle
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-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 esforço é o controle
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 UserMessageParam { 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 esforço é o controle
.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 esforço
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 thinking (pensamento) está sempre ativo; o effort (esforço) é o controle
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
```
#### O uso forçado de ferramentas não é suportado
Os tipos `any` e `tool` de `tool_choice` 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 indique 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). 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 solicitaçã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: 2026-10-21" \
-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 UserMessageParam { 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 segue o input_schema da ferramenta
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-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 estrito de ferramentas: toda chamada segue o 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 UserMessageParam { 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, Claude Fable 5.1 e Claude Mythos 5.1 leem os blocos de pensamento do Claude Opus 5.5; nenhum outro modelo faz isso. Um roteador ou uma alternativa de contingência que move uma conversa do Claude Opus 5.5 para qualquer outro modelo executa esses turnos sem eles. Na direção oposta, 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 Claude Models on Google Cloud (Google managed), do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos. Mantenha a conversa “append-only” (somente acréscimo), sem edições no prompt do sistema (`system`), em `tools` ou em mensagens anteriores no meio da conversa, para que os blocos continuem válidos; Claude Code, claude.ai, Claude Managed Agents e o Claude Agent SDK já fazem isso. Em contas criadas em ou após 31 de agosto de 2026, 00:00 UTC, na Claude API e em plataformas de nuvem, uma solicitação que reenvia um bloco de pensamento após uma edição desse tipo e deixa `thinking.block_binding.prefix_mismatch_behavior` sem definir recebe um erro 400. Não há alteração de código para integrações append-only. 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).
#### Algumas versões da ferramenta de uso de computador não são suportadas
O Claude Opus 5.5 suporta uso de computador por meio do toolset `computer_toolset_20260801`. No Amazon Bedrock, o Claude Opus 5.5 também aceita a ferramenta `computer_20251124` com o cabeçalho beta `computer-use-2025-11-24`. O Claude Opus 5.5 retorna um erro 400 para qualquer versão da ferramenta de uso de computador que ele não aceita, como `computer_20251124` na Claude API. Ele não aceita `computer_20250124` em nenhuma plataforma. Na Claude API, a mensagem de erro começa com `'claude-opus-5-5' does not support tool types: computer_20251124.` e então lista os tipos de ferramenta que o modelo aceita.
Integrações que usam o toolset não precisam de alteração. Para mover uma integração `computer_20251124` para o toolset, remova o cabeçalho beta e envie a entrada `computer_toolset_20260801` sem `name` nem dimensões de tela. No seu loop de agente, trate todos os blocos `tool_use` de membros em um turno e repita `toolset_name` em cada resultado. Leia a ação a partir do `name` de cada bloco, não de `input.action`. [Migrar de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124) lista as alterações no loop de agente.
Antes. O Claude Opus 5 aceita esta requisição, e o Claude Opus 5.5 a rejeita com um erro 400 na Claude API:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-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 BetaUserMessageParam { 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 cabeçalho beta; a entrada do conjunto de ferramentas 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: 2026-10-21" \
-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 cabeçalho beta; a entrada do toolset não aceita 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 cabeçalho 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 cabeçalho 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 cabeçalho beta; a entrada do toolset não recebe nome nem tamanho de exibição
Tools = [new ComputerToolset20260801()],
Messages = [new UserMessageParam { Content = "Open the display settings." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// sem cabeçalho 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 cabeçalho 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 cabeçalho 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 cabeçalho 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 `thinking.display` padrão de `"omitted"`, o campo `thinking` deles fica vazio. Nenhuma solicitaçã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 passe os blocos de volta sem alterações 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 de categorias mais amplo 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). Trate 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 solicitaçõ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 salvaguarda](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals).
### Alterações recomendadas
1. **Refaça 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`, então uma solicitação que omite `effort` agora é executada com `medium`. Reduza onde a qualidade se mantém e aumente 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 [Fazendo prompts para o 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 mudar 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 solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lide 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 como está escrita, porque o Claude Opus 4.8, assim como o Claude Opus 5:
* Aceita `thinking: {"type": "disabled"}`, a escolha forçada de ferramenta e a ferramenta `computer_20251124`.
* Retorna o texto entre chamadas de ferramentas como blocos `text`.
* Tem `high` como esforço padrão.
Esta seção acrescenta o que mudou entre o Claude Opus 4.8 e o Claude Opus 5. Para uma checklist, consulte os dois primeiros grupos da [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 solicitaçõ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 solicitação sem o campo `thinking` é executada com pensamento, então cada item em [Lide 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 o 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 para 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 no 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.
### Alterações recomendadas
Estas não são obrigatórias, mas vão melhorar sua experiência:
1. **Considere orçamentos de tarefa (beta):** Para cargas de trabalho agênticas, os [“task budgets” (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 de [“prompt cache” (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, no Claude Platform on AWS e no Claude Models on Google Cloud (Anthropic managed), envie o cabeçalho beta `inline-tools-2026-09-15`. O cabeçalho `mid-conversation-tool-changes-2026-07-01` funciona para alterações que nomeiam uma ferramenta por referência, na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed).
## Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.7
Primeiro, percorra [O que toda solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lide 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 como estão escritas. Assim como o Claude Opus 4.8, ele aceita `thinking: {"type": "disabled"}`, a escolha forçada de ferramenta e a ferramenta `computer_20251124`. Ele tem `high` como esforço 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 o 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. Ela acrescenta as alterações incompatíveis que entraram em vigor no Claude Opus 4.7. Para uma checklist, consulte os três primeiros grupos da [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 alteração 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 “effort” (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 reaproveitar 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. **Janela de contexto de 1M é o padrão:** O Claude Opus 5.5 oferece a [“context window” (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 o seu cliente envia um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, remova-o.
3. **Mensagens do sistema no meio da conversa:** Na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed), 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 por recusa:** Quando o modelo recusa uma solicitação, o Claude Opus 5.5 retorna um objeto `stop_details` que nomeia a categoria da recusa, junto com o “stop reason” (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 [Tratamento de 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 oferece suporte ao [“fast mode” (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 solicitações com `speed: "fast"` retornam um erro. Defina `speed: "fast"` em suas solicitações. O Claude Opus 5.5 não precisa de cabeçalho beta.
6. **Conjunto de ferramentas de uso de computador e ferramenta de uso de navegador:** O Claude Opus 5.5 oferece suporte ao [“computer use” (uso de computador)](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) como o conjunto de ferramentas `computer_toolset_20260801` e à [“browser use tool” (ferramenta de uso de navegador)](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) para tarefas dentro de páginas da web. O Claude Opus 4.7 não oferece suporte a nenhum dos dois. Para migrar uma integração `computer_20251124` para o conjunto de ferramentas, consulte a [alteração 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 de modelos Opus anteriores
Primeiro, percorra todas as seções anteriores, na ordem da página. São elas [O que toda solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lide com o pensamento em toda resposta](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#thinking-in-every-response) e as seções para o [Claude Opus 5](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), o [Claude Opus 4.8](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8) e o [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 usa por padrão o esforço `high` e é executado sem pensamento, a menos que você o solicite. O Claude Opus 4.5 e os 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, portanto 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 uma lista de verificação, consulte a [lista de verificação de migração](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#migration-checklist) até o grupo que menciona o seu modelo.
### Mudanças incompatíveis
1. **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 [parâmetro effort](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 equivalente a omitir totalmente 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: 2026-10-21" \
-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 UserMessageParam { 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: 2026-10-21" \
-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 UserMessageParam { 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: 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: Anthropic::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 effort](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 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:** Omita `temperature`, `top_p` e `top_k`. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5.5. Se você usava `temperature = 0` para obter determinismo, observe que isso nunca garantiu saídas idênticas nos modelos anteriores.
3. **Conteúdo de pensamento omitido por padrão:** Os blocos de pensamento ainda aparecem no fluxo de resposta no Claude Opus 4.7 e em modelos posteriores, mas seu campo `thinking` fica vazio, a menos que você opte explicitamente por recebê-lo. Essa é uma mudança silenciosa em relação ao Claude Opus 4.6, em que o padrão era retornar o texto de pensamento resumido. Para restaurá-lo, consulte o item 4 de [Lide com o pensamento em toda resposta](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 “tokenizer” (tokenizador), que os modelos Opus posteriores, incluindo o Claude Opus 5.5, também usam. Ele contribui para um desempenho aprimorado em uma ampla gama de tarefas e pode usar aproximadamente de 1x a 1,35x tokens ao processar texto em comparação com os modelos anteriores ao Claude Opus 4.7 (até cerca de 35 por cento 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 perfil 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 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 de prompt, [`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 custos; esses controles podem comprometer a inteligência do modelo.
5. **Remoção do prefill (já em vigor no Claude Opus 4.6):** Fazer “prefill” (preenchimento prévio) de 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. Use [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) ou instruções no prompt do sistema em vez disso.
### 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 apoio:
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 estrutura de apoio para forçar mensagens de status intermediárias (“Após cada 3 chamadas de ferramenta, resuma o progresso”), experimente removê-la. 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 ferramenta é retornado em blocos de pensamento](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#text-between-tool-calls). Para moldar seu tamanho e conteúdo, 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:** Essas salvaguardas são novas no Claude Opus 4.7: solicitações que envolvam tópicos proibidos ou de alto risco podem levar a 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 proporciona 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 ativação no lado do cliente. Dois pontos a 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 cerca de 1.600 tokens). Reavalie 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 caso não precise 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 por 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 obter detalhes.
Para diferenças relacionadas a prompts, consulte [Criando prompts para o 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 prompts](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).
### Migrando a partir 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 a migração a partir 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 a partir 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 a migração a partir 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 um escape de strings JSON ligeiramente diferente nos argumentos das chamadas de ferramenta (por exemplo, tratamento diferente de escapes Unicode ou do 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 a migração a partir 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 esforço:** O parâmetro effort não requer um cabeçalho beta. Remova o beta `effort-2025-11-24` das suas solicitações.
3. **Remova o cabeçalho beta de streaming de ferramentas refinado:** O streaming de ferramentas refinado não requer um cabeçalho beta. Remova o beta `fine-grained-tool-streaming-2025-05-14` das suas solicitaçõ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 solicitaçõ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 a partir 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 em [Migrando a partir 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 alteração 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 mais 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 instruções de migração.
* **Uso de computador:** Use o toolset `computer_toolset_20260801` no lugar de `computer_20250124`, que o Claude Opus 5.5 não aceita. No Amazon Bedrock, `computer_20251124` também funciona. Consulte a [alteração incompatível de 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 de forma apropriada
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "refusal") {
// Tratar a recusa adequadamente
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Value() == StopReason.Refusal)
{
// Trate a recusa de forma apropriada
}
```
```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 de forma adequada
}
```
```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`**
Os modelos Claude 4.5 e posteriores retornam um motivo de parada `model_context_window_exceeded` quando a geração para por atingir o limite da janela de contexto, em vez do limite `max_tokens` solicitado. Atualize sua aplicação para tratar este 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") {
// Tratar adequadamente o limite da janela de contexto
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// Trata adequadamente o limite da janela de contexto
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// Trate adequadamente o limite da janela de contexto
}
```
```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)**
Os modelos Claude 4.5 e posteriores preservam quebras de linha finais em parâmetros de string de chamadas de ferramentas que antes eram removidas. Se suas ferramentas dependem de correspondência exata de strings com parâmetros de chamadas de ferramentas, verifique se sua lógica trata quebras de linha finais corretamente.
6. **Atualize seus prompts para as mudanças de comportamento**
Os modelos Claude 4 e posteriores têm um estilo de comunicação mais conciso e direto e exigem direcionamento explícito. Revise as [melhores práticas de prompting](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices) para orientações de otimização.
#### Mudanças recomendadas adicionais
* **Cabeçalhos beta:** Remova `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`. Todos os modelos Claude 4 e posteriores têm uso de ferramentas com eficiência de 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 solicitação ao Claude Opus 5.5 deve atender](https://platform.claude.com/docs/pt-BR/models/opus-5-5/migration-guide#request-requirements), [Lide com o pensamento em toda resposta](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 de modelo que você substitui. Essa última seção se aplica ao código no Claude Sonnet 5 tal como está escrita, 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 ferramenta como blocos `text`.
* Usa por padrão o esforço `high`.
O pensamento estendido manual, os parâmetros de amostragem 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 para o Claude Opus 4.8, o Claude Opus 4.7 e o Claude Opus 4.6 se aplica a você.
### O que mudou
1. **Mensagens do sistema no meio da conversa:** Na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed), 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 [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) em turnos anteriores.
2. **Mínimo de cache de prompt mais baixo:** O comprimento mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens no 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 os mínimos por modelo.