Pensamento adaptativo

O 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. No Claude Fable 5 e no Claude Mythos 5, o pensamento está sempre ativado e não pode ser desativado; o pensamento adaptativo é o único modo de pensamento. No Claude Mythos Preview, o pensamento adaptativo é o modo padrão e é aplicado automaticamente sempre que thinking não está definido. Em vez de definir manualmente um orçamento de tokens de pensamento, o pensamento adaptativo permite que o Claude determine dinamicamente quando e quanto usar o pensamento estendido com base na complexidade de cada requisição. No Claude Opus 4.8 e no Claude Opus 4.7, o pensamento adaptativo é o único modo de pensamento suportado; o modo manual thinking: {type: "enabled", budget_tokens: N} não é mais aceito. No Claude Sonnet 5, o pensamento adaptativo está ativado por padrão; passe thinking: {type: "disabled"} para desativá-lo, e o modo manual {type: "enabled", budget_tokens: N} é rejeitado com um erro 400.



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
• Claude Mythos Preview (claude-mythos-preview), o pensamento adaptativo é o padrão; thinking: {type: "disabled"} não é suportado
• Claude Opus 4.8 (claude-opus-4-8), o pensamento adaptativo é o único modo de pensamento suportado. O pensamento está desativado a menos que você defina explicitamente thinking: {type: "adaptive"} na sua requisição; o modo manual thinking: {type: "enabled"} é rejeitado com um erro 400.
• Claude Opus 4.7 (claude-opus-4-7), o pensamento adaptativo é o único modo de pensamento suportado. O pensamento está desativado a menos que você defina explicitamente thinking: {type: "adaptive"} na sua requisição; o modo manual thinking: {type: "enabled"} é rejeitado com um erro 400.
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 5 (claude-sonnet-5), o pensamento adaptativo está ativado por padrão; o modo manual {type: "enabled"} é rejeitado com um erro 400.
• Claude Sonnet 4.6 (claude-sonnet-4-6)



Como o pensamento adaptativo funciona

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

O pensamento adaptativo também ativa automaticamente o pensamento intercalado. Isso significa que o 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 requisição de API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    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}")



Pensamento adaptativo com o parâmetro effort

Você pode combinar o pensamento adaptativo com o parâmetro effort para orientar quanto pensamento o Claude realiza. O nível de esforço atua como orientação flexível para a alocação de pensamento do 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?"}],
)

print(response.content[0].text)



Streaming com pensamento adaptativo

O pensamento adaptativo funciona perfeitamente com streaming. Os blocos de pensamento são transmitidos via eventos thinking_delta, assim como no modo de pensamento manual:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    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 turnos com pensamento ativado comecem com um bloco de pensamento.



Cache de prompt

Requisições consecutivas usando 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 de mudanças de modo.



Ajustando o comportamento de pensamento

O comportamento de acionamento do pensamento adaptativo pode ser influenciado por prompts. Se o Claude está 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 à formulação exata. Se uma formulação não produzir o comportamento desejado, experimente uma variante mais direta.

Você também pode direcionar o pensamento por mensagem a partir do turno do usuário. Adicionar "Please think hard before responding." a uma mensagem do usuário incentiva o Claude a pensar naquele turno; "Answer directly without deliberating." suprime o pensamento. Isso funciona independentemente do prompt do sistema e é útil quando apenas algumas requisiçõ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 de resposta). O parâmetro effort fornece orientação flexível adicional sobre quanto pensamento o Claude aloca. Juntos, eles oferecem controle efetivo sobre o custo.

Nos níveis de esforço high e max, o Claude pode pensar mais extensivamente 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 esforço.



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 reconstrua. Ler o texto do resumo para exibição não é problema: 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 requisição, mas blocos ignorados ainda adicionam tokens de entrada.

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

• Retentativas 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 seção 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 de campos e orientação 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 e 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.
• Cache de prompt: Com pensamento adaptativo, requisições consecutivas usando o mesmo modo de pensamento preservam os pontos de interrupção de cache. Alternar entre os modos 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).
• Janelas de contexto: Como os tokens de pensamento interagem com max_tokens e os limites da janela de contexto.



Próximos passos