Pensamento

Um modelo que responde em uma única passagem precisa acertar tudo na primeira tentativa: sem rascunho, sem verificação, sem mudar de rumo no meio do caminho. Para uma prova, um bug complicado ou uma tarefa agêntica longa, a primeira abordagem muitas vezes não é a melhor.

O pensamento remove essa restrição. Quando o pensamento está ativo, Claude trabalha o problema em suas próprias palavras antes de responder: ele reformula o que está sendo perguntado, tenta abordagens, verifica resultados intermediários e abandona caminhos que não se sustentam. Esse raciocínio chega em blocos de conteúdo thinking antes da resposta, e Claude se baseia nele para produzir a resposta final. É por isso que o pensamento melhora o desempenho em tarefas complexas como matemática, programação, análise e trabalho agêntico de longa duração, onde a qualidade da resposta depende de trabalho intermediário que, de outra forma, seria comprimido na própria resposta ou ignorado.

O pensamento tem um custo: os tokens que Claude gasta raciocinando são cobrados como tokens de saída, mesmo quando o texto de pensamento não é retornado para você, e eles contam para max_tokens junto com o texto da resposta. Esta página cobre como o pensamento se comporta em toda a superfície da API: ativá-lo, ler sua saída e gerenciar suas interações com ferramentas, streaming, cache e a janela de contexto.



Como o pensamento funciona

Se Claude pensa em uma determinada solicitação, e com que profundidade, depende da sua configuração de pensamento e da complexidade da solicitação.

Veja como o pensamento aparece em uma resposta: um ou mais blocos de conteúdo thinking chegam antes dos blocos text. O bloco de pensamento ainda é conteúdo gerado, como o bloco text que o segue, mas é separado da resposta canônica. Cada bloco de pensamento também carrega um campo signature, uma cópia criptografada do raciocínio completo que você passa de volta sem alterações em conversas de múltiplos turnos e com uso de ferramentas (consulte Criptografia do pensamento):

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Você nem sempre vê esse texto, e o que você vê nunca é a cadeia de pensamento bruta: o texto em um bloco de pensamento é um resumo do raciocínio do Claude. O campo display na configuração de pensamento controla se esse resumo é retornado: "summarized" o retorna, enquanto "omitted", o padrão nos modelos mais recentes, retorna blocos de pensamento com um campo thinking vazio. De qualquer forma, o bloco é cobrado da mesma maneira e passado de volta da mesma maneira em conversas de múltiplos turnos; consulte Controlando a exibição do pensamento para padrões por modelo e detalhes.

Se Claude usa ferramentas, o pensamento também pode aparecer entre chamadas de ferramentas; consulte Pensamento com uso de ferramentas. Para o formato completo da resposta, consulte a referência da API de Messages.



Configurando o pensamento

Nos modelos atuais, o pensamento está ativado por padrão ou a um parâmetro de distância. Qual configuração cada modelo aceita, e qual é o padrão, está listado na tabela de configuração por modelo na página de Solução de problemas.

No Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, o pensamento já está ativado: nenhuma configuração é necessária. A primeira coisa que a maioria dos desenvolvedores precisa nesses modelos é ver o texto de pensamento, já que display tem como padrão "omitted" neles. Opte por isso com thinking: {"type": "adaptive", "display": "summarized"}, que é exatamente a solicitação a seguir com a string do modelo trocada.

No Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, o pensamento está desativado até que você defina thinking: {type: "adaptive"} na sua solicitação. Os exemplos a seguir fazem isso, definem display: "summarized" para que o texto de pensamento fique visível e usam um max_tokens espaçoso:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Executar o exemplo imprime o pensamento resumido e, em seguida, a resposta:

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

Os tokens de pensamento contam para max_tokens, então defina-o alto o suficiente para deixar espaço tanto para o pensamento quanto para o texto da resposta. Consulte Controle de custos na página de direcionamento e Pensamento e a janela de contexto.



Desativando o pensamento

No Claude Sonnet 5, onde o pensamento está ativado por padrão, você pode desativá-lo:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

O Claude Opus 5 também tem o pensamento ativado por padrão e aceita thinking: {type: "disabled"} com effort high ou inferior. Com effort xhigh ou max, o pensamento não pode ser desativado: solicitações que combinam thinking: {type: "disabled"} com esses níveis de effort retornam um erro 400. Essa restrição se aplica ao Claude Opus 5 e modelos posteriores e é aplicada em cada solicitação. Com o pensamento desativado, o Claude Opus 5 pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível; consulte Executando com pensamento desativado para mitigações via prompting.

Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview rejeitam thinking: {type: "disabled"}: o pensamento não pode ser desativado nesses modelos.

Se o seu modelo suporta apenas pensamento estendido (consulte a tabela de configuração por modelo), configure-o com type: "enabled" e um valor de budget_tokens em vez disso; a página de Pensamento estendido cobre essa configuração. E se qualquer configuração de pensamento retornar um erro 400, Solução de problemas de pensamento relaciona cada mensagem de erro à sua correção.



Lendo a saída de pensamento



Controlando a exibição do pensamento

O campo display na configuração de pensamento controla como o conteúdo de pensamento é retornado nas respostas da API. display funciona em ambos os modos: defina-o junto com type: "adaptive" ou type: "enabled". Ele aceita dois valores:

• "summarized": os blocos de pensamento contêm texto de pensamento resumido, um resumo legível do raciocínio do Claude. Este é o padrão no Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores.
• "omitted": os blocos de pensamento são retornados com um campo thinking vazio. O campo signature ainda carrega o pensamento completo criptografado para continuidade em múltiplos turnos (consulte Criptografia do pensamento). Este é o padrão no Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview.

Defina display: "omitted" quando sua aplicação não exibe conteúdo de pensamento aos usuários. O principal benefício é um tempo até o primeiro token de texto mais rápido ao fazer streaming: o servidor pula completamente o streaming dos tokens de pensamento e entrega apenas a assinatura, então a resposta de texto final começa a ser transmitida mais cedo.

Com display: "omitted", a resposta contém blocos thinking com um campo thinking vazio:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Tenha o seguinte em mente ao trabalhar com pensamento omitido:

• Você ainda é cobrado pelos tokens de pensamento completos. Omitir reduz a latência, não o custo.
• Se você passar blocos de pensamento de volta em conversas de múltiplos turnos, passe-os sem alterações. O servidor descriptografa a signature para reconstruir o pensamento original para a construção do prompt (consulte Preservando blocos de pensamento). Qualquer texto que você coloque no campo thinking de um bloco omitido reenviado é ignorado.
• display é inválido com thinking.type: "disabled" (não há nada para exibir).
• Ao usar thinking.type: "adaptive" e o modelo pular o pensamento para uma solicitação simples, nenhum bloco de pensamento é produzido, independentemente de display.
• Ao fazer streaming com display: "omitted", nenhum evento thinking_delta é emitido; consulte Streaming de pensamento para a sequência de eventos.

No SDK de Ruby, defina este campo como display_: (com um sublinhado no final) para evitar sobrepor o Kernel#display do Ruby; o campo na transmissão ainda é display.



Pensamento resumido

Quando display é "summarized", o texto de pensamento que você recebe é um resumo do processo completo de pensamento do Claude, em vez da cadeia de pensamento bruta. O pensamento resumido fornece todos os benefícios de inteligência do pensamento enquanto previne uso indevido. Nenhuma configuração de display retorna a cadeia de pensamento bruta.

Tenha o seguinte em mente ao trabalhar com pensamento resumido:

• Você é cobrado pelos tokens de pensamento completos gerados pela solicitação original, não pelos tokens do resumo. A contagem de tokens de saída cobrada não corresponde à contagem de tokens que você vê na resposta.
• No Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores, as primeiras linhas da saída de pensamento são mais detalhadas, fornecendo raciocínio detalhado que é particularmente útil para fins de engenharia de prompt. O Claude Mythos Preview resume desde o primeiro token, então seus blocos de pensamento não mostram esse preâmbulo detalhado.
• A sumarização preserva as ideias-chave do processo de pensamento do Claude com latência adicional mínima, permitindo uma experiência de usuário transmissível via streaming.
• A sumarização é processada por um modelo diferente daquele que você especifica em suas solicitações. O modelo de pensamento não vê a saída resumida.
• À medida que a Anthropic busca melhorar o recurso de pensamento, o comportamento de sumarização está sujeito a alterações.



Streaming de pensamento

O pensamento funciona com streaming. Os blocos de pensamento são transmitidos como eventos thinking_delta dentro de eventos content_block_delta, seguidos por um único evento signature_delta logo antes do content_block_stop do bloco. Os blocos de texto são transmitidos depois, como de costume.

Os exemplos a seguir transmitem uma resposta com pensamento adaptativo, imprimindo deltas de pensamento e texto conforme chegam:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Quando display: "omitted" está definido, o bloco de pensamento abre, um único signature_delta chega e o bloco fecha sem nenhum evento thinking_delta. O streaming de texto começa imediatamente depois:

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

Para a mecânica geral de streaming, consulte Streaming de Messages.



Pensamento e effort

O parâmetro thinking controla se Claude pensa em blocos de pensamento antes de responder; o parâmetro effort controla quanto trabalho Claude dedica à resposta como um todo, o que no modo adaptativo inclui com que frequência e com que profundidade ele pensa. Não passe adaptive como um valor de effort: adaptive é um modo de pensamento, não um nível de esforço.

Para o que cada nível de effort faz com o comportamento de pensamento, consulte a tabela de comportamento de pensamento por nível na página Direcionando o pensamento; a página de Effort documenta o parâmetro em si, incluindo quais níveis cada modelo suporta. No Claude Opus 4.5, o único modelo exclusivamente de pensamento estendido que suporta effort, o effort se compõe com budget_tokens; consulte Regras e ajuste de orçamento.

Com os dois controles separados dessa forma, escolha aquele que corresponde ao seu objetivo:

• Menor custo ou latência em uma carga de trabalho com pensamento habilitado: reduza o effort primeiro. Ele reduz a escala de toda a resposta, incluindo o pensamento.
• Claude está pensando com pouca frequência ou de forma muito superficial: aumente o effort, ou consulte Direcionando a frequência com que Claude pensa na página de direcionamento.
• Você precisa do pensamento totalmente desativado: use thinking: {type: "disabled"} em modelos que o permitem (consulte a tabela de configuração por modelo).
• Você precisa de um teto rígido de gastos: use max_tokens. Effort é uma orientação flexível; max_tokens é um limite estrito.



Pensamento com uso de ferramentas

O pensamento funciona junto com o uso de ferramentas, permitindo que Claude raciocine sobre a seleção de ferramentas e processe os resultados das ferramentas. Duas restrições se aplicam:

1. Limitação de escolha de ferramenta (modo manual): o uso de ferramentas com pensamento estendido manual (thinking: {type: "enabled"}) suporta apenas tool_choice: {"type": "auto"} (o padrão) ou tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} resulta em um erro porque essas opções forçam o uso de ferramentas, o que é incompatível com o pensamento estendido manual. O pensamento adaptativo, incluindo em modelos onde o pensamento está ativado por padrão, suporta uso forçado de ferramentas.
2. Preservando blocos de pensamento: quando você retorna resultados de ferramentas, você deve passar os blocos de pensamento da mensagem do assistente de volta para a API, completos e sem modificações. Consulte Preservando blocos de pensamento.

Um loop de uso de ferramentas é um único turno do assistente. Da perspectiva do modelo, um turno do assistente não é concluído até que Claude termine sua resposta completa, que pode incluir múltiplas chamadas de ferramentas e resultados. Toda essa sequência é um único turno do assistente:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

O turno inteiro é executado em um único modo de pensamento: você não pode alternar o pensamento no meio de um turno, incluindo durante o loop de uso de ferramentas. No modo estendido (manual), a API adicionalmente exige que o turno final do assistente de uma solicitação com pensamento habilitado comece com um bloco de pensamento. O modo adaptativo relaxa isso: nenhum turno do assistente precisa começar com um.

Conflitos no meio do turno degradam graciosamente. Se você alternar o pensamento no meio do turno (por exemplo, entre enviar uma chamada de ferramenta e retornar seu resultado), a API não gera erro. Em vez disso, ela desativa silenciosamente o pensamento para essa solicitação. Para preservar a qualidade do modelo, a API pode remover blocos de pensamento que criariam uma estrutura de turno inválida, ou desativar o pensamento quando o histórico da conversa é incompatível com o pensamento estar habilitado. Para confirmar se o pensamento estava ativo, verifique a presença de blocos thinking na resposta.

Alterne entre turnos, não dentro deles. Planeje sua estratégia de pensamento no início de cada turno. Complete o turno do assistente e, em seguida, altere a configuração de pensamento para o próximo:

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

Observe que alternar modos de pensamento também invalida o cache de prompt; consulte Pensamento e cache de prompt.



Preservando blocos de pensamento

Quando Claude invoca uma ferramenta, ele pausa a construção de sua resposta para aguardar informações externas. Quando você retorna o resultado da ferramenta, Claude continua construindo essa mesma resposta, então seu raciocínio anterior ainda deve estar presente. Passe cada bloco thinking de volta para a API completo e sem modificações, junto com o bloco tool_use que o acompanhava. Isso é importante por duas razões:

1. Continuidade do raciocínio: os blocos de pensamento capturam o raciocínio passo a passo que levou às solicitações de ferramentas. Incluí-los permite que Claude continue raciocinando de onde parou.
2. Manutenção do contexto: os resultados de ferramentas aparecem como mensagens do usuário na estrutura da API, mas fazem parte de um fluxo contínuo de raciocínio. Preservar os blocos de pensamento mantém esse fluxo entre chamadas de API.

Em resumo:

• Obrigatório: dentro de um turno de uso de ferramentas, passe os blocos de pensamento de volta.
• Recomendado: entre turnos, passe tudo de volta.
• Permitido: fora do uso de ferramentas, omita o pensamento de turnos anteriores.

Você não precisa podar o pensamento antigo por conta própria. Passe todos os blocos de pensamento de volta em conversas de múltiplos turnos, e a API os filtra automaticamente, mantém os blocos necessários para preservar o raciocínio do modelo e cobra tokens de entrada apenas pelos blocos realmente mostrados ao Claude. Quais blocos de turnos anteriores são mantidos depende do modelo; consulte Preservação de blocos de pensamento por modelo. Para substituir o padrão, use a estratégia de edição de contexto clear_thinking_20251015.

Dentro da mensagem mais recente do assistente, a sequência de blocos thinking consecutivos deve corresponder ao que o modelo gerou na solicitação original: você não pode reorganizá-los, editá-los ou descartá-los parcialmente. Isso inclui blocos redacted_thinking.

Para um passo a passo completo de dois turnos com código em cada SDK, consulte Pensamento em fluxos de trabalho com ferramentas e múltiplos turnos. Ele define uma ferramenta, recebe uma resposta de pensamento mais uso de ferramentas e ecoa o turno do assistente de volta com o resultado da ferramenta.



Pensamento intercalado

O pensamento intercalado permite que Claude pense entre chamadas de ferramentas, raciocinando sobre cada resultado de ferramenta antes de agir sobre ele. Com o pensamento intercalado, Claude pode:

• Raciocinar sobre os resultados de uma chamada de ferramenta antes de decidir o que fazer em seguida
• Encadear múltiplas chamadas de ferramentas com etapas de raciocínio entre elas
• Tomar decisões mais refinadas com base em resultados intermediários

Com o pensamento adaptativo, o pensamento intercalado é automático em todos os modelos que suportam pensamento adaptativo; nenhum cabeçalho beta é necessário. No Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.7, o raciocínio entre chamadas de ferramentas sempre aparece em blocos de pensamento. O Claude Haiku 4.5 não suporta pensamento intercalado. Em modelos que usam pensamento estendido manual, a intercalação requer um cabeçalho beta e muda como o orçamento de pensamento é contado; Pensamento intercalado no modo manual cobre as regras por modelo e o comportamento do cabeçalho específico de cada plataforma.

Com o pensamento intercalado, a alocação de pensamento pode abranger todo o turno do assistente em vez de uma única resposta. O pensamento intercalado é suportado apenas para ferramentas usadas através da API de Messages.

Para uma comparação detalhada mostrando o que o pensamento intercalado muda em um fluxo de trabalho com duas ferramentas, consulte Como o pensamento intercalado muda o fluxo.



Preservação de blocos de pensamento por modelo

Se os blocos de pensamento de turnos anteriores do assistente permanecem no contexto por padrão depende do modelo:

• Mantêm todos os turnos anteriores: Claude Opus 4.5 e modelos Opus posteriores, Claude Sonnet 4.6 e modelos Sonnet posteriores, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview.
• Mantêm apenas o último turno: modelos Opus e Sonnet anteriores, e todos os modelos Haiku até o Claude Haiku 4.5. Quando você passa blocos de pensamento mais antigos de volta, a API os remove automaticamente; você não precisa removê-los por conta própria.

A preservação traz dois benefícios:

• Otimização de cache: blocos de pensamento preservados permitem acertos de cache durante o uso de ferramentas, pois são passados de volta com os resultados das ferramentas e armazenados em cache incrementalmente ao longo do turno do assistente, resultando em economia de tokens em fluxos de trabalho de múltiplas etapas.
• Sem impacto na inteligência: preservar blocos de pensamento não tem efeito negativo no desempenho do modelo.

A contrapartida é o uso de contexto: conversas longas consomem mais espaço de contexto em modelos que mantêm tudo, já que blocos de pensamento retidos contam como entrada como qualquer outro histórico de conversa (consulte Pensamento e a janela de contexto). O comportamento é automático em ambos os regimes; nenhuma alteração de código ou cabeçalho beta é necessária, e você deve continuar passando blocos de pensamento completos e não modificados de volta, conforme descrito em Preservando blocos de pensamento. Para substituir o padrão em qualquer direção, use a limpeza de blocos de pensamento.

Trocando de modelo no meio da conversa. Quando você alterna entre quaisquer dois modelos, por exemplo após um fallback de recusa do classificador, remova os blocos thinking e redacted_thinking dos turnos anteriores do assistente. Os blocos de pensamento estão vinculados ao modelo que os produziu. Outros modelos os ignoram silenciosamente em vez de rejeitar a solicitação, mas blocos ignorados ainda adicionam tokens de entrada.



Pensamento e cache de prompt

O cache de prompt interage com o pensamento de algumas maneiras específicas. As regras a seguir se aplicam em ambos os modos de pensamento.

Mudanças de configuração invalidam o cache. A configuração de pensamento e o nível de effort resolvido são renderizados no próprio prompt, então alterar qualquer um deles inicia um novo prefixo de cache. Alternar entre adaptive, enabled e disabled, alterar budget_tokens e alterar o valor de effort invalidam os pontos de interrupção do cache: pontos de interrupção no nível de mensagem sempre falham, e pontos de interrupção de ferramentas e de prompt do sistema também podem falhar, dependendo de onde o modelo renderiza a configuração. Trate qualquer mudança de pensamento ou effort como um reinício do cache. Solicitações consecutivas que mantêm a mesma configuração preservam o cache, e definir um parâmetro explicitamente com seu valor padrão é equivalente a omiti-lo. Uma demonstração detalhada com saída de uso está na página Direcionando o pensamento.

Blocos de pensamento são armazenados em cache com os resultados das ferramentas. Durante um loop de uso de ferramentas, o cache ocorre quando você faz uma solicitação de acompanhamento que inclui resultados de ferramentas. Nesse ponto, o histórico anterior da conversa, incluindo seus blocos de pensamento, pode ser armazenado em cache, e esses blocos de pensamento em cache contam como tokens de entrada em suas métricas de uso quando lidos do cache. Isso acontece automaticamente, mesmo sem marcadores cache_control explícitos, e se comporta da mesma forma para pensamento regular e intercalado. A contrapartida: blocos de pensamento que você nunca mais vê nas respostas ainda contribuem para o uso de tokens de entrada quando lidos do cache.

Se os blocos anteriores estão no contexto depende do modelo. O padrão de preservação governa isso. Em modelos que mantêm tudo, os blocos de pensamento de turnos anteriores permanecem em cache e no contexto. Em modelos que mantêm apenas o último turno, assim que você envia uma mensagem de usuário que não é um resultado de ferramenta, todos os blocos de pensamento anteriores são removidos do contexto. Nesses modelos, uma conversa como esta:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

é processada como se os blocos de pensamento nunca estivessem lá:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

Em modelos que mantêm tudo, a mesma solicitação mantém thinking_block_1 e thinking_block_2 no contexto e no cache.

A degradação remove o pensamento do histórico armazenável em cache. Se o pensamento for desativado no meio do turno e você passar conteúdo de pensamento no turno atual de uso de ferramentas, o conteúdo de pensamento é removido e o pensamento permanece desativado para essa solicitação (consulte degradação graciosa). O pensamento intercalado amplifica os efeitos de invalidação de cache, já que blocos de pensamento podem ocorrer entre múltiplas chamadas de ferramentas.



Pensamento e a janela de contexto

max_tokens, que inclui todo o pensamento que Claude gera no turno atual, é aplicado como um limite estrito. Nos modelos Claude 4.5 e mais recentes, se os tokens de entrada mais max_tokens excederem o tamanho da janela de contexto, a API aceita a solicitação; se a geração então atingir o limite da janela de contexto, ela para com stop_reason: "model_context_window_exceeded" em vez de retornar um erro. Em modelos anteriores, a API retorna um erro de validação. Consulte Lidando com razões de parada.

Como o pensamento conta contra a janela depende de quando ele foi gerado:

• Pensamento do turno atual sempre conta para max_tokens, é cobrado como tokens de saída e ocupa espaço na janela de contexto para o turno que o gerou.
• Pensamento de turnos anteriores depende do padrão de preservação. Em modelos que mantêm todos os turnos anteriores, os blocos de pensamento anteriores permanecem no contexto, contam para a janela e são cobrados como tokens de entrada como o restante do histórico da conversa. Em modelos que mantêm apenas o último turno, a API remove automaticamente os blocos de pensamento mais antigos quando você os passa de volta, então eles não consomem espaço na janela nem tokens de entrada.

Na prática:

• Em modelos que mantêm tudo, planeje sua janela de contexto como se o pensamento fosse histórico de conversa comum, porque ele é. Sessões agênticas longas acumulam pensamento no contexto; use a limpeza de blocos de pensamento se precisar recuperar espaço.
• Em modelos que mantêm apenas o último turno, o pensamento é um custo apenas por turno: o pensamento de cada turno conta contra o max_tokens daquele turno e depois sai da janela.

Os diagramas a seguir ilustram o regime de apenas último turno (remoção). O primeiro mostra uma conversa de múltiplos turnos: o bloco de pensamento de cada turno é gerado na saída, mas não é levado para a entrada de turnos posteriores.

O segundo mostra o mesmo regime com uso de ferramentas: o pensamento permanece no contexto junto com seu resultado de ferramenta durante o turno do assistente, depois sai no próximo turno do usuário.

Use a API de contagem de tokens para obter contagens precisas para seu caso de uso específico, especialmente para conversas de múltiplos turnos que incluem pensamento.



Criptografia do pensamento

O conteúdo completo do pensamento é criptografado e retornado no campo signature em cada bloco de pensamento. A API usa a assinatura para verificar que os blocos de pensamento foram gerados por Claude quando você os passa de volta.

Tenha o seguinte em mente ao trabalhar com assinaturas:

• Só é estritamente necessário enviar blocos de pensamento de volta ao usar ferramentas com pensamento. Caso contrário, você pode omitir blocos de pensamento de turnos anteriores. Se você os passar de volta, se a API os mantém ou remove depende do modelo (consulte Preservação de blocos de pensamento por modelo); use a edição de contexto para configurar isso.
• Ao enviar blocos de pensamento de volta, passe tudo de volta exatamente como você recebeu, para consistência e para evitar possíveis problemas.
• Ao fazer streaming de respostas, a assinatura chega como um signature_delta dentro de um evento content_block_delta logo antes do evento content_block_stop.
• Os valores de signature são significativamente mais longos nos modelos Claude 4 e posteriores do que em modelos anteriores.
• O campo signature é opaco: não o interprete nem o analise.
• Os valores de signature são compatíveis entre plataformas (APIs do Claude, Amazon Bedrock e Google Cloud). Valores gerados em uma plataforma funcionam em outra.



Blocos de pensamento redigidos

Além dos blocos thinking regulares, a API pode retornar blocos redacted_thinking quando partes do raciocínio do Claude são redigidas por segurança. Um bloco redacted_thinking contém conteúdo de pensamento criptografado em um campo data, sem texto legível:

{
  "type": "redacted_thinking",
  "data": "..."
}

O campo data é opaco e criptografado. Assim como o campo signature em blocos de pensamento regulares, passe os blocos redacted_thinking de volta para a API sem alterações ao continuar uma conversa de múltiplos turnos com ferramentas.



Saída de pensamento no Claude Fable 5 e Claude Mythos 5

No Claude Fable 5 e Claude Mythos 5, a cadeia de pensamento bruta nunca é retornada; os blocos que você recebe são blocos thinking regulares, não redacted_thinking, e a configuração display funciona da mesma forma que em outros modelos (texto resumido, ou um campo thinking vazio quando omitido, o padrão aqui). Para o formato de resposta dos blocos de pensamento, consulte a referência da API de Messages.

Ao continuar uma conversa no mesmo modelo, passe cada bloco de pensamento de volta para a API exatamente como recebido, incluindo blocos cujo campo thinking está vazio. Não os edite nem os reconstrua. Ler o texto do resumo para exibição é aceitável: a API rejeita blocos cujo conteúdo retornado foi modificado, não blocos que você leu. Texto colocado em um campo thinking omitido vazio é ignorado em vez de rejeitado.

Para o que acontece com os blocos de pensamento quando você troca de modelo no meio da conversa, consulte Preservação de blocos de pensamento por modelo.

Duas exceções, cobertas em Crédito de fallback:

• Novas tentativas com crédito de fallback devem ecoar o corpo da solicitação recusada sem alterações.
• Blocos fallback de um fallback no meio da saída permanecem onde apareceram.

Para obter visibilidade do raciocínio do modelo, leia os blocos thinking descritos nesta página em vez de solicitar o raciocínio no texto da resposta. No Claude Fable 5, uma solicitação que tenta extrair o raciocínio interno do modelo como parte do texto da resposta pode ser recusada com stop_details.category: "reasoning_extraction". Consulte Categorias de recusa para a referência do campo e orientações de tratamento.



Limites e compatibilidade de recursos

Parâmetros de amostragem. No Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Sonnet 5, valores não padrão de temperature, top_p ou top_k retornam um erro 400 em todas as requisições, independentemente de o pensamento estar sendo usado ou não. Em modelos mais antigos, a restrição se aplica apenas enquanto o pensamento está ativado: temperature e top_k são incompatíveis com o pensamento, e top_p é permitido com valores entre 0.95 e 1.

Pré-preenchimento de resposta e uso forçado de ferramentas. Você não pode pré-preencher a resposta do assistente enquanto o pensamento está ativado. O uso forçado de ferramentas (tool_choice: {"type": "any"} ou {"type": "tool", ...}) é incompatível com o pensamento estendido manual, mas funciona com o pensamento adaptativo; consulte Pensamento com uso de ferramentas.

Limites de saída. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 e Claude Sonnet 4.6 suportam até 128k tokens de saída por requisição. Claude Haiku 4.5, Claude Sonnet 4.5 e Claude Opus 4.5 suportam até 64k. Na API de Message Batches, o cabeçalho beta output-300k-2026-03-24 eleva o limite para 300k para Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 e Claude Sonnet 4.6. Consulte a visão geral dos modelos para os limites de modelos legados.

Requisições longas. Os SDKs exigem streaming quando max_tokens é maior que 21.333, para evitar timeouts de HTTP em requisições de longa duração. Esta é uma validação do lado do cliente, não uma restrição da API. Se você não precisa processar eventos de forma incremental, use .stream() com .get_final_message() (Python) ou .finalMessage() (TypeScript) para obter o objeto Message completo sem lidar com eventos individuais; consulte Streaming de Messages. Espere tempos de resposta mais longos quando o pensamento está ativo, já que gerar blocos de pensamento adiciona tempo de processamento. Para cargas de trabalho que levam o pensamento acima de aproximadamente 32k tokens por requisição, use processamento em lote para evitar problemas de rede: tais requisições podem durar o suficiente para atingir timeouts do sistema e limites de conexões abertas.



Próximos passos