Construindo com raciocínio estendido

Raciocínio estendido oferece ao Claude capacidades aprimoradas de raciocínio para tarefas complexas, com diferentes níveis de transparência em seu processo de pensamento passo a passo antes de entregar sua resposta final.

Modelos suportados

Raciocínio estendido é suportado nos seguintes modelos:

• Claude Opus 4.6 (claude-opus-4-6) — raciocínio adaptativo recomendado; modo manual (type: "enabled") está descontinuado
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (descontinuado)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Como funciona o raciocínio estendido

Quando o raciocínio estendido é ativado, Claude cria blocos de conteúdo thinking onde produz seu raciocínio interno. Claude incorpora insights deste raciocínio antes de elaborar uma resposta final.

A resposta da API incluirá 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 raciocínio estendido, veja a Referência da API de Mensagens.

Como usar raciocínio estendido

Aqui está um exemplo de uso de raciocínio estendido na API de Mensagens:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "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?"
        }
    ]
}'

Para ativar o raciocínio estendido, adicione um objeto thinking, com o parâmetro type definido como enabled e o budget_tokens para um orçamento de tokens especificado para raciocínio estendido. Para Claude Opus 4.6, recomendamos usar type: "adaptive" em vez disso — veja Raciocínio adaptativo para detalhes. Enquanto type: "enabled" com budget_tokens ainda é suportado no Opus 4.6, está descontinuado e será removido em uma versão futura.

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

budget_tokens deve ser definido para um valor menor que max_tokens. No entanto, ao usar raciocínio intercalado com ferramentas, você pode exceder este limite, pois o limite de tokens se torna sua janela de contexto inteira (200k tokens).

Raciocínio resumido

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse.

Here are some important considerations for summarized thinking:

• You're charged for the full thinking tokens generated by the original request, not the summary tokens.
• The billed output token count will not match the count of tokens you see in the response.
• The first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes.
• As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
• Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Raciocínio em streaming

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

Quando o streaming é ativado para raciocínio estendido, você recebe conteúdo de raciocínio via eventos thinking_delta.

Para mais documentação sobre streaming via a API de Mensagens, veja Streaming de Mensagens.

Aqui está como lidar com streaming com raciocínio:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?"
        }
    ]
}'

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-5", "stop_reason": null, "stop_sequence": null}}

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

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

Raciocínio estendido com uso de ferramentas

Raciocínio estendido pode ser usado junto com uso de ferramentas, permitindo que Claude raciocine através da seleção de ferramentas e processamento de resultados.

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

1. Limitação de escolha de ferramenta: Uso de ferramentas com raciocínio 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 estas opções forçam o uso de ferramentas, que é incompatível com raciocínio estendido.

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

Alternando modos de raciocínio em conversas

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

• Se raciocínio está ativado, o turno final do assistente deve começar com um bloco de raciocínio.
• Se raciocínio está desativado, o turno final do assistente não deve conter nenhum bloco de raciocínio

Do ponto de vista do modelo, loops de uso de ferramentas fazem parte do turno do assistente. Um turno do assistente não se completa até que Claude termine sua resposta completa, que pode incluir múltiplas chamadas de ferramentas e resultados.

Por exemplo, esta sequência é 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"]

Embora haja múltiplas mensagens da API, o loop de uso de ferramentas é conceitualmente parte de uma resposta contínua do assistente.

Degradação graciosa de raciocínio

Quando um conflito de raciocínio mid-turn ocorre (como alternar raciocínio ligado ou desligado durante um loop de uso de ferramentas), a API desativa automaticamente o raciocínio para aquele pedido. Para preservar a qualidade do modelo e permanecer on-distribution, a API pode:

• Remover blocos de raciocínio da conversa quando criariam uma estrutura de turno inválida
• Desativar raciocínio para o pedido atual quando o histórico de conversa é incompatível com raciocínio sendo ativado

Isto significa que tentar alternar raciocínio mid-turn não causará um erro, mas raciocínio será silenciosamente desativado para aquele pedido. Para confirmar se raciocínio estava ativo, verifique a presença de blocos thinking na resposta.

Orientação prática

Melhor prática: Planeje sua estratégia de raciocínio no início de cada turno em vez de tentar alternar mid-turn.

Exemplo: Alternando raciocínio 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 raciocínio, você garante que raciocínio está realmente ativado para o novo pedido.

Preservando blocos de raciocínio

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

Quando Claude invoca ferramentas, está pausando sua construção de uma resposta para aguardar informações externas. Quando resultados de ferramentas são retornados, Claude continuará construindo aquela resposta existente. Isto necessita preservar blocos de raciocínio durante o uso de ferramentas, por alguns motivos:

1. Continuidade de raciocínio: Os blocos de raciocínio capturam o raciocínio passo a passo de Claude que levou a pedidos de ferramentas. Quando você publica resultados de ferramentas, incluir o raciocínio original garante que Claude possa continuar seu raciocínio de onde parou.

2. Manutenção de contexto: Enquanto resultados de ferramentas aparecem como mensagens de usuário na estrutura da API, eles fazem parte de um fluxo de raciocínio contínuo. Preservar blocos de raciocínio mantém este fluxo conceitual através de múltiplas chamadas de API. Para mais informações sobre gerenciamento de contexto, veja nosso guia sobre janelas de contexto.

Importante: Ao fornecer blocos thinking, a sequência inteira de blocos thinking consecutivos deve corresponder aos outputs gerados pelo modelo durante o pedido original; você não pode reorganizar ou modificar a sequência destes blocos.

Raciocínio intercalado

Raciocínio estendido com uso de ferramentas em modelos Claude 4 suporta raciocínio intercalado, que permite que Claude pense entre chamadas de ferramentas e faça raciocínio mais sofisticado após receber resultados de ferramentas.

Com raciocínio intercalado, 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 passos de raciocínio entre elas
• Tomar decisões mais nuançadas baseadas em resultados intermediários

Para Claude Opus 4.6, raciocínio intercalado é automaticamente ativado ao usar raciocínio adaptativo — nenhum cabeçalho beta é necessário.

Para modelos Claude 4, adicione o cabeçalho beta interleaved-thinking-2025-05-14 ao seu pedido de API para ativar raciocínio intercalado.

Aqui estão algumas considerações importantes para raciocínio intercalado:

• Com raciocínio intercalado, o budget_tokens pode exceder o parâmetro max_tokens, pois representa o orçamento total através de todos os blocos de raciocínio dentro de um turno do assistente.
• Raciocínio intercalado é suportado apenas para ferramentas usadas via a API de Mensagens.
• Para modelos Claude 4, raciocínio intercalado requer o cabeçalho beta interleaved-thinking-2025-05-14.
• Chamadas diretas para a API Claude permitem que você passe interleaved-thinking-2025-05-14 em pedidos para qualquer modelo, sem efeito.
• Em plataformas de terceiros (por exemplo, Amazon Bedrock e Vertex AI), se você passar interleaved-thinking-2025-05-14 para qualquer modelo além de Claude Opus 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4, ou Sonnet 4, seu pedido falhará.

Raciocínio estendido com cache de prompt

Cache de prompt com raciocínio tem várias considerações importantes:

Remoção de contexto de bloco de raciocínio

• Blocos de raciocínio de turnos anteriores são removidos do contexto, o que pode afetar pontos de quebra de cache
• Ao continuar conversas com uso de ferramentas, blocos de raciocínio são cacheados e contam como tokens de entrada quando lidos do cache
• Isto cria um tradeoff: enquanto blocos de raciocínio não consomem espaço de janela de contexto visualmente, eles ainda contam para seu uso de tokens de entrada quando cacheados
• Se raciocínio se torna desativado e você passa conteúdo de raciocínio no turno atual de uso de ferramentas, o conteúdo de raciocínio será removido e raciocínio permanecerá desativado para aquele pedido

Padrões de invalidação de cache

• Mudanças em parâmetros de raciocínio (ativado/desativado ou alocação de orçamento) invalidam pontos de quebra de cache de mensagem
• Raciocínio intercalado amplifica invalidação de cache, pois blocos de raciocínio podem ocorrer entre múltiplas chamadas de ferramentas
• Prompts de sistema e ferramentas permanecem cacheados apesar de mudanças em parâmetros de raciocínio ou remoção de bloco

Compreendendo o comportamento do cache de blocos de pensamento

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

Como funciona:

1. O cache ocorre apenas quando você faz uma solicitação subsequente que inclui resultados de ferramentas
2. Quando a solicitaçã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, todos os blocos de pensamento anteriores são ignorados e removidos do contexto

Fluxo de exemplo detalhado:

Solicitação 1:

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

Resposta 1:

[thinking_block_1] + [tool_use block 1]

Solicitaçã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 Solicitação 2 escreve um cache do conteúdo da solicitação (não da resposta). O cache inclui a mensagem do usuário original, o primeiro bloco de pensamento, bloco de uso de ferramenta e o resultado da ferramenta.

Solicitaçã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 Claude Opus 4.5 e posterior (incluindo Claude Opus 4.6), todos os blocos de pensamento anteriores são mantidos por padrão. Para modelos mais antigos, porque um bloco de usuário que não é resultado de ferramenta foi incluído, todos os blocos de pensamento anteriores são ignorados. Esta solicitaçã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-chave:

• Este comportamento de cache acontece automaticamente, mesmo sem marcadores cache_control explícitos
• Este comportamento é consistente se você estiver usando pensamento regular ou pensamento intercalado

Max tokens e tamanho da janela de contexto com pensamento estendido

Em modelos Claude mais antigos (anteriores ao Claude Sonnet 3.7), se a soma de tokens de prompt e max_tokens excedesse a janela de contexto do modelo, o sistema ajustaria automaticamente max_tokens para caber dentro do limite de contexto. Isso significava que você poderia definir um grande valor de max_tokens e o sistema o reduziria silenciosamente conforme necessário.

Com os modelos Claude 3.7 e 4, max_tokens (que inclui seu orçamento de pensamento quando o pensamento está habilitado) é aplicado como um limite rigoroso. O sistema agora retornará um erro de validação se tokens de prompt + max_tokens exceder o tamanho da janela de contexto.

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:

• Blocos de pensamento de turnos anteriores são removidos e não contam para sua janela de contexto
• 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)

Recomendamos usar a API de contagem de tokens para obter contagens de tokens precisas para seu caso de uso específico, especialmente ao trabalhar com conversas multi-turno 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 efetivo da janela de contexto 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 nos modelos Claude 3.7 e 4, 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

Esta mudança foi feita para fornecer um comportamento mais previsível e transparente, especialmente conforme os limites de tokens máximos aumentaram significativamente.

Criptografia de pensamento

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

Here are some important considerations on thinking encryption:

• When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
• signature values are significantly longer in Claude 4 models than in previous models.
• The signature field is an opaque field and should not be interpreted or parsed - it exists solely for verification purposes.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Redação de pensamento

Occasionally Claude's internal reasoning will be flagged by our safety systems. When this occurs, we encrypt some or all of the thinking block and return it to you as a redacted_thinking block. redacted_thinking blocks are decrypted when passed back to the API, allowing Claude to continue its response without losing context.

When building customer-facing applications that use extended thinking:

• Be aware that redacted thinking blocks contain encrypted content that isn't human-readable
• Consider providing a simple explanation like: "Some of Claude's internal reasoning has been automatically encrypted for safety reasons. This doesn't affect the quality of responses."
• If showing thinking blocks to users, you can filter out redacted blocks while preserving normal thinking blocks
• Be transparent that using extended thinking features may occasionally result in some reasoning being encrypted
• Implement appropriate error handling to gracefully manage redacted thinking without breaking your UI

Here's an example showing both normal and redacted thinking blocks:

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

When passing thinking and redacted_thinking blocks back to the API in a multi-turn conversation, you must include the complete unmodified block back to the API for the last assistant turn. This is critical for maintaining the model's reasoning flow. We suggest always passing back all thinking blocks to the API. For more details, see the Preserving thinking blocks section.

Diferenças no pensamento entre versões de modelo

A API de Mensagens lida com pensamento de forma diferente entre os modelos Claude Sonnet 3.7 e Claude 4, principalmente no comportamento de redação e resumo.

Veja a tabela abaixo para uma comparação condensada:

Preservação de bloco de pensamento em Claude Opus 4.5 e posterior

A partir do Claude Opus 4.5 (e continuando no Claude Opus 4.6), blocos de pensamento de turnos anteriores do assistente são preservados no contexto do modelo por padrão. Isso difere dos modelos anteriores, que removem blocos de pensamento de turnos anteriores.

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

• Otimização de cache: Ao usar uso de ferramentas, blocos de pensamento preservados habilitam cache hits conforme são passados de volta com resultados de ferramentas e armazenados em cache incrementalmente entre o turno do assistente, resultando em economia de tokens em fluxos de trabalho multi-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 comportamento padrão para modelos Claude Opus 4.5 e posteriores (incluindo Opus 4.6)—nenhuma mudança de código ou cabeçalho beta necessário
• Compatibilidade com versões anteriores: Para aproveitar este 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

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

• Tokens used during thinking (output tokens)
• Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
• Standard text output tokens

When using summarized thinking:

• Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
• Output tokens (billed): The original thinking tokens that Claude generated internally
• Output tokens (visible): The summarized thinking tokens you see in the response
• No charge: Tokens used to generate the summary

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

Trabalhando com orçamentos de pensamento

• Otimização de orçamento: O orçamento mínimo é de 1.024 tokens. Sugerimos começar no mínimo e aumentar 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 aumento de latência. Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio ideal. Observe que o orçamento de pensamento é um alvo em vez de um limite rigoroso—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 conforme necessário.
• Orçamentos grandes: Para orçamentos de pensamento acima de 32k, recomendamos usar processamento em lote para evitar problemas de rede. Solicitações que empurram o modelo para pensar acima de 32k tokens causam solicitações de longa duração que podem atingir limites de tempo limite do sistema e limites de conexão aberta.
• Rastreamento de uso de tokens: Monitore o uso de tokens de pensamento para otimizar custos e desempenho.

Considerações de desempenho

• Tempos de resposta: Esteja preparado para tempos de resposta potencialmente mais longos devido ao processamento adicional necessário para o processo de raciocínio. Considere que gerar blocos de pensamento pode aumentar o tempo de resposta geral.
• Requisitos de streaming: Os SDKs exigem streaming quando max_tokens é maior que 21.333 para evitar timeouts HTTP em solicitações de longa duração. Esta é uma validação do lado do cliente, não uma restrição de API. Se você não precisar processar eventos incrementalmente, use .stream() com .get_final_message() (Python) ou .finalMessage() (TypeScript) para obter o objeto Message completo sem lidar com eventos individuais — veja Streaming Messages para detalhes. Ao fazer streaming, esteja preparado para lidar com blocos de conteúdo de pensamento e texto conforme chegam.

Compatibilidade de recursos

• Pensamento não é compatível com modificações de temperature ou top_k, bem como 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é-preenchimento de 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 de sistema em cache e definições de ferramentas continuarão funcionando quando os parâmetros de pensamento mudarem.

Diretrizes de uso

• Seleção de tarefa: Use pensamento estendido para tarefas particularmente complexas que se beneficiam de raciocínio passo a passo, como matemática, codificação e análise.
• Manipulação de contexto: Você não precisa remover blocos de pensamento anteriores você mesmo. A API Claude automaticamente ignora blocos de pensamento de turnos anteriores e eles não são incluídos ao calcular o uso de contexto.
• Engenharia de prompt: Revise nossas dicas de prompt de pensamento estendido se você quiser maximizar as capacidades de pensamento do Claude.

Próximos passos