---
title: Guia de migração para o Claude Sonnet 5.5
url: https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide
description: Mude para o Claude Sonnet 5.5 a partir de modelos Sonnet anteriores ou do Claude Haiku 4.5 com este guia de migração. As orientações para habilitar o Claude Sonnet 5.5 incluem configurações que retornam erros, mudanças no pensamento e uma lista de verificação para cada modelo de origem.
---

Este guia lista as alterações de código para migrar para o Claude Sonnet 5.5 a partir do Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet ou Claude Haiku 4.5. Leia as duas primeiras seções e depois continue até a seção do seu modelo atual. A [lista de verificação de migração](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migration-checklist) lista todas as alterações por modelo de origem.

<Note>
  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.
</Note>

<Tip>
  **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-sonnet-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.
</Tip>

O Claude Sonnet 5.5 tem os mesmos preços do Claude Sonnet 5, exceto pelas leituras do cache de prompt, que custam $0,10 USD por milhão de tokens, metade da tarifa do Claude Sonnet 5. Consulte [Preços do Claude](https://platform.claude.com/docs/pt-BR/about-claude/pricing). Para a "context window" (janela de contexto) e os limites de saída, consulte a [página do modelo Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview). Para recursos e prompts, consulte [Novidades do Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support) e [Como escrever prompts para o Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5).

## Envie uma solicitação ao Claude Sonnet 5.5

Esta solicitação funciona no Claude Sonnet 5.5 como está escrita. Ela define um nível de "effort" (esforço), e as abas de SDK leem a resposta por tipo de bloco. Ela omite cinco configurações que retornam um erro 400: [orçamentos de pensamento](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes), [parâmetros de amostragem](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes), ["assistant prefill" (preenchimento prévio do assistente)](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45), [escolha forçada de ferramenta](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#forced-tool-use) e [`thinking: {"type": "disabled"}`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking).

<CodeGroup>
  ```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-sonnet-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-sonnet-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-sonnet-5-5",
      max_tokens=4096,
      messages=[
          {
              "role": "user",
              "content": "Analyze the trade-offs between microservices and monolithic architectures",
          }
      ],
      output_config={"effort": "medium"},
  )

  print(f"Stop reason: {response.stop_reason}")
  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-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Analyze the trade-offs between microservices and monolithic architectures"
      }
    ],
    output_config: {
      effort: "medium"
    }
  });

  console.log(`Stop reason: ${response.stop_reason}`);
  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.ClaudeSonnet5_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($"Stop reason: {message.StopReason?.Raw()}");
  foreach (var block in message.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_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)
  }
  fmt.Println("Stop reason:", response.StopReason)
  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_SONNET_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.stopReason().ifPresent(reason -> IO.println("Stop reason: " + reason));
      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-sonnet-5-5',
      outputConfig: ['effort' => 'medium'],
  );

  echo "Stop reason: {$message->stopReason}", PHP_EOL;
  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-sonnet-5-5",
    max_tokens: 4096,
    messages: [
      { role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
    ],
    output_config: {
      effort: "medium"
    }
  )

  puts "Stop reason: #{message.stop_reason}"
  message.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

## O pensamento é executado por padrão

No Claude Sonnet 5.5, uma solicitação sem o campo `thinking` é executada com ["adaptive thinking" (pensamento adaptativo)](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking), assim como `thinking: {"type": "adaptive"}`. No Claude Sonnet 4.6 e modelos anteriores, e no Claude Haiku 4.5, essa solicitação era executada sem pensamento. Para continuar executando sem pensamento antecipado, consulte [Desative o pensamento antecipado](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking).

| Modelo                               | Pensamento sem o campo `thinking` | Valores de `thinking.type` aceitos                      | `display` padrão |
| ------------------------------------ | --------------------------------- | ------------------------------------------------------- | ---------------- |
| Claude Sonnet 5.5                    | Ativado                           | `"adaptive"`, `"between_tools"`                         | `"omitted"`      |
| Claude Sonnet 5                      | Ativado                           | `"adaptive"`, `"disabled"`                              | `"omitted"`      |
| Claude Sonnet 4.6                    | Desativado                        | `"adaptive"`, `"disabled"`, `"enabled"` (descontinuado) | `"summarized"`   |
| Claude Sonnet 4.5 e Claude Haiku 4.5 | Desativado                        | `"disabled"`, `"enabled"`                               | `"summarized"`   |

### Trate o pensamento nas respostas

Código que era executado sem pensamento precisa dos três itens. Código vindo do Claude Sonnet 5 provavelmente já tem os dois primeiros.

* **Leia os blocos de conteúdo por `type`.** Uma resposta pode começar com blocos `thinking`, então código que lê `content[0].text` deixa de funcionar.
* **Devolva os blocos `thinking` sem alterações** em loops de "tool use" (uso de ferramentas), incluindo os vazios. Consulte [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks).
* **Revise `max_tokens`.** Ele abrange pensamento mais texto, e os tokens de pensamento são cobrados como tokens de saída. Consulte [Controle de custos](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#cost-control).

O texto do pensamento é omitido por padrão. Os blocos `thinking` chegam com um campo `thinking` vazio e uma `signature`. Para obter resumos legíveis, defina `display: "summarized"`, o padrão no Claude Sonnet 4.6 e modelos anteriores, e no Claude Haiku 4.5. Consulte [Controlando a exibição do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display).

### Desative o pensamento antecipado

Para desativar o pensamento antecipado no Claude Sonnet 5.5, envie `thinking: {"type": "between_tools"}`. É a configuração de pensamento mais baixa. Suas atualizações de progresso entre chamadas de ferramentas ainda retornam como blocos `thinking` com seu texto de resumo. Sem ferramentas, a resposta contém apenas texto. O Claude Sonnet 5 desativa o pensamento com `thinking: {"type": "disabled"}`, e os modelos anteriores são executados sem pensamento por padrão. No Claude Sonnet 5.5, `disabled` retorna um erro 400 `invalid_request_error`:

```text wrap
To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.
```

`between_tools` funciona em todas as plataformas que oferecem o Claude Sonnet 5.5, sem cabeçalho beta. Ele é aceito nos níveis de esforço `low`, `medium` e `high`. Em `xhigh` ou `max`, retorna um erro 400. Para executar nesses níveis, use o pensamento adaptativo: omita o campo `thinking` ou envie `thinking: {"type": "adaptive"}`. `between_tools` não aceita nenhum outro campo: `display`, `budget_tokens` ou `block_binding` enviados com ele retornam um erro 400. Com o [fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback), uma solicitação `between_tools` que recorre ao Claude Sonnet 5 é executada lá com `thinking: {"type": "disabled"}`.

Com `between_tools`, o esforço não pode mudar no meio da conversa: um `output_config.effort` por mensagem que difira do nível em vigor retorna um erro 400. Para variar o esforço por turno, use o pensamento adaptativo. Para orientações sobre prompts, consulte [Executando sem pensamento antecipado](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking).

Antes (Claude Sonnet 5):

<CodeGroup>
  ```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-sonnet-5",
      "max_tokens": 16000,
      "thinking": {"type": "disabled"},
      "output_config": {"effort": "xhigh"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5 \
    --max-tokens 16000 \
    --thinking '{type: disabled}' \
    --output-config '{effort: xhigh}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5",
      max_tokens=16000,
      thinking={"type": "disabled"},
      output_config={"effort": "xhigh"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 16000,
    thinking: { type: "disabled" },
    output_config: { effort: "xhigh" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigDisabled(),
      OutputConfig = new() { Effort = Effort.Xhigh },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortXhigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigDisabled.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.XHIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5,
      maxTokens: 16000,
      thinking: ThinkingConfigDisabled::with(),
      outputConfig: OutputConfig::with(effort: Effort::XHIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigDisabled.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::XHIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

Depois (Claude Sonnet 5.5):

<CodeGroup>
  ```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-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {"type": "between_tools"},
      "output_config": {"effort": "high"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-sonnet-5-5 \
    --max-tokens 16000 \
    --thinking '{type: between_tools}' \
    --output-config '{effort: high}' \
    --message '{role: user, content: "..."}'
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-5-5",
      max_tokens=16000,
      thinking={"type": "between_tools"},
      output_config={"effort": "high"},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 16000,
    thinking: { type: "between_tools" },
    output_config: { effort: "high" },
    messages: [{ role: "user", content: "..." }]
  });
  ```

  ```csharp C#
  await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigBetweenTools(),
      OutputConfig = new() { Effort = Effort.High },
      Messages = [new() { Role = Role.User, Content = "..." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 16000,
  	Thinking: anthropic.ThinkingConfigParamUnion{
  		OfBetweenTools: &anthropic.ThinkingConfigBetweenToolsParam{},
  	},
  	OutputConfig: anthropic.OutputConfigParam{
  		Effort: anthropic.OutputConfigEffortHigh,
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
  	},
  })
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_SONNET_5_5)
      .maxTokens(16000L)
      .thinking(ThinkingConfigBetweenTools.builder().build())
      .outputConfig(OutputConfig.builder()
          .effort(OutputConfig.Effort.HIGH)
          .build())
      .addUserMessage("...")
      .build();

  client.messages().create(params);
  ```

  ```php PHP
  $client->messages->create(
      model: Model::CLAUDE_SONNET_5_5,
      maxTokens: 16000,
      thinking: ThinkingConfigBetweenTools::with(),
      outputConfig: OutputConfig::with(effort: Effort::HIGH),
      messages: [['role' => 'user', 'content' => '...']],
  );
  ```

  ```ruby Ruby
  client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 16000,
    thinking: Anthropic::ThinkingConfigBetweenTools.new,
    output_config: { effort: Anthropic::OutputConfig::Effort::HIGH },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

## Lista de verificação de migração por modelo de origem

Percorra os grupos de cima para baixo e pare após aquele que nomeia o seu modelo. No Claude Haiku 4.5, aplique todos os grupos, exceto "Claude Sonnet 4 ou anterior", terminando com "Somente Claude Haiku 4.5".

### Todos os modelos de origem

* Altere o ID do modelo para `claude-sonnet-5-5`.
* [Leia os blocos de conteúdo por `type`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-in-responses) e devolva os blocos `thinking` sem alterações.
* Para continuar executando sem pensamento antecipado, envie [a configuração de pensamento mais baixa](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking) com esforço `high` ou inferior.
* Substitua o [uso forçado de ferramentas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#forced-tool-use) por `auto` e ferramentas estritas, ou apenas por `auto` no Amazon Bedrock.
* Mantenha as conversas [somente com acréscimos](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-blocks).
* Na Claude API e no Google Cloud, migre o uso do computador para o [toolset](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#computer-use-toolset), sem o cabeçalho beta `fine-grained-tool-streaming-2025-05-14`.
* Combine a [ferramenta advisor](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#advisor-tool) com um advisor compatível e espere conselhos criptografados.
* Leia o [texto entre chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#text-between-tool-calls) a partir dos blocos `thinking`.
* [Lide com recusas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#safety-classifiers-and-fallback) e configure o fallback.
* [Execute novamente sua varredura de esforço](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#recommended-changes) e restabeleça a linha de base de custo.

### Claude Sonnet 4.6 ou anterior

* Espere [pensamento em solicitações sem o campo `thinking`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-on-by-default) e revise `max_tokens`.
* Substitua os [orçamentos de pensamento](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#sonnet-46-breaking-changes) por um nível de esforço.
* Remova valores não padrão de `temperature`, `top_p` e `top_k`.
* Se você [exibe o texto do pensamento](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-in-responses), defina `display: "summarized"`.
* [Reconte os tokens](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-4-6) e refaça o orçamento de tokens de imagem.

### Claude Sonnet 4.5 ou anterior

* Substitua os [preenchimentos prévios do assistente](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45).
* Analise a entrada das chamadas de ferramentas com um parser JSON padrão.
* No Amazon Bedrock, migre o uso do computador de `computer_20250124` para [`computer_20251124`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#computer-use-toolset).
* Defina `output_config.effort` explicitamente.
* Remova qualquer cabeçalho beta de janela de contexto.
* Remova `interleaved-thinking-2025-05-14` e substitua `fine-grained-tool-streaming-2025-05-14` por `eager_input_streaming`.
* Mova `output_format` para `output_config.format`.

### Claude Sonnet 4 ou anterior

* Atualize as [versões das ferramentas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-4-or-earlier) para `text_editor_20250728` e `code_execution_20260521`.
* Trate os motivos de parada `refusal` e `model_context_window_exceeded`.
* Verifique se há quebras de linha finais nos parâmetros de string das ferramentas.
* Remova `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`.
* Revise seus prompts.

### Somente Claude Haiku 4.5

* Substitua [`claude-haiku-4-5-20251001`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migrating-from-claude-haiku-4-5) ou seu alias.
* Restabeleça a linha de base de custos com o preço por token mais alto.
* Revise os prompts que eram curtos demais para cache no Claude Haiku 4.5.

## Migrando para o Claude Sonnet 5.5 a partir do Claude Sonnet 5

Todos os modelos de origem precisam das alterações desta seção. Substitua o ID do seu modelo por `claude-sonnet-5-5`, que não tem sufixo de data. Em outras plataformas, use o ID listado em [Disponibilidade](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/whats-new-sonnet-5-5#availability).

### O uso forçado de ferramentas não é suportado

Todos os modelos anteriores desta página aceitam um `tool_choice` do tipo `any` ou `tool`. O Claude Sonnet 5.5 rejeita ambos com um erro 400, inclusive no endpoint de [contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting):

```text wrap
tool_choice: type "tool" and "any" are not supported for this model.
```

Envie `tool_choice: {"type": "auto"}` e marque a ferramenta com `strict: true` para que sua entrada corresponda ao schema. O modelo pode então responder sem chamar a ferramenta, então diga no prompt quando usá-la. O [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) suporta um subconjunto do JSON Schema e exige `additionalProperties: false` em todos os objetos. 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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs), que incluem o uso estrito de ferramentas, não estão disponíveis para o Claude Sonnet 5.5. Lá, envie `auto` sem `strict`, diga no prompt quando chamar a ferramenta e valide a entrada da ferramenta no seu código.

Antes (Claude Sonnet 5):

<CodeGroup>
  ```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-sonnet-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-sonnet-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-sonnet-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-sonnet-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.ClaudeSonnet5,
      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.ModelClaudeSonnet5,
  	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_SONNET_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_SONNET_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_SONNET_5,
    max_tokens: 1024,
    tools: tools,
    tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
    messages: [{ role: "user", content: "What's the weather in Paris?" }]
  )
  ```
</CodeGroup>

Depois (Claude Sonnet 5.5):

<CodeGroup>
  ```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-sonnet-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-sonnet-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-sonnet-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-sonnet-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.ClaudeSonnet5_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.ModelClaudeSonnet5_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_SONNET_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_SONNET_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_SONNET_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." }
    ]
  )
  ```
</CodeGroup>

O exemplo marca todas as ferramentas da lista como estritas. Uma solicitação pode ter no máximo 20 ferramentas estritas, e as entradas de toolset de MCP, uso do computador e uso do navegador não aceitam `strict`. Em uma lista de ferramentas mais longa, marque apenas as ferramentas que precisam disso.

### Os blocos de pensamento estão vinculados ao modelo e à conversa

O Claude Sonnet 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores e, na Claude API e no Google Cloud, do Claude Haiku 5.5. Ele não lê blocos do Claude Opus 5, Claude Opus 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. A API descarta os blocos que o modelo não consegue ler. A solicitação ainda retorna 200, e os blocos descartados não são cobrados. Consulte [Trocar de modelo no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#switching-models).

Cada bloco de pensamento do Claude Sonnet 5.5 também é assinado sobre a conversa que o precede. Para contas criadas em ou após 31 de agosto de 2026, 00:00 UTC, a API aplica isso por padrão, na Claude API, no Amazon Bedrock e no Google Cloud. Nessas contas, uma solicitação que reenvia um bloco após uma edição no histórico anterior retorna um erro 400. Mantenha as conversas somente com acréscimos e altere instruções ou ferramentas com [mensagens do sistema no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages). Os blocos de pensamento que o Claude Sonnet 5.5 produz funcionam apenas na conta que os produziu ou em uma conta vinculada a ela. Consulte [Pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#account-bound-thinking).

### O uso do computador exige o toolset na API do Claude e no Google Cloud

Na API do Claude e no Google Cloud, o Claude Sonnet 5.5 suporta o uso do computador apenas por meio do toolset `computer_toolset_20260801`. Nessas plataformas, `computer_20251124` retorna um erro 400. O Claude Sonnet 5.5 não aceita `computer_20250124` em nenhuma plataforma. Encontre a versão que você envia hoje:

| Versão que você envia hoje | Modelos de origem que a enviam                       | Envie na API do Claude e no Google Cloud | Envie no Amazon Bedrock |
| -------------------------- | ---------------------------------------------------- | ---------------------------------------- | ----------------------- |
| `computer_20251124`        | Claude Sonnet 5, Claude Sonnet 4.6                   | `computer_toolset_20260801`              | `computer_20251124`     |
| `computer_20250124`        | Claude Sonnet 4.5, Claude Haiku 4.5, Claude Sonnet 4 | `computer_toolset_20260801`              | `computer_20251124`     |

Se você envia o cabeçalho beta `fine-grained-tool-streaming-2025-05-14`, remova-o ao migrar para o toolset. Junto com uma entrada de toolset, ele retorna um erro 400. Em vez disso, defina `eager_input_streaming: true` em cada ferramenta que precisar.

Código que já envia o toolset não precisa de alterações. [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 na solicitação e no loop do agente. Para outras plataformas, consulte [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#compatibility).

### A ferramenta advisor aceita menos advisors

Com a [ferramenta advisor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool), um executor Claude Sonnet 5.5 precisa de um destes advisors: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5 ou Claude Mythos 5.1. Advisors Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 e Claude Haiku 5.5 retornam um erro 400. O conselho retorna criptografado como um bloco `advisor_redacted_result`, então seu texto não é legível na resposta. Consulte [Compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility).

### O texto entre chamadas de ferramentas é retornado em blocos de pensamento

No Claude Sonnet 5.5, as notas com mais de uma ou duas frases que o modelo escreve entre chamadas de ferramentas retornam como [blocos `thinking` de atualização de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates), vazios com o `display` padrão. Comentários mais curtos continuam como `text`. No Claude Sonnet 5 e modelos anteriores, todo o texto entre chamadas de ferramentas retorna como blocos `text`. Nenhuma solicitação falha, mas uma interface que exibe essas notas fica em silêncio.

Com o pensamento adaptativo, defina `display` como `"updates"` (beta, cabeçalho `thinking-display-updates-2026-08-18`) para obter apenas as atualizações, ou como `"summarized"` para obtê-las misturadas com o raciocínio. Renderize cada bloco `thinking` não vazio antes do bloco `tool_use` que o segue. Com [`between_tools`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking), o texto retorna sem `display`. Consulte [Atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates).

### Classificadores de segurança e fallback

O Claude Sonnet 5.5 recusa em mais categorias do que o Claude Sonnet 5. Uma recusa retorna `stop_reason: "refusal"`, e seu `stop_details` pode indicar uma destas [categorias](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#refusal-response):

* **`"cyber"`:** A solicitação poderia possibilitar danos cibernéticos, como o desenvolvimento de malware ou exploits.
* **`"bio"`:** A solicitação poderia possibilitar danos biológicos, como métodos laboratoriais perigosos.
* **`"frontier_llm"`:** A solicitação poderia auxiliar o desenvolvimento de modelos de IA concorrentes.
* **`"reasoning_extraction"`:** A solicitação pede ao modelo que reproduza seu raciocínio interno no texto da resposta.
* **`"general_harms"`:** A solicitação se enquadra em outra área da política de uso. Trabalhos benignos também podem acionar essa categoria.

O [fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback) (`fallbacks: "default"`, beta, somente na API do Claude) tenta novamente as recusas `"cyber"` e `"frontier_llm"` no Claude Sonnet 5. Ele não tenta novamente as recusas `"bio"`, `"reasoning_extraction"` ou `"general_harms"`. Consulte [Recusas e fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback) e [Como as recusas são cobradas](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#how-refusals-are-billed).

As salvaguardas cibernéticas em tempo real são novidade para código vindo do Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5. Para trabalhos legítimos 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).

### Outras alterações

* **"Prompt caching" (cache de prompt):** O prompt mínimo armazenável em cache é de 512 tokens, abaixo dos 1.024 no Claude Sonnet 5, Claude Sonnet 4.6 e Claude Sonnet 4.5. Consulte [Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#cache-limitations).
* **Novos recursos:** Para mensagens do sistema no meio da conversa, alterações de ferramentas no meio da conversa e esforço por mensagem, consulte [Novidades do Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/whats-new-sonnet-5-5#feature-support). Com [`between_tools`](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking), o esforço não pode mudar no meio da conversa.

### Alterações recomendadas

Execute novamente sua varredura de esforço. O Claude Sonnet 5.5 tem cinco níveis de esforço: `low`, `medium`, `high`, `xhigh` e `max`. O padrão na API do Claude é `high`. Os níveis foram recalibrados, portanto um nível não produz a mesma quantidade de pensamento que no Claude Sonnet 5. Comece em `high`, a menos que sua carga de trabalho seja agêntica ou sensível à "latency" (latência). Para programação agêntica e uso de ferramentas em várias etapas, comece em `medium` para tarefas bem especificadas e passe para `high` para tarefas mais difíceis ou mais longas. Para chat e outros trabalhos sensíveis à latência, comece em `medium` ou `low`. Defina o nível em `output_config.effort`. Consulte [Níveis de esforço recomendados para o Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#recommended-effort-levels-for-claude-sonnet-5-5). Em seguida, reavalie as instruções de prompt específicas do modelo com base em [Criando prompts para o Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5).

## Migrando para o Claude Sonnet 5.5 a partir do Claude Sonnet 4.6 e modelos Sonnet anteriores

Primeiro, aplique todas as seções anteriores, substituindo `claude-sonnet-4-6`. Depois, faça estas alterações. No Claude Sonnet 4.5 ou anterior, continue com as subseções a seguir.

### Alterações incompatíveis

**O pensamento é executado em solicitações que o omitiam.** Consulte [O pensamento é executado por padrão](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-on-by-default) e [Desative o pensamento antecipado](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#turn-off-up-front-thinking).

**Orçamentos de pensamento retornam um erro.** O Claude Sonnet 4.6 aceita `thinking: {"type": "enabled", "budget_tokens": N}` como uma configuração descontinuada. O Claude Sonnet 4.5 e o Claude Haiku 4.5 a usam para todo o pensamento. O Claude Sonnet 5.5 retorna um erro 400:

```text wrap
"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
```

Remova o orçamento e defina um nível de [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort). Não há um mapeamento fixo de um orçamento para um nível de esforço, então execute suas avaliações em dois ou três níveis.

Antes (Claude Sonnet 4.6):

<CodeGroup>
  ```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-sonnet-4-6",
      "max_tokens": 16000,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=16000,
      thinking={"type": "enabled", "budget_tokens": 10000},
      messages=[{"role": "user", "content": "..."}],
  )
  ```

  ```typescript TypeScript
  await client.messages.create({
    model: "claude-sonnet-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.ClaudeSonnet4_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.ModelClaudeSonnet4_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_SONNET_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-sonnet-4-6',
      thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: {
      type: "enabled",
      budget_tokens: 10000
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

Depois (Claude Sonnet 5.5):

<CodeGroup>
  ```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-sonnet-5-5",
      "max_tokens": 16000,
      "thinking": {
        "type": "adaptive"
      },
      "output_config": {
        "effort": "high"
      },
      "messages": [
        {
          "role": "user",
          "content": "..."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-sonnet-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
  output_config:
    effort: high
  messages:
    - role: user
      content: "..."
  YAML
  ```

  ```python Python
  client.messages.create(
      model="claude-sonnet-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-sonnet-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.ClaudeSonnet5_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.ModelClaudeSonnet5_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_SONNET_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-sonnet-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-sonnet-5-5",
    max_tokens: 16000,
    thinking: {
      type: "adaptive"
    },
    output_config: {
      effort: "high" # or "max", "xhigh", "medium", "low"
    },
    messages: [
      { role: "user", content: "..." }
    ]
  )
  ```
</CodeGroup>

**Parâmetros de amostragem retornam um erro.** O Claude Sonnet 4.6 e modelos anteriores, e o Claude Haiku 4.5, aceitam `temperature`, `top_p` e `top_k`. No Claude Sonnet 5.5, um valor não padrão retorna um erro 400. Remova-os.

**O texto do pensamento é omitido por padrão.** Consulte [Trate o pensamento nas respostas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#thinking-in-responses).

### Outras alterações

* **Cerca de 30% mais tokens:** O Claude Sonnet 5.5 usa o tokenizador do Claude Sonnet 5. Em comparação com o Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5, o mesmo texto produz cerca de 30% mais tokens, dependendo do conteúdo. Reconte com a [contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) e revise `max_tokens` e os custos.
* **Esforço:** `xhigh` é novo, e os níveis foram recalibrados. Consulte [Alterações recomendadas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#recommended-changes).
* **Imagens:** O Claude Sonnet 5.5 usa o nível de imagem de alta resolução, com até 2576 pixels no lado maior e 4.784 tokens visuais por imagem. O Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 param em 1568 pixels e 1.568 tokens. Uma imagem de 2000×1500 custa cerca de 2,5 vezes mais tokens no Claude Sonnet 5.5. Consulte [Resolução e custo em tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size).

### Migrando a partir do Claude Sonnet 4.5 ou anterior

No Claude Sonnet 4.5, Claude Sonnet 4 ou Claude 3.7 Sonnet, primeiro aplique todas as seções anteriores e depois estas alterações.

**O prefill retorna um erro.** O Claude Sonnet 5.5 rejeita um último turno do assistente preenchido previamente com um erro 400, assim como o Claude Sonnet 4.6 e o Claude Sonnet 5. O Claude Sonnet 4.5, o Claude Haiku 4.5 e modelos mais antigos o aceitam. O erro diz:

```text wrap
This model does not support assistant message prefill. The conversation must end with a user message.
```

Substitua cada prefill de acordo com sua finalidade:

* **Formato de saída:** use [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) ou ferramentas com campos enum para classificação. No Amazon Bedrock, as saídas estruturadas não estão disponíveis para o Claude Sonnet 5.5. Nessa plataforma, descreva o formato no prompt ou use uma ferramenta sem `strict`, e valide a saída no seu código.
* **Preâmbulos:** peça no prompt do sistema uma resposta direta.
* **Recusas indesejadas:** instruções claras na mensagem do usuário geralmente são suficientes.
* **Continuações:** mova-as para a mensagem do usuário, por exemplo "Sua resposta anterior foi interrompida e terminou com `[previous_response]`. Continue de onde parou."
* **Lembretes de contexto:** coloque-os no turno do usuário.

**Escape na entrada de ferramentas.** O escape nos argumentos das chamadas de ferramentas pode ser diferente. Analise `input` com um parser JSON padrão.

**Uso do computador.** O Claude Sonnet 5.5 não aceita `computer_20250124`. Consulte a [tabela de uso do computador](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#computer-use-toolset).

**Esforço.** O Claude Sonnet 4.5 não tem parâmetro de esforço. Defina um nível de esforço explicitamente, conforme descrito em [Alterações recomendadas](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#recommended-changes).

**Contexto e saída.** O Claude Sonnet 5.5 tem uma janela de contexto maior, sem cabeçalho beta, e um limite de saída mais alto. Consulte a [página do modelo](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/overview). Remova qualquer cabeçalho beta de janela de contexto.

**Cabeçalhos beta.** Remova `interleaved-thinking-2025-05-14`, já que o pensamento adaptativo é intercalado automaticamente. Substitua `fine-grained-tool-streaming-2025-05-14` por `eager_input_streaming: true` em cada ferramenta que precisar. Esse cabeçalho retorna um erro 400 junto com uma entrada de toolset de uso do computador ou uso do navegador. Consulte [Streaming de ferramentas de granularidade fina](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/fine-grained-tool-streaming).

**Saídas estruturadas.** 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. Use `output_config.format` em vez disso.

### Migrando a partir do Claude Sonnet 4 ou anterior

O Claude Sonnet 4 está desativado na API do Claude e ainda disponível no Amazon Bedrock e no Google Cloud. O Claude 3.7 Sonnet está desativado. A partir de qualquer um desses modelos, primeiro aplique todas as seções anteriores e depois estas alterações:

* **Versões das ferramentas:** Use `text_editor_20250728`, com o nome de ferramenta `str_replace_based_edit_tool` e sem o comando `undo_edit`. Use `code_execution_20260521`. Consulte a [ferramenta de editor de texto](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool) e a [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).
* **Motivos de parada:** Trate `refusal`. O Claude 4.5 e modelos posteriores também param com `model_context_window_exceeded` no limite da janela de contexto. Consulte [Tratando motivos de parada](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons).
* **Quebras de linha finais:** O Claude 4.5 e modelos posteriores as mantêm nos parâmetros de string das chamadas de ferramentas.
* **Cabeçalhos beta legados:** Remova `token-efficient-tools-2025-02-19` e `output-128k-2025-02-19`.
* **Prompts:** Revise-os com base nas [melhores práticas de prompts](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/claude-prompting-best-practices).

## Migrando para o Claude Sonnet 5.5 a partir do Claude Haiku 4.5

Primeiro, aplique todas as seções até [Migrando a partir do Claude Sonnet 4.5 ou anterior](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#migrating-from-sonnet-45), inclusive, pulando a subseção do Claude Sonnet 4. Depois, faça estas alterações:

* **ID do modelo:** Substitua `claude-haiku-4-5-20251001`, ou o alias `claude-haiku-4-5`, por `claude-sonnet-5-5`.
* **Custo:** O preço por token é mais alto, e o mesmo texto produz mais tokens. Reconte os tokens e restabeleça a linha de base de custos. Consulte [Preços do Claude](https://platform.claude.com/docs/pt-BR/about-claude/pricing).
* **Cache de prompt:** O prompt mínimo armazenável em cache cai de 4.096 tokens para o [mínimo do Claude Sonnet 5.5](https://platform.claude.com/docs/pt-BR/models/sonnet-5-5/migration-guide#other-changes-from-claude-sonnet-5).
* **Pensamento intercalado:** O pensamento adaptativo é executado entre chamadas de ferramentas automaticamente, sem cabeçalho beta.
* **Roteamento:** O Claude Sonnet 5.5 lê blocos de pensamento do Claude Haiku 4.5. Uma conversa que sobe de modelo mantém seu raciocínio. Uma que volta para o Claude Haiku 4.5 descarta os blocos do Claude Sonnet 5.5.