Pensamento adaptativo

O "adaptive thinking" (pensamento adaptativo) é a forma recomendada de usar o pensamento estendido com Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6, e o único modo de pensamento no Claude Fable 5 e no Claude Mythos 5. Em vez de definir manualmente um orçamento de tokens de pensamento, o pensamento adaptativo permite que Claude determine dinamicamente quando e quanto usar o pensamento estendido com base na complexidade de cada solicitação. Os padrões e restrições por modelo estão listados em Modelos suportados.



Modelos suportados

O pensamento adaptativo é suportado nos seguintes modelos:

• Claude Fable 5 (claude-fable-5) e Claude Mythos 5 (claude-mythos-5), o pensamento adaptativo está sempre ativado; thinking: {type: "disabled"} não é suportado. Nenhum dos dois modelos está disponível sob retenção zero de dados.
• Claude Mythos Preview (claude-mythos-preview), o pensamento adaptativo é o padrão; thinking: {type: "disabled"} não é suportado, e o {type: "enabled", budget_tokens: N} manual ainda é aceito.
• Claude Opus 4.8 (claude-opus-4-8), o pensamento adaptativo é o único modo de pensamento suportado. O pensamento fica desativado a menos que você defina explicitamente thinking: {type: "adaptive"} na sua solicitação; o thinking: {type: "enabled"} manual é rejeitado com um erro 400.
• Claude Opus 4.7 (claude-opus-4-7), o pensamento adaptativo é o único modo de pensamento suportado. O pensamento fica desativado a menos que você defina explicitamente thinking: {type: "adaptive"} na sua solicitação; o thinking: {type: "enabled"} manual é rejeitado com um erro 400.
• Claude Opus 4.6 (claude-opus-4-6), o pensamento adaptativo fica desativado a menos que você defina explicitamente thinking: {type: "adaptive"}; o {type: "enabled", budget_tokens: N} manual ainda é aceito, mas está descontinuado.
• Claude Sonnet 5 (claude-sonnet-5), o pensamento adaptativo está ativado por padrão; passe thinking: {type: "disabled"} para desativá-lo. O {type: "enabled"} manual é rejeitado com um erro 400.
• Claude Sonnet 4.6 (claude-sonnet-4-6), o pensamento adaptativo fica desativado a menos que você defina explicitamente thinking: {type: "adaptive"}; o {type: "enabled", budget_tokens: N} manual ainda é aceito, mas está descontinuado.



Como funciona o pensamento adaptativo

No modo adaptativo, o pensamento é opcional para o modelo. Claude avalia a complexidade de cada solicitação e determina se e quanto usar o pensamento estendido. No nível padrão de effort (high), Claude quase sempre pensa. Em níveis de esforço mais baixos, Claude pode pular o pensamento para problemas mais simples.

O pensamento adaptativo também habilita automaticamente o pensamento intercalado. Isso significa que Claude pode pensar entre chamadas de ferramentas, tornando-o especialmente eficaz para fluxos de trabalho agênticos.



Como usar o pensamento adaptativo

Defina thinking.type como "adaptive" na sua solicitação de API. Os exemplos também definem thinking.display como "summarized" para tornar o texto de pensamento visível: nos modelos mais recentes, display tem como padrão "omitted", que retorna blocos de pensamento com um campo thinking vazio. Consulte Controlando a exibição do pensamento para detalhes.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

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

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.



Pensamento adaptativo com o parâmetro effort

Você pode combinar o pensamento adaptativo com o parâmetro effort para orientar quanto pensamento Claude realiza. O nível de esforço atua como uma orientação flexível para a alocação de pensamento de Claude:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)



Streaming com pensamento adaptativo

O pensamento adaptativo funciona com streaming. Os blocos de pensamento são transmitidos por streaming através de eventos thinking_delta, da mesma forma que no modo de pensamento manual. Como nos exemplos anteriores, thinking.display: "summarized" torna o texto de pensamento transmitido visível:

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)



Pensamento adaptativo vs manual vs desativado



Considerações importantes



Mudanças de validação

Ao usar o pensamento adaptativo, os turnos anteriores do assistente não precisam começar com blocos de pensamento. Isso é mais flexível do que o modo manual, onde a API exige que os turnos com pensamento habilitado comecem com um bloco de pensamento.

Separadamente, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7 e Claude Sonnet 5 rejeitam valores não padrão de temperature, top_p e top_k com um erro 400. Isso se aplica a todas as solicitações nesses modelos, independentemente de o pensamento estar ativo.



Cache de prompt

Solicitações consecutivas usando o pensamento adaptive preservam os pontos de interrupção do cache de prompt. No entanto, alternar entre os modos de pensamento adaptive e enabled/disabled quebra os pontos de interrupção de cache para mensagens. Prompts do sistema e definições de ferramentas permanecem em cache independentemente das mudanças de modo.



Ajustando o comportamento de pensamento

O comportamento de acionamento do pensamento adaptativo pode ser ajustado via prompt. Se Claude estiver pensando com mais ou menos frequência do que você gostaria, você pode adicionar orientação ao seu prompt do sistema:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multi-step reasoning. When in doubt, respond directly.

Para incentivar o pensamento, use uma frase como:

This task involves multi-step reasoning. Think carefully before responding.

A eficácia do direcionamento pode ser sensível à redação exata. Se uma formulação não produzir o comportamento desejado, tente uma variante mais direta.

Você também pode direcionar o pensamento por mensagem a partir do turno do usuário. Anexar "Please think hard before responding." a uma mensagem do usuário incentiva Claude a pensar naquele turno; "Answer directly without deliberating." o suprime. Isso funciona independentemente do prompt do sistema e é útil quando apenas algumas solicitações em uma conversa justificam raciocínio estendido.



Controle de custos

Use max_tokens como um limite rígido na saída total (pensamento + texto da resposta). O parâmetro effort fornece orientação flexível adicional sobre quanto pensamento Claude aloca. Juntos, eles oferecem controle efetivo sobre o custo.

Nos níveis de effort high e max, Claude pode pensar de forma mais extensa e pode ter maior probabilidade de esgotar o orçamento de max_tokens. Se você observar stop_reason: "max_tokens" nas respostas, considere aumentar max_tokens para dar mais espaço ao modelo, ou reduzir o nível de effort.



Trabalhando com blocos de pensamento

Os conceitos a seguir se aplicam a todos os modelos que suportam pensamento estendido, independentemente de você usar o modo adaptativo ou manual.



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.



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.

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Para exemplos de código e comportamento de streaming com display: "omitted", consulte Controlando a exibição do pensamento na página de pensamento estendido. Os exemplos lá usam type: "enabled"; com pensamento adaptativo, use:

thinking = {"type": "adaptive", "display": "omitted"}



Criptografia do 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.



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

No Claude Fable 5 e no Claude Mythos 5, a cadeia de pensamento bruta nunca é retornada. Os blocos de pensamento que você recebe são blocos thinking regulares, não redacted_thinking. A configuração thinking.display funciona da mesma forma que em outros modelos:

• "summarized" retorna um resumo legível do raciocínio.
• "omitted" (o padrão nesses modelos) ainda inclui blocos thinking nas respostas, mas seu campo thinking é uma string vazia.

Para o formato de resposta dos blocos de pensamento, consulte a referência da API de Messages.

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

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

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

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

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



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.



Tópicos adicionais

A página de pensamento estendido aborda vários tópicos com mais detalhes, com exemplos de código específicos por modo:

• Uso de ferramentas com pensamento: As mesmas regras se aplicam ao pensamento adaptativo: preserve os blocos de pensamento entre chamadas de ferramentas e esteja ciente das limitações de tool_choice quando o pensamento está ativo.
• Pensamento estendido com cache de prompt: Exemplos de código para cache com blocos de pensamento. O comportamento de cache específico do modo adaptativo é abordado em Cache de prompt anteriormente nesta página.
• Janelas de contexto: Como os tokens de pensamento interagem com max_tokens e os limites da janela de contexto.



Próximos passos