Pensamento

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

O pensamento remove essa restrição. Quando o pensamento está ativo, o Claude trabalha o problema com suas próprias palavras antes de responder: ele reformula o que está sendo pedido, 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 o 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 o Claude gasta raciocinando são cobrados como tokens de saída, mesmo quando o texto de pensamento não é retornado a você, e eles contam para max_tokens junto com o texto da resposta. Esta página aborda como o pensamento se comporta em toda a superfície da API: como 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 o Claude pensa em uma determinada requisição, e com que profundidade, depende da sua configuração de pensamento e da complexidade da requisiçã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 multi-turno e de 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 multi-turno. Consulte Controlando a exibição do pensamento para padrões e detalhes por modelo.

Se o 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 é seu 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, porque display tem como padrão "omitted" neles. Opte por isso com thinking: {"type": "adaptive", "display": "summarized"}, que é exatamente a requisiçã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é você definir thinking: {type: "adaptive"}, o que permite ao Claude decidir quando e com que profundidade pensar com base na requisição. Os exemplos a seguir fazem isso, definem display: "summarized" para que o texto de pensamento fique visível e usam um max_tokens amplo:

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"} em effort high ou inferior. Em effort xhigh ou max, o pensamento não pode ser desativado: requisiçõ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 requisiçã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 o pensamento desativado para mitigações de prompt.

O 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. A página Pensamento estendido aborda essa configuração. E se qualquer configuração de pensamento retornar com um erro 400, Solução de problemas de pensamento associa 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 multi-turno (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 mais rápido até o primeiro token de texto ao usar streaming: o servidor pula completamente o streaming de 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 em mente o seguinte 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 multi-turno, 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ê colocar no campo thinking de um bloco omitido retornado é 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 requisição simples, nenhum bloco de pensamento é produzido, independentemente de display.
• Ao usar streaming com display: "omitted", nenhum evento thinking_delta é emitido. Consulte Streaming de pensamento para a sequência de eventos.

No SDK Ruby, hashes simples aceitam display: como os exemplos mostram. A classe tipada ThinkingConfigAdaptive nomeia o parâmetro como display_ (com underscore no final, para evitar sombrear o Kernel#display do Ruby). De qualquer forma, o campo transmitido 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 em mente o seguinte ao trabalhar com pensamento resumido:

• Você é cobrado pelos tokens de pensamento completos gerados pela requisiçã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 principais do processo de pensamento do Claude com latência adicional mínima, então os resumos podem ser transmitidos via streaming à medida que chegam.
• A sumarização é processada por um modelo diferente daquele que você especifica em suas requisiçõ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 à medida que 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)

Para remontar blocos de pensamento completos com suas assinaturas após o streaming, use o helper de acumulação de mensagens do seu SDK quando existir (por exemplo, stream.get_final_message() em Python ou stream.finalMessage() em TypeScript) em vez de concatenar deltas você mesmo.

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 Effort documenta o parâmetro em si, incluindo quais níveis cada modelo suporta. No Claude Opus 4.5, o único modelo exclusivo 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:

• Reduzir custo ou latência em uma carga de trabalho com pensamento ativado: reduza effort primeiro. Ele reduz a escala de toda a resposta, incluindo o pensamento.
• O Claude está pensando muito raramente ou muito superficialmente: aumente effort, ou consulte Direcionando a frequência com que o Claude pensa na página de direcionamento.
• Você precisa do pensamento totalmente desativado: use thinking: {type: "disabled"} em modelos que permitem isso (consulte a tabela de configuração por modelo).
• Você precisa de um teto rígido de gastos: use max_tokens. Effort é 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 o Claude raciocine sobre a seleção de ferramentas e processe resultados de 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 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, 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 o Claude termine sua resposta completa, o 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 requisição com pensamento ativado 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 silenciosamente desativa o pensamento para essa requisiçã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 ativado. 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, depois 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)

Alternar modos de pensamento também invalida o cache de prompt. Consulte Pensamento e cache de prompt.



Preservando blocos de pensamento

Quando o Claude invoca uma ferramenta, ele pausa a construção de sua resposta para aguardar informações externas. Quando você retorna o resultado da ferramenta, o 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 acompanhou. Isso importa por dois motivos:

1. Continuidade do raciocínio: os blocos de pensamento capturam o raciocínio passo a passo que levou às requisições de ferramentas. Incluí-los permite que o Claude continue raciocinando de onde parou.
2. Manutenção de contexto: os resultados de ferramentas aparecem como mensagens de usuário na estrutura da API, mas fazem parte de um fluxo contínuo de raciocínio. Preservar 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 multi-turno, 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 requisiçã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 de ferramentas e multi-turno. Ele define uma ferramenta, recebe uma resposta de pensamento mais uso de ferramenta e ecoa o turno do assistente de volta com o resultado da ferramenta.



Pensamento intercalado

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

• Raciocinar sobre os resultados de uma chamada de ferramenta antes de decidir o que fazer a seguir
• 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 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 aborda as regras por modelo e o comportamento de cabeçalho específico da plataforma.

Com 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 prática mostrando o que o pensamento intercalado muda em um fluxo de trabalho de 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 resultados de 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, porque 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 limpeza de blocos de pensamento.

Alternando modelos no meio da conversa. Quando você alterna entre quaisquer dois modelos, por exemplo após um fallback de recusa de classificador, remova os blocos thinking e redacted_thinking de 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 requisiçã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.

Alterações 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 pontos de interrupção de cache: pontos de interrupção no nível de mensagem sempre falham, e pontos de interrupção de ferramentas e prompt do sistema também podem falhar, dependendo de onde o modelo renderiza a configuração. Trate qualquer alteração de pensamento ou effort como um reinício do cache. Requisições consecutivas que mantêm a mesma configuração preservam o cache, e definir um parâmetro explicitamente para seu valor padrão é equivalente a omiti-lo. Uma demonstração prática com saída de uso está na página Direcionando o pensamento.

Blocos de pensamento são armazenados em cache com resultados de ferramentas. Durante um loop de uso de ferramentas, o cache ocorre quando você faz uma requisição de acompanhamento que inclui resultados de ferramentas. Nesse ponto, o histórico de conversa anterior, 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 ocorre 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 vê novamente nas respostas ainda contribuem para o uso de tokens de entrada quando lidos do cache.

Se 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, uma vez 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 requisiçã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 requisição (consulte degradação graciosa). O pensamento intercalado amplifica os efeitos de invalidação de cache, porque 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 o 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 requisiçã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 motivos de parada.

Como o pensamento conta para a janela depende de quando 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, blocos de pensamento anteriores permanecem no contexto, contam para a janela e são cobrados como tokens de entrada como o resto do histórico da conversa. Em modelos que mantêm apenas o último turno, a API remove blocos de pensamento mais antigos automaticamente 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 é. Sessões agênticas longas acumulam pensamento no contexto. Use limpeza de blocos de pensamento se precisar recuperar espaço.
• Em modelos que mantêm apenas o último turno, o pensamento é apenas um custo por turno: o pensamento de cada turno conta para o max_tokens desse turno e depois sai da janela.

Os diagramas a seguir ilustram o regime de apenas último turno (remoção). O primeiro mostra uma conversa multi-turno: o bloco de pensamento de cada turno é gerado na saída, mas não é carregado 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 multi-turno que incluem pensamento.



Criptografia do pensamento

O conteúdo completo de 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 pelo Claude quando você os passa de volta.

Tenha em mente o seguinte ao trabalhar com assinaturas:

• É estritamente necessário enviar blocos de pensamento de volta apenas 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 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 transmitir respostas via streaming, 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 (a API 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. Como o campo signature em blocos de pensamento regulares, passe blocos redacted_thinking de volta para a API sem alterações ao continuar uma conversa multi-turno 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 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 vazio de um bloco omitido é ignorado em vez de rejeitado.

Para como os blocos de pensamento são tratados quando você alterna modelos no meio da conversa, consulte Preservação de blocos de pensamento por modelo.

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

• Novas tentativas com crédito de fallback devem ecoar o corpo da requisiçã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 raciocínio no texto da resposta. No Claude Fable 5, uma requisiçã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. 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.

Preenchimento prévio de resposta e uso forçado de ferramentas. Você não pode preencher previamente 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 Lotes de Mensagens, o cabeçalho beta output-300k-2026-03-24 aumenta o limite para 300k no 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 limites em modelos legados.

Requisições longas. Os SDKs exigem streaming quando max_tokens é maior que 21.333, para evitar timeouts 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 Mensagens. Espere tempos de resposta mais longos quando o pensamento está ativo, porque gerar blocos de pensamento adiciona tempo de processamento. Para cargas de trabalho que elevam o pensamento acima de aproximadamente 32k tokens por requisição, use processamento em lote para evitar problemas de rede: tais requisições podem durar tempo suficiente para atingir timeouts do sistema e limites de conexões abertas.



Próximos passos