Pensamento estendido

O "extended thinking" (pensamento estendido) dá ao Claude capacidades de raciocínio aprimoradas para tarefas complexas, ao mesmo tempo que fornece níveis variados de transparência sobre seu processo de pensamento passo a passo antes de entregar sua resposta final.



Modelos compatíveis

O pensamento estendido está disponível em todos os modelos Claude atuais. Como você o habilita depende do modelo:

Com o pensamento adaptativo, o modelo decide quando e quanto pensar em cada requisição. No Claude Mythos Preview, Claude Fable 5 e Claude Mythos 5, thinking: {type: "disabled"} não é compatível. Para diferenças de comportamento por modelo (saída de pensamento, pensamento intercalado e preservação de blocos), consulte Diferenças no pensamento entre versões de modelos.



Como o pensamento estendido funciona

Quando o pensamento estendido está ativado, o Claude cria blocos de conteúdo thinking onde ele gera seu raciocínio interno. O Claude incorpora insights desse raciocínio antes de elaborar uma resposta final.

A resposta da API inclui blocos de conteúdo thinking, seguidos por blocos de conteúdo text.

Aqui está um exemplo do formato de resposta padrão:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Para mais informações sobre o formato de resposta do pensamento estendido, consulte a Referência da Messages API.



Como usar o pensamento estendido

Aqui está um exemplo de uso do pensamento estendido na Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta contém blocos de pensamento resumidos e blocos de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Para ativar o pensamento estendido, adicione um objeto thinking com type definido como enabled e um valor de budget_tokens. Em modelos onde o pensamento estendido manual está descontinuado ou não é compatível (consulte Modelos compatíveis), use type: "adaptive" em vez disso, conforme descrito em Pensamento adaptativo.

O parâmetro budget_tokens define o número máximo de tokens que o Claude pode usar para seu processo de raciocínio interno. Esse limite se aplica aos tokens de pensamento completos, não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir uma análise mais completa para problemas complexos, embora o Claude possa não usar todo o orçamento alocado, especialmente em faixas acima de 32k.

budget_tokens deve ser definido com um valor menor que max_tokens. No entanto, ao usar pensamento intercalado com ferramentas, você pode exceder esse limite, pois o limite de tokens se torna toda a sua janela de contexto. Como budget_tokens deve ser menor que max_tokens, o pensamento estendido não pode ser combinado com max_tokens: 0 (pré-aquecimento do cache).



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. Ele aceita dois valores:

• "summarized": Os blocos de pensamento contêm texto de pensamento resumido. Consulte Pensamento resumido para mais detalhes. Este é o padrão no Claude Opus 4.6, Claude Sonnet 4.6 e modelos Claude 4 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 de pensamento). Este é o padrão no Claude Fable 5, Claude Mythos 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview.

Definir display: "omitted" é útil quando sua aplicação não exibe o 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 dos tokens de pensamento e entrega apenas a assinatura, de modo que a resposta de texto final começa a ser transmitida mais cedo.

Aqui estão algumas considerações importantes sobre o pensamento omitido:

• Você ainda é cobrado pelos tokens de pensamento completos. A omissão 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 o signature para reconstruir o pensamento original na construção do prompt (consulte Preservando blocos de pensamento). Qualquer texto que você colocar no campo thinking de um bloco omitido enviado de volta é 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.

Pipelines automatizados que nunca exibem conteúdo de pensamento para usuários finais podem evitar a sobrecarga de receber tokens de pensamento pela rede. Aplicações sensíveis à latência obtêm a mesma qualidade de raciocínio sem esperar que o texto de pensamento seja transmitido antes que a resposta final comece.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

Quando display: "omitted" está definido, 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."
    }
  ]
}

Ao fazer streaming com display: "omitted", nenhum evento thinking_delta é emitido; consulte Streaming de pensamento para a sequência de eventos.



Pensamento resumido

Com o "extended thinking" (pensamento estendido) habilitado, a API de Messages para modelos Claude 4 retorna um resumo do processo completo de pensamento do Claude. O pensamento resumido fornece todos os benefícios de inteligência do pensamento estendido, ao mesmo tempo que previne uso indevido. Este é o comportamento padrão nos modelos Claude 4 quando o campo display na configuração de pensamento não está definido ou está definido como "summarized". No Claude Fable 5, Claude Mythos 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 e Claude Mythos Preview, display tem como padrão "omitted", então você deve definir display: "summarized" explicitamente para receber o pensamento resumido.

Aqui estão algumas considerações importantes sobre o pensamento resumido:

• Você é cobrado pelos tokens completos de pensamento gerados pela requisição original, não pelos tokens do resumo.
• A contagem de tokens de saída faturada não corresponderá à contagem de tokens que você vê na resposta.
• Nos modelos Claude 4, as primeiras linhas da saída de pensamento são mais detalhadas, fornecendo raciocínio minucioso que é particularmente útil para fins de engenharia de prompts. O Claude Mythos Preview resume desde o primeiro token, então seus blocos de pensamento não mostram esse preâmbulo detalhado.
• À medida que a Anthropic busca aprimorar o recurso de pensamento estendido, o comportamento de resumo está sujeito a alterações.
• O resumo preserva as ideias principais do processo de pensamento do Claude com latência adicional mínima, possibilitando uma experiência de usuário com suporte a streaming.
• O resumo é processado por um modelo diferente daquele que você especifica em suas requisições. O modelo de pensamento não vê a saída resumida.



Streaming de pensamento

Você pode fazer streaming de respostas de pensamento estendido usando server-sent events (SSE).

Quando o streaming está habilitado para pensamento estendido, você recebe conteúdo de pensamento via eventos thinking_delta.

Quando display: "omitted" está definido, nenhum evento thinking_delta é emitido. Consulte Controlando a exibição do pensamento.

Para mais documentação sobre streaming via Messages API, consulte Streaming de Mensagens.

Veja como lidar com streaming com pensamento:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # Redefinir flags para cada novo bloco
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

Exemplo de saída de streaming:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}

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": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

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

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": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

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

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

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":""}}



Pensamento estendido com uso de ferramentas

O pensamento estendido pode ser usado junto com uso de ferramentas, permitindo que o Claude raciocine sobre a seleção de ferramentas e o processamento de resultados.

Ao usar pensamento estendido com uso de ferramentas, esteja ciente das seguintes limitações:

1. Limitação de escolha de ferramenta: O uso de ferramentas com pensamento 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": "..."} resultará em um erro porque essas opções forçam o uso de ferramentas, o que é incompatível com o pensamento estendido.

2. Preservação de blocos de pensamento: Durante o uso de ferramentas, você deve passar os blocos thinking de volta para a API na última mensagem do assistente. Inclua o bloco completo e não modificado de volta para a API para manter a continuidade do raciocínio.



Alternando modos de pensamento em conversas

Você não pode alternar o pensamento no meio de um turno do assistente, incluindo durante loops de uso de ferramentas. Todo o turno do assistente deve operar em um único modo de pensamento:

• Se o pensamento estiver habilitado, o turno final do assistente deve começar com um bloco de pensamento.
• Se o pensamento estiver desabilitado, o turno final do assistente não deve conter nenhum bloco de pensamento

Da perspectiva do modelo, loops de uso de ferramentas fazem parte do turno do assistente. Um turno do assistente não é concluído até que o Claude termine sua resposta completa, que pode incluir várias chamadas de ferramentas e resultados.

Por exemplo, esta sequência faz toda parte de 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"]

Mesmo que haja várias mensagens da API, o loop de uso de ferramentas é conceitualmente parte de uma resposta contínua do assistente.



Degradação graciosa do pensamento

Quando ocorre um conflito de pensamento no meio do turno (como alternar o pensamento para ativado ou desativado durante um loop de uso de ferramentas), a API desabilita automaticamente o pensamento para essa requisição. Para preservar a qualidade do modelo e permanecer dentro da distribuição, a API pode:

• Remover blocos de pensamento da conversa quando eles criariam uma estrutura de turno inválida
• Desabilitar o pensamento para a requisição atual quando o histórico da conversa for incompatível com o pensamento habilitado

Isso significa que tentar alternar o pensamento no meio do turno não causará um erro, mas o pensamento será silenciosamente desabilitado para essa requisição. Para confirmar se o pensamento estava ativo, verifique a presença de blocos thinking na resposta.



Orientação prática

Melhor prática: Planeje sua estratégia de pensamento no início de cada turno em vez de tentar alternar no meio do turno.

Exemplo: Alternando o pensamento após completar um turno

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)

Ao completar o turno do assistente antes de alternar o pensamento, você garante que o pensamento esteja realmente habilitado para a nova requisição.



Preservando blocos de pensamento

Durante o uso de ferramentas, você deve passar os blocos thinking de volta para a API, e deve incluir o bloco completo e não modificado de volta para a API. Isso é crítico para manter o fluxo de raciocínio do modelo e a integridade da conversa.

Quando o Claude invoca ferramentas, ele está pausando a construção de uma resposta para aguardar informações externas. Quando os resultados das ferramentas são retornados, o Claude continua construindo essa resposta existente. Isso torna necessário preservar blocos de pensamento durante o uso de ferramentas, por algumas razões:

1. Continuidade do raciocínio: Os blocos de pensamento capturam o raciocínio passo a passo do Claude que levou às requisições de ferramentas. Quando você envia resultados de ferramentas, incluir o pensamento original garante que o Claude possa continuar seu raciocínio de onde parou.

2. Manutenção de contexto: Embora os resultados de ferramentas apareçam como mensagens de usuário na estrutura da API, eles fazem parte de um fluxo de raciocínio contínuo. Preservar blocos de pensamento mantém esse fluxo conceitual em várias chamadas de API. Para mais informações sobre gerenciamento de contexto, consulte o guia sobre janelas de contexto.

Importante: Ao fornecer blocos thinking, toda a sequência de blocos thinking consecutivos deve corresponder às saídas geradas pelo modelo durante a requisição original; você não pode reorganizar ou modificar a sequência desses blocos.



Pensamento intercalado

O pensamento estendido com uso de ferramentas em modelos Claude 4 suporta "interleaved thinking" (pensamento intercalado), que permite ao Claude pensar entre chamadas de ferramentas e fazer raciocínio mais sofisticado após receber resultados de ferramentas.

Com pensamento intercalado, o Claude pode:

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

Como você habilita o pensamento intercalado depende do modelo:

Modelos Claude 4 anteriores aqui significa Claude Sonnet 4.5, Claude Opus 4.1 (descontinuado), Claude Opus 4 (retirado, exceto no Google Cloud) e Claude Sonnet 4 (retirado, exceto no Bedrock e Google Cloud).

Aqui estão algumas considerações importantes para o pensamento intercalado:

• Com pensamento intercalado, o budget_tokens pode exceder o parâmetro max_tokens, pois representa o orçamento total em todos os blocos de pensamento dentro de um turno do assistente.
• O pensamento intercalado é compatível apenas com ferramentas usadas via Messages API.
• A API do Claude e a Claude Platform na AWS aceitam interleaved-thinking-2025-05-14 em requisições para qualquer modelo sem retornar um erro. Em modelos que não suportam pensamento intercalado, o cabeçalho é ignorado. No Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 5, ele está descontinuado e é ignorado com segurança. No Claude Mythos Preview, ele não é necessário e é ignorado com segurança.
• Em plataformas operadas por parceiros (por exemplo, Amazon Bedrock e Google Cloud), se você passar interleaved-thinking-2025-05-14 para qualquer modelo além de Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1 (descontinuado), Opus 4 (retirado, exceto no Google Cloud), Sonnet 4.5 ou Sonnet 4 (retirado, exceto no Bedrock e Google Cloud), sua requisição falhará.



Pensamento estendido com cache de prompt

O cache de prompt com pensamento tem várias considerações importantes:

Remoção de contexto de blocos de pensamento

• Em modelos Opus/Sonnet anteriores e todos os modelos Haiku, blocos de pensamento de turnos anteriores são removidos do contexto, o que pode afetar pontos de interrupção de cache. No Opus 4.5+ e Sonnet 4.6+, eles são mantidos por padrão.
• Ao continuar conversas com uso de ferramentas, blocos de pensamento são armazenados em cache e contam como tokens de entrada quando lidos do cache
• Isso cria uma compensação: embora blocos de pensamento não consumam espaço da janela de contexto visualmente, eles ainda contam para seu uso de tokens de entrada quando armazenados em cache
• Se o pensamento for desabilitado e você passar conteúdo de pensamento no turno atual de uso de ferramentas, o conteúdo de pensamento será removido e o pensamento permanecerá desabilitado para essa requisição

Padrões de invalidação de cache

• Mudanças nos parâmetros de pensamento (habilitado/desabilitado ou alocação de orçamento) invalidam pontos de interrupção de cache de mensagens
• O pensamento intercalado amplifica a invalidação de cache, pois blocos de pensamento podem ocorrer entre várias chamadas de ferramentas
• Prompts do sistema e ferramentas permanecem em cache apesar de mudanças nos parâmetros de pensamento ou remoção de blocos



Entendendo o comportamento de cache de blocos de pensamento

Ao usar pensamento estendido com uso de ferramentas, blocos de pensamento exibem comportamento de cache específico que afeta a contagem de tokens:

Como funciona:

1. O cache ocorre apenas quando você faz uma requisição subsequente que inclui resultados de ferramentas
2. Quando a requisição subsequente é feita, o histórico de conversa anterior (incluindo blocos de pensamento) pode ser armazenado em cache
3. Esses blocos de pensamento em cache contam como tokens de entrada em suas métricas de uso quando lidos do cache
4. Quando um bloco de usuário que não é resultado de ferramenta é incluído: no Opus 4.5+ e Sonnet 4.6+, blocos de pensamento anteriores são mantidos; em modelos Opus/Sonnet anteriores e todos os modelos Haiku, todos os blocos de pensamento anteriores são ignorados e removidos do contexto

Fluxo de exemplo detalhado:

Requisição 1:

User: "What's the weather in Paris?"

Resposta 1:

[thinking_block_1] + [tool_use block 1]

Requisição 2:

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

Resposta 2:

[thinking_block_2] + [text block 2]

A Requisição 2 grava um cache do conteúdo da requisição (não da resposta). O cache inclui a mensagem original do usuário, o primeiro bloco de pensamento, o bloco de uso de ferramenta e o resultado da ferramenta.

Requisição 3:

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]

Para Opus 4.5+ e Sonnet 4.6+, todos os blocos de pensamento anteriores são mantidos por padrão. Para modelos Opus/Sonnet anteriores e todos os modelos Haiku, como um bloco de usuário que não é resultado de ferramenta foi incluído, todos os blocos de pensamento anteriores são ignorados e removidos do contexto. Essa requisição será processada da mesma forma que:

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]

Pontos principais:

• Esse comportamento de cache acontece automaticamente, mesmo sem marcadores cache_control explícitos
• Esse comportamento é consistente seja usando pensamento regular ou pensamento intercalado



Max tokens e tamanho da janela de contexto com pensamento estendido

max_tokens (que inclui seu orçamento de pensamento quando o pensamento está habilitado) é aplicado como um limite estrito. Em 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 modelos anteriores, a API retorna um erro de validação em vez disso. Consulte Lidando com motivos de parada.



A janela de contexto com pensamento estendido

Ao calcular o uso da janela de contexto com pensamento habilitado, há algumas considerações a serem observadas:

• No Opus 4.5+ e Sonnet 4.6+, blocos de pensamento de turnos anteriores são mantidos e contam para sua janela de contexto; em modelos Opus/Sonnet anteriores e todos os modelos Haiku, eles são removidos e não contados
• O pensamento do turno atual conta para seu limite de max_tokens para esse turno

O diagrama abaixo demonstra o gerenciamento especializado de tokens quando o pensamento estendido está habilitado:

A janela de contexto efetiva é calculada como:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

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



A janela de contexto com pensamento estendido e uso de ferramentas

Ao usar pensamento estendido com uso de ferramentas, blocos de pensamento devem ser explicitamente preservados e retornados com os resultados das ferramentas.

O cálculo da janela de contexto efetiva para pensamento estendido com uso de ferramentas se torna:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

O diagrama abaixo ilustra o gerenciamento de tokens para pensamento estendido com uso de ferramentas:



Gerenciando tokens com pensamento estendido

Dado o comportamento da janela de contexto e max_tokens com pensamento estendido, você pode precisar:

• Monitorar e gerenciar mais ativamente seu uso de tokens
• Ajustar valores de max_tokens conforme o comprimento do seu prompt muda
• Potencialmente usar os endpoints de contagem de tokens com mais frequência
• Estar ciente de que blocos de pensamento anteriores não se acumulam em sua janela de contexto



Criptografia de pensamento

O conteúdo completo do pensamento é criptografado e retornado no campo signature. Esse campo é usado para verificar se os blocos de pensamento foram gerados pelo Claude quando passados de volta para a API.

Aqui estão algumas considerações importantes sobre a criptografia do pensamento:

• Ao fazer streaming de respostas, a assinatura é adicionada por meio de 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 do que nos modelos anteriores.
• O campo signature é um campo opaco e não deve ser interpretado ou analisado.
• Os valores de signature são compatíveis entre plataformas (APIs do Claude, Amazon Bedrock e Google Cloud). Valores gerados em uma plataforma serão compatíveis com outra.



Blocos de pensamento redigidos

Além dos blocos thinking regulares, a API pode retornar blocos redacted_thinking. Um bloco redacted_thinking contém conteúdo de pensamento criptografado em um campo data, sem resumo legível:

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

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



Diferenças no pensamento entre versões de modelos

A Messages API lida com o pensamento de forma diferente entre versões de modelos Claude. A tabela a seguir fornece uma comparação condensada:

¹ Defina display: "summarized" para receber pensamento resumido. No Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview, tokens de pensamento brutos nunca são retornados.
² Com pensamento adaptativo. O cabeçalho beta interleaved-thinking-2025-05-14 não é necessário nesses modelos e é ignorado com segurança se incluído.
³ Blocos são removidos ao continuar a conversa em um modelo que não suporta o formato de pensamento do Mythos.



Preservação de blocos de pensamento por modelo

Se os blocos de pensamento de turnos anteriores do assistente são preservados no contexto por padrão depende da classe do modelo. Opus: Claude Opus 4.5 e modelos Opus posteriores mantêm todos os blocos de pensamento anteriores; Claude Opus 4.1 (descontinuado) e modelos Opus anteriores mantêm apenas o pensamento do último turno do assistente. Sonnet: Claude Sonnet 4.6 e modelos Sonnet posteriores mantêm todos; Claude Sonnet 4.5 e modelos Sonnet anteriores mantêm apenas o último turno. Haiku: todos os modelos Haiku até Claude Haiku 4.5 mantêm apenas o último turno. Claude Mythos Preview também mantém todos os blocos de pensamento anteriores.

Benefícios da preservação de blocos de pensamento:

• Otimização de cache: Ao usar uso de ferramentas, blocos de pensamento preservados permitem acertos de cache, 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 várias etapas
• Sem impacto na inteligência: Preservar blocos de pensamento não tem efeito negativo no desempenho do modelo

Considerações importantes:

• Uso de contexto: Conversas longas consumirão mais espaço de contexto, pois blocos de pensamento são retidos no contexto
• Comportamento automático: Este é o padrão para cada modelo conforme listado acima. Nenhuma alteração de código ou cabeçalhos beta são necessários
• Compatibilidade retroativa: Para aproveitar esse recurso, continue passando blocos de pensamento completos e não modificados de volta para a API como você faria para uso de ferramentas



Preços

Para informações completas sobre preços, incluindo taxas base, gravações de cache, acertos de cache e tokens de saída, consulte a página de preços.

O processo de pensamento gera cobranças por:

• Tokens usados durante o pensamento (tokens de saída)
• Blocos de pensamento de turnos anteriores do assistente mantidos no contexto: apenas o último turno em modelos Opus/Sonnet anteriores e todos os modelos Haiku; todos os turnos por padrão no Opus 4.5+ e Sonnet 4.6+ (tokens de entrada)
• Tokens de saída de texto padrão

Ao usar pensamento resumido:

• Tokens de entrada: Tokens na sua solicitação original (exclui tokens de pensamento de turnos anteriores)
• Tokens de saída (cobrados): Os tokens de pensamento originais que o Claude gerou internamente
• Tokens de saída (visíveis): Os tokens de pensamento resumidos que você vê na resposta
• Sem cobrança: Tokens usados para gerar o resumo

Ao usar display: "omitted":

• Tokens de entrada: Tokens na sua solicitação original (igual ao resumido)
• Tokens de saída (cobrados): Os tokens de pensamento originais que o Claude gerou internamente (igual ao resumido)
• Tokens de saída (visíveis): Zero tokens de pensamento (o campo thinking está vazio)

Para ver quantos tokens de saída cobrados foram gastos no raciocínio interno, leia usage.output_tokens_details.thinking_tokens na resposta. Esse valor reflete o raciocínio bruto que o modelo gerou (não o texto resumido retornado no corpo) e é sempre menor ou igual a output_tokens. Subtraia-o de output_tokens para obter uma aproximação da parte da saída que não corresponde ao raciocínio.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens continua sendo o total inclusivo e autoritativo usado para cobrança. output_tokens_details é um detalhamento somente leitura para observabilidade.



Melhores práticas e considerações para pensamento estendido



Trabalhando com orçamentos de pensamento

• Otimização do orçamento: O orçamento mínimo é de 1.024 tokens. Comece no mínimo e aumente o orçamento de pensamento incrementalmente para encontrar o intervalo ideal para seu caso de uso. Contagens de tokens mais altas permitem raciocínio mais abrangente, mas com retornos decrescentes dependendo da tarefa. Aumentar o orçamento pode melhorar a qualidade da resposta em troca de maior "latency" (latência). Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio ideal. Observe que o orçamento de pensamento é uma meta e não um limite estrito. O uso real de tokens pode variar com base na tarefa.
• Pontos de partida: Comece com orçamentos de pensamento maiores (16k+ tokens) para tarefas complexas e ajuste com base em suas necessidades.
• Orçamentos grandes: Para orçamentos de pensamento acima de 32k, use processamento em lote para evitar problemas de rede. Requisições que levam o modelo a pensar acima de 32k tokens causam requisições de longa duração que podem esbarrar em timeouts do sistema e limites de conexões abertas.
• Rastreamento de uso de tokens: Monitore o uso de tokens de pensamento para otimizar custos e desempenho. O campo usage.output_tokens_details.thinking_tokens na resposta informa quantos dos tokens de saída cobrados foram de raciocínio interno. Ao usar streaming, esse detalhamento aparece apenas no evento final message_delta.



Considerações de desempenho

• Tempos de resposta: Esteja preparado para tempos de resposta mais longos devido ao processamento adicional. A geração de blocos de pensamento aumenta o tempo total de resposta.
• Requisitos de streaming: 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 incrementalmente, 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 para mais detalhes. Ao usar streaming, esteja preparado para lidar com blocos de conteúdo de pensamento e de texto à medida que chegam.
• Omitir pensamento para reduzir latência: Se sua aplicação não exibe o conteúdo de pensamento, defina display: "omitted" na configuração de pensamento para reduzir o tempo até o primeiro token de texto. Consulte Controlando a exibição do pensamento.



Compatibilidade de recursos

• O pensamento não é compatível com modificações de temperature ou top_k, nem com uso forçado de ferramentas.
• Quando o pensamento está habilitado, você pode definir top_p para valores entre 1 e 0,95.
• Você não pode pré-preencher respostas quando o pensamento está habilitado.
• Alterações no orçamento de pensamento invalidam prefixos de prompt em cache que incluem mensagens. No entanto, prompts do sistema e definições de ferramentas em cache continuarão funcionando quando os parâmetros de pensamento mudarem.



Diretrizes de uso

• Seleção de tarefas: Use pensamento estendido para tarefas particularmente complexas que se beneficiam de raciocínio passo a passo, como matemática, programação e análise.
• Tratamento de contexto: Você não precisa remover blocos de pensamento anteriores por conta própria. No Opus 4.5+ e Sonnet 4.6+, a API do Claude mantém blocos de pensamento de turnos anteriores por padrão; em modelos Opus/Sonnet anteriores e em todos os modelos Haiku, ela os ignora automaticamente e eles não são incluídos no cálculo do uso de contexto.
• Engenharia de prompt: Revise as dicas de prompting para pensamento estendido se quiser maximizar as capacidades de pensamento do Claude.



Próximos passos