Pensamento

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

O pensamento remove essa restrição. Quando o pensamento está ativo, o Claude trabalha o problema com suas próprias palavras antes de responder: ele reformula o que está sendo pedido, testa abordagens, verifica resultados intermediários e abandona caminhos que não se sustentam. Esse pensamento antecipado chega em blocos de conteúdo thinking antes da resposta, e o Claude se baseia nele para produzir a resposta final. É por isso que o pensamento melhora o desempenho em tarefas complexas como matemática, programação, análise e trabalho agêntico de longa duração, em que a qualidade da resposta depende de um trabalho intermediário que, de outra forma, seria comprimido na própria resposta ou ignorado.

O pensamento tem um custo: os tokens que o Claude gasta raciocinando são cobrados como tokens de saída, mesmo quando o texto do pensamento não é retornado para você, e eles contam para o max_tokens junto com o texto da resposta. Esta página aborda como o pensamento se comporta em toda a superfície da API: como ativá-lo, como ler sua saída e como gerenciar suas interações com ferramentas, "streaming", "prompt caching" (cache de prompt) e a "context window" (janela de contexto).

Como o pensamento funciona

Se o Claude pensa em uma determinada solicitação, e com que profundidade, depende da sua configuração de pensamento e da complexidade da solicitação.

Veja como o pensamento antecipado aparece em uma resposta: um ou mais blocos de conteúdo thinking chegam antes dos blocos text. O bloco de pensamento ainda é conteúdo gerado, como o bloco text que o segue, mas fica separado da resposta canônica. Cada bloco de pensamento também carrega um campo signature, uma cópia criptografada do raciocínio completo que você devolve sem alterações em conversas de múltiplos turnos e com uso de ferramentas (consulte Criptografia do pensamento):

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Você nem sempre vê esse texto, e o que você vê nunca é a cadeia de pensamento bruta: o texto em um bloco de pensamento é um resumo do raciocínio do Claude. O campo display na configuração de pensamento controla se esse resumo é retornado: "summarized" o retorna, enquanto "omitted", o padrão em muitos modelos, retorna blocos de pensamento com um campo thinking vazio. De qualquer forma, o bloco é cobrado da mesma maneira e devolvido da mesma maneira em conversas de múltiplos turnos. Consulte Controlando a exibição do pensamento para ver os padrões e detalhes por modelo.

Se o Claude usar ferramentas, o pensamento também pode aparecer entre chamadas de ferramentas. Consulte Pensamento com uso de ferramentas. Para o formato completo da resposta, consulte a referência da Messages API.

Configurando o pensamento

Na maioria dos modelos, o pensamento está ativado por padrão ou a um parâmetro de distância. A tabela a seguir mostra o que cada modelo faz com cada valor de thinking que uma solicitação pode enviar. Um erro 400 significa que a API rejeita a solicitação, e Solução de problemas do pensamento apresenta cada erro e sua correção.

Na tabela, "com esforço high ou inferior" significa que a solicitação funciona com esforço low, medium e high e retorna um erro 400 com xhigh ou max.

No Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview e Claude Haiku 5.5, o pensamento já está ativado e não precisa de configuração. display tem como padrão "omitted" nesses modelos, então o texto do pensamento fica oculto até que você opte por exibi-lo. Opte por exibi-lo com thinking: {"type": "adaptive", "display": "summarized"}, como fazem os exemplos a seguir.

No Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, o pensamento fica desativado até que você defina thinking: {type: "adaptive"}, o que permite que o Claude determine quando e com que profundidade pensar com base na solicitação. A mesma solicitação, com a string do modelo trocada, o ativa nesses modelos. Os exemplos a seguir definem display: "summarized" para que o texto do pensamento fique visível e usam um max_tokens generoso:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

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

Executar o exemplo imprime o pensamento resumido e, em seguida, a resposta:

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

Os tokens de pensamento contam para max_tokens, então defina-o alto o suficiente para deixar espaço tanto para o pensamento quanto para o texto da resposta. Consulte Controle de custos na página de direcionamento e Pensamento e a janela de contexto.

Desativando o pensamento

No Claude Sonnet 5, em que o pensamento está ativado por padrão, você pode desativá-lo:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

O Claude Opus 5 também tem o pensamento ativado por padrão e aceita thinking: {type: "disabled"} com "effort" (esforço) high ou inferior. Com esforço xhigh ou max, o pensamento não pode ser desativado: solicitações que combinam thinking: {type: "disabled"} com esses níveis de esforço retornam um erro 400. Essa restrição é aplicada em cada solicitação. Com o pensamento desativado, o Claude Opus 5 pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível. Consulte Executando com o pensamento desativado para ver mitigações via prompt.

O Claude Sonnet 5.5 também tem o pensamento ativado por padrão e rejeita thinking: {type: "disabled"} com um erro 400. Para desativar o pensamento antecipado, envie thinking: {type: "between_tools"} em vez disso. Essa é a configuração de pensamento mais baixa no Claude Sonnet 5.5 e é aceita com esforço high ou inferior. O modelo ainda retorna suas atualizações de progresso entre chamadas de ferramentas. Sem ferramentas, a resposta contém apenas texto, como acontece com disabled no Claude Sonnet 5. Consulte Executando sem pensamento antecipado para orientações sobre prompts.

O Claude Haiku 5.5 também tem o pensamento ativado por padrão e aceita thinking: {type: "disabled"} com esforço high ou inferior. Com esforço xhigh ou max, essa combinação retorna um erro 400. Para obter menos pensamento, reduza primeiro o nível de esforço. Com o pensamento desativado, o modelo pode pular uma chamada de ferramenta de que precisa quando você também solicita saída JSON. Um output_config.effort por mensagem que difere do nível em vigor também retorna um erro 400 enquanto o pensamento está desativado. Consulte Use o esforço para controlar o pensamento e Use o pensamento adaptativo com saída JSON e suas próprias ferramentas.

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 e Claude Mythos Preview rejeitam thinking: {type: "disabled"}. O pensamento não pode ser desativado nesses modelos.

Para verificar se um modelo aceita "disabled" antes de enviar uma solicitação, leia o valor capabilities.thinking.types.disabled.supported na Models API. Usando a Models API descreve o campo.

Se o seu modelo oferece suporte apenas ao pensamento estendido (consulte a tabela de configuração por modelo), configure-o com type: "enabled" e um valor de budget_tokens em vez disso. A página Pensamento estendido aborda essa configuração. E se qualquer configuração de pensamento retornar um erro 400, Solução de problemas do pensamento associa cada mensagem de erro à sua correção.

Lendo a saída do pensamento

Controlando a exibição do pensamento

O campo display na configuração de pensamento controla como o conteúdo do pensamento é retornado nas respostas da API. display funciona em ambos os modos: defina-o junto com type: "adaptive" ou type: "enabled". Ele aceita estes valores:

• "summarized": os blocos de pensamento contêm texto de pensamento resumido, um resumo legível do raciocínio do Claude. Este é o padrão no Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores.
• "omitted": os blocos de pensamento são retornados com um campo thinking vazio. O campo signature ainda carrega o pensamento completo criptografado para a continuidade em múltiplos turnos (consulte Criptografia do pensamento). Este é o padrão no Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Mythos Preview e Claude Haiku 5.5.
• "updates" (beta): os blocos de raciocínio são retornados com um campo thinking vazio, como em "omitted", e as breves atualizações de progresso que alguns modelos escrevem entre chamadas de ferramentas retornam como texto legível. Requer o cabeçalho beta thinking-display-updates-2026-08-18.

Defina display: "omitted" quando sua aplicação não exibe o conteúdo do pensamento aos usuários. O principal benefício é um tempo menor até o primeiro token de texto durante o streaming: o servidor pula totalmente 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.

Com display: "omitted", a resposta contém blocos thinking com um campo thinking vazio:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Tenha em mente o seguinte ao trabalhar com pensamento omitido:

• Você ainda é cobrado pelos tokens de pensamento completos. Omitir reduz a "latency" (latência), não o custo.
• Se você devolver blocos de pensamento em conversas de múltiplos turnos, devolva-os sem alterações. O servidor descriptografa a signature para reconstruir o pensamento original para a construção do prompt (consulte Preservando blocos de pensamento). Qualquer texto que você colocar no campo thinking de um bloco omitido devolvido é ignorado.
• display é inválido com thinking.type: "disabled" (não há nada para exibir) e com thinking.type: "between_tools" (apenas Claude Sonnet 5.5), que não aceita nenhum outro campo. Com between_tools, as atualizações de progresso ainda retornam com texto de resumo, como acontece com display: "updates" (consulte Atualizações de progresso).
• Ao usar thinking.type: "adaptive" e o modelo pular o pensamento em uma solicitação simples, nenhum bloco de pensamento é produzido, independentemente de display.
• Ao fazer streaming com display: "omitted", nenhum texto de pensamento é transmitido. Cada bloco de pensamento transmite um thinking_delta com uma string thinking vazia e, em seguida, seu signature_delta. Com display: "updates", apenas os blocos de atualização de progresso transmitem eventos thinking_delta que carregam texto. Consulte Streaming do pensamento para ver a sequência de eventos.

Pensamento resumido

Quando display é "summarized", o texto de pensamento que você recebe é um resumo do processo de pensamento completo do Claude, e não a cadeia de pensamento bruta. O pensamento resumido oferece todos os benefícios de inteligência do pensamento, ao mesmo tempo em que evita usos indevidos. Nenhuma configuração de display retorna a cadeia de pensamento bruta.

Tenha em mente o seguinte ao trabalhar com pensamento resumido:

• Você é cobrado pelos tokens de pensamento completos gerados pela solicitação original, não pelos tokens do resumo. A contagem de tokens de saída cobrada não corresponde à contagem de tokens que você vê na resposta.
• No Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores, as primeiras linhas da saída de pensamento são mais detalhadas, fornecendo um raciocínio minucioso que é particularmente útil para fins de engenharia de prompt. O Claude Mythos Preview resume desde o primeiro token, então seus blocos de pensamento não mostram esse preâmbulo detalhado.
• A sumarização preserva as ideias principais do processo de pensamento do Claude com latência adicional mínima, de modo que os resumos podem ser transmitidos à medida que chegam.
• A sumarização é processada por um modelo diferente daquele que você usa em suas solicitações. O modelo que pensa não vê a saída resumida.
• À medida que a Anthropic busca aprimorar o recurso de pensamento, o comportamento da sumarização está sujeito a alterações.

Para ver o raciocínio do modelo, leia os blocos thinking em vez de pedir o raciocínio no texto da resposta. No Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Fable 5, uma solicitação que tente 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 Mantenha o raciocínio nos blocos de pensamento para saber o que pedir em vez disso.

Streaming do pensamento

O pensamento funciona com streaming. Os blocos de pensamento são transmitidos como eventos thinking_delta dentro de eventos content_block_delta, seguidos por um único evento signature_delta logo antes do content_block_stop do bloco. Os blocos de texto são transmitidos em seguida, como de costume.

Os exemplos a seguir transmitem uma resposta com pensamento adaptativo, imprimindo os deltas de pensamento e de texto à medida que chegam:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    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:
        match event.type:
            case "content_block_start":
                print(f"\nStarting {event.content_block.type} block...")
            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "thinking_delta":
                        print(delta.thinking, end="", flush=True)
                    case "text_delta":
                        print(delta.text, end="", flush=True)

Para remontar blocos de pensamento completos com suas assinaturas após o streaming, use o auxiliar de acumulação de mensagens do seu SDK, stream.get_final_message(), em vez de concatenar os deltas você mesmo.

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}}

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 é aberto, chega um thinking_delta com uma string thinking vazia, segue-se um único signature_delta e o bloco é fechado. 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":"thinking_delta","thinking":""}}

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

Com display: "updates" (beta), os blocos de raciocínio são transmitidos como em "omitted". Cada bloco de atualização de progresso transmite seu texto como eventos thinking_delta antes do bloco tool_use que ele introduz. Uma pausa de vários segundos antes da abertura do bloco de atualização de progresso é normal:

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

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}}

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

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}}

Em "updates", trate um bloco como uma atualização de progresso assim que um de seus eventos thinking_delta carregar texto não vazio.

Para a mecânica geral de streaming, consulte Streaming de mensagens.

Pensamento e esforço

O parâmetro thinking controla se o Claude pensa em blocos de pensamento antes de responder; o parâmetro effort controla quanto trabalho o Claude dedica à resposta inteira, o que, no modo adaptativo, inclui com que frequência e com que profundidade ele pensa. Não passe adaptive como um valor de effort: adaptive é um modo de pensamento, não um nível de esforço.

Para saber o que cada nível de esforço faz com o comportamento do pensamento, consulte a tabela de comportamento do pensamento por nível na página Direcionando o pensamento. A página Esforço documenta o próprio parâmetro, incluindo quais níveis cada modelo suporta. No Claude Opus 4.5, o único modelo exclusivamente de pensamento estendido que suporta esforço, o esforço se combina com budget_tokens. Consulte Regras e ajuste do orçamento.

Com os dois controles separados dessa forma, escolha aquele que corresponde ao seu objetivo:

• Menor custo ou latência em uma carga de trabalho com pensamento ativado: reduza effort primeiro. Ele reduz a resposta inteira, incluindo o pensamento.
• O Claude está pensando raramente demais ou de forma superficial demais: aumente effort ou consulte Direcionando com que frequência Claude pensa na página de direcionamento.
• Você precisa do pensamento totalmente desativado: use thinking: {type: "disabled"} nos modelos que permitem isso (consulte a tabela de configuração por modelo). O Claude Sonnet 5.5 rejeita "disabled". Sua configuração mais baixa é thinking: {type: "between_tools"}, que desativa o pensamento antecipado.
• Você precisa de um teto rígido de gastos: use max_tokens. O esforço é uma orientação flexível. max_tokens é um limite estrito.

Pensamento com uso de ferramentas

O pensamento funciona junto com o uso de ferramentas, permitindo que o Claude raciocine sobre a seleção de ferramentas e processe os resultados das ferramentas. Duas restrições se aplicam:

1. Limitação de escolha de ferramenta (modo manual): o uso de ferramentas com pensamento estendido manual (thinking: {type: "enabled"}) suporta apenas tool_choice: {"type": "auto"} (o padrão) ou tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} resulta em erro, porque essas opções forçam o uso de ferramentas, o que é incompatível com o pensamento estendido manual. O pensamento adaptativo, inclusive em modelos em que o pensamento está ativado por padrão, suporta o uso forçado de ferramentas, exceto no Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 (consulte Preenchimento prévio da resposta e uso forçado de ferramentas). Onde o uso forçado de ferramentas é aceito, a resposta começa com a chamada de ferramenta e não tem bloco thinking.
2. Preservação dos blocos de pensamento: ao retornar resultados de ferramentas, você deve devolver à API os blocos de pensamento da mensagem do assistente, completos e sem modificações. Consulte Preservando blocos de pensamento.

Um loop de uso de ferramentas é um único turno do assistente. Da perspectiva do modelo, um turno do assistente não termina até que o Claude conclua sua resposta completa, que pode incluir várias chamadas de ferramentas e resultados. Toda esta sequência é um único turno do assistente:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

O turno inteiro é executado em um único modo de pensamento: você não pode alternar o pensamento no meio de um turno, inclusive durante o loop de uso de ferramentas. No modo estendido (manual), a API também exige que o turno final do assistente de uma solicitação com pensamento ativado comece com um bloco de pensamento. O modo adaptativo flexibiliza isso: nenhum turno do assistente precisa começar com um.

Conflitos no meio do turno são tratados de forma tolerante. Se você alternar o pensamento no meio de um turno (por exemplo, entre enviar uma chamada de ferramenta e retornar seu resultado), a API não gera erro. Em vez disso, ela desativa silenciosamente o pensamento para essa solicitação. Para preservar a qualidade do modelo, a API pode remover blocos de pensamento que criariam uma estrutura de turno inválida, ou desativar o pensamento quando o histórico da conversa for incompatível com o pensamento ativado. Para confirmar se o pensamento estava ativo, verifique a presença de blocos thinking na resposta.

Alterne entre turnos, não dentro deles. Planeje sua estratégia de pensamento no início de cada turno. Conclua o turno do assistente e, em seguida, altere a configuração de pensamento para o próximo:

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

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

Preservando blocos de pensamento

Quando o Claude invoca uma ferramenta, ele pausa a construção de sua resposta para aguardar informações externas. Quando você retorna o resultado da ferramenta, o Claude continua construindo essa mesma resposta, então seu raciocínio anterior ainda precisa estar presente. Devolva cada bloco thinking à API completo e sem modificações, junto com o bloco tool_use que ele acompanhava. Isso é importante por dois motivos:

1. Continuidade do raciocínio: os blocos de pensamento capturam o raciocínio passo a passo que levou às solicitações de ferramentas. Incluí-los permite que o Claude continue raciocinando de onde parou.
2. Manutenção do contexto: os resultados das ferramentas aparecem como mensagens do usuário na estrutura da API, mas fazem parte de um fluxo de raciocínio contínuo. Preservar os blocos de pensamento mantém esse fluxo entre as chamadas de API.

Em resumo:

• Obrigatório: dentro de um turno de uso de ferramentas, devolva os blocos de pensamento.
• Recomendado: entre turnos, devolva tudo.
• Permitido: fora do uso de ferramentas, omita o pensamento de turnos anteriores.

Você não precisa remover pensamentos antigos por conta própria. Devolva todos os blocos de pensamento em conversas de múltiplos turnos, e a API os filtra automaticamente, mantém os blocos necessários para preservar o raciocínio do modelo e cobra tokens de entrada apenas pelos blocos efetivamente mostrados ao Claude. Quais blocos de turnos anteriores são mantidos varia por modelo. Consulte Preservação de blocos de pensamento por modelo. Para substituir o padrão, use a estratégia de edição de contexto clear_thinking_20251015.

Dentro da mensagem mais recente do assistente, a sequência de blocos thinking consecutivos deve corresponder ao que o modelo gerou na solicitação original: você não pode reorganizá-los, editá-los ou descartá-los parcialmente. Isso inclui os blocos redacted_thinking.

Para um passo a passo completo de dois turnos com código em todos os SDKs, consulte Pensamento em fluxos de trabalho com ferramentas e múltiplos turnos. Ele define uma ferramenta, recebe uma resposta com pensamento e uso de ferramenta e devolve o turno do assistente junto com o resultado da ferramenta.

Pensamento intercalado

O "interleaved thinking" (pensamento intercalado) permite que o Claude pense entre chamadas de ferramentas, raciocinando sobre cada resultado de ferramenta antes de agir com base nele. Com o pensamento intercalado, o Claude pode:

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

Com o pensamento adaptativo, o pensamento intercalado é automático em todos os modelos que suportam pensamento adaptativo. Nenhum cabeçalho beta é necessário. No Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8 e Claude Opus 4.7, o raciocínio entre chamadas de ferramentas sempre aparece em blocos de pensamento. O Claude Haiku 4.5 não suporta pensamento intercalado. Em modelos que usam pensamento estendido manual, a intercalação requer um cabeçalho beta e altera a forma como o orçamento de pensamento é contabilizado. Pensamento intercalado no modo manual aborda as regras por modelo e o comportamento do cabeçalho específico de cada plataforma.

Com o pensamento intercalado, a alocação de pensamento pode abranger todo o turno do assistente, em vez de uma única resposta. O pensamento intercalado é suportado apenas para ferramentas usadas por meio da Messages API.

Para uma comparação prática que mostra o que o pensamento intercalado muda em um fluxo de trabalho com duas ferramentas, consulte Como o pensamento intercalado muda o fluxo.

Atualizações de progresso entre chamadas de ferramentas

No Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Fable 5, o modelo pode escrever uma atualização de progresso entre chamadas de ferramentas. Uma atualização de progresso é uma nota sobre o que o modelo acabou de descobrir e o que está prestes a fazer em seguida, escrita para a pessoa que acompanha o agente, e não como raciocínio. Cada uma retorna como seu próprio bloco thinking com sua própria signature, separado de qualquer bloco de raciocínio no mesmo ponto. Ela fica imediatamente antes do bloco tool_use ou server_tool_use que introduz. No máximo uma atualização de progresso precede cada chamada de ferramenta, e o modelo pode pular qualquer uma delas. As atualizações de progresso não são pensamento intercalado: elas aparecem independentemente de blocos de raciocínio aparecerem entre as chamadas de ferramentas, e uma resposta pode conter ambos.

O que um bloco de atualização de progresso contém depende de display:

No Claude Sonnet 5.5, a configuração de pensamento mais baixa é thinking: {type: "between_tools"}. Ela desativa o pensamento antecipado, e cada atualização de progresso retorna com seu texto de resumo, como aconteceria com display: "updates". between_tools é aceito apenas com esforço high ou inferior. Com xhigh ou max, uma solicitação com ele retorna um erro 400. between_tools não aceita nenhum outro campo: display, budget_tokens ou block_binding enviados com ele retornam um erro 400. A configuração não precisa de cabeçalho beta e funciona em todas as plataformas que oferecem o Claude Sonnet 5.5. Devolva os blocos sem alterações: um bloco de atualização de progresso que você devolve fornece ao modelo a nota completa que ele escreveu, não o resumo.

Use display: "updates" para uma interface de agente que mantém o raciocínio oculto e mostra ao usuário uma linha de status a cada etapa. Com ele, qualquer bloco thinking com texto não vazio é uma atualização de progresso, então renderize esses blocos e nada mais. Ele está em beta e requer o cabeçalho beta thinking-display-updates-2026-08-18 (para enviá-lo no Amazon Bedrock, Google Cloud ou Microsoft Foundry, consulte Recursos beta em outras plataformas). Sem ele, o valor é rejeitado com o mesmo erro 400 invalid_request_error de um valor de display desconhecido.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": [
    {
      "name": "edit_file",
      "description": "Replace the contents of a file in the repository.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "The login test fails after an hour of uptime. Find out why and fix it."
    }
  ]
}

Com "updates", o início da resposta que segue um tool_result tem esta aparência. O primeiro bloco é de raciocínio e permanece vazio, como ficaria com "omitted". O segundo carrega texto, então é uma atualização de progresso. Com "summarized", ambos os blocos carregam texto e, com "omitted", ambos ficam vazios.

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EqMBCkYICxIM..."
    },
    {
      "type": "thinking",
      "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.",
      "signature": "Es8CCkYICxIM..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "edit_file",
      "input": { "path": "auth.py", "content": "..." }
    }
  ]
}

Tenha em mente o seguinte ao trabalhar com atualizações de progresso:

• Devolva os blocos de atualização de progresso sem alterações junto com o restante do turno do assistente, como qualquer outro bloco thinking.
• O texto que você recebe é um resumo da atualização de progresso, normalmente uma ou duas frases. Não dependa do seu tamanho. A atualização de progresso conta para usage.output_tokens com seu tamanho completo, não com o do resumo.
• Um bloco de atualização de progresso pode retornar com um campo thinking vazio com qualquer valor de display. Não renderize nada para um bloco vazio. Com "updates", ele tem a mesma aparência de um bloco de raciocínio vazio e não precisa de tratamento separado.
• Quando uma resposta para em max_tokens, model_context_window_exceeded ou stop_sequence logo após uma chamada de ferramenta ou um resultado de ferramenta, seu último bloco pode ser um bloco de atualização de progresso que substitui o trabalho que o modelo não havia concluído. Com "updates" e "summarized", seu texto é exatamente This part of the response was interrupted before it finished. e você pode exibi-lo como qualquer outra atualização. Com "omitted", ele fica vazio. Para continuar, devolva o turno do assistente sem alterações e acrescente uma nova mensagem user (com um tool_result para cada bloco tool_use nesse turno).
• Ao fazer streaming, espere uma pausa de vários segundos antes da abertura de um bloco de atualização de progresso. Consulte o rastreamento de "updates" em Streaming do pensamento.
• Esses modelos escrevem menos atualizações de progresso com esforço mais alto e em cadeias longas de ferramentas. Se sua interface depende delas, consulte Peça atualizações de progresso voltadas ao usuário ou, para o Claude Opus 5.5, Atualizações de progresso voltadas ao usuário. Para o Claude Sonnet 5.5, consulte Atualizações de progresso voltadas ao usuário.

Preservação de blocos de pensamento por modelo

Se os blocos de pensamento de turnos anteriores do assistente permanecem no contexto por padrão depende do modelo:

• Manter todos os turnos anteriores: Claude Opus 4.5 e modelos Opus posteriores, Claude Sonnet 4.6 e modelos Sonnet posteriores, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview.
• Manter apenas o último turno: modelos Opus e Sonnet anteriores, e todos os modelos Haiku até o Claude Haiku 4.5. Quando você envia blocos de pensamento mais antigos de volta, a API os remove automaticamente. Você não precisa removê-los por conta própria.

A preservação traz dois benefícios:

• Otimização de cache: blocos de pensamento preservados permitem acertos de cache durante o uso de ferramentas, pois são enviados de volta com os resultados das ferramentas e armazenados em cache de forma incremental ao longo do turno do assistente, resultando em economia de tokens em fluxos de trabalho de várias etapas.
• Nenhum impacto na inteligência: preservar blocos de pensamento não tem efeito negativo no desempenho do modelo.

A contrapartida é o uso de contexto: conversas longas consomem mais espaço de contexto em modelos que mantêm tudo, porque os blocos de pensamento retidos contam como entrada como qualquer outro histórico de conversa (consulte Pensamento e a janela de contexto). O comportamento é automático em ambos os regimes. Nenhuma alteração de código ou cabeçalho beta é necessária, e você deve continuar enviando de volta blocos de pensamento completos e não modificados, conforme descrito em Preservando blocos de pensamento. Para substituir o padrão em qualquer direção, use a limpeza de blocos de pensamento.

Trocando de modelo no meio da conversa. Continue enviando de volta os blocos de pensamento sem alterações quando você trocar de modelo, por exemplo após um fallback por recusa do classificador. Um bloco de pensamento só pode ser lido pelo modelo que o produziu e por certos outros modelos, e a API ignora ou descarta os blocos que o modelo de destino não consegue ler. No Claude Fable 5.1 e no Claude Mythos 5.1 a direção importa: eles leem os blocos de pensamento de modelos anteriores, e apenas os dois leem os blocos um do outro, então trocar para eles mantém o raciocínio da conversa e trocar deles para qualquer outro modelo o descarta (consulte como os blocos descartados são cobrados e relatados). O Claude Opus 5.5 lê os blocos de pensamento do Claude Opus 5 e os de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, os do Claude Haiku 5.5, mas não os dos modelos Claude Fable e Claude Mythos; na Claude API, o Claude Fable 5.1 e o Claude Mythos 5.1 leem os blocos do Claude Opus 5.5. Uma troca do Claude Opus 5.5 para o Claude Fable 5.1 na Claude API mantém o raciocínio dos turnos anteriores; uma troca do Claude Fable 5.1 para o Claude Opus 5.5 o descarta. O Claude Sonnet 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores e, na Claude API e no Google Cloud, do Claude Haiku 5.5, mas não do Claude Opus 5, Claude Opus 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. Na Claude API e no Google Cloud, o Claude Opus 5.5 lê os blocos do Claude Sonnet 5.5 e nenhum outro modelo o faz: uma troca do Claude Sonnet 5.5 para o Claude Opus 5.5 na Claude API e no Google Cloud mantém o raciocínio dos turnos anteriores, e qualquer outra troca a partir do Claude Sonnet 5.5 o descarta. O Claude Haiku 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores, mas não do Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. Na Claude API e no Google Cloud, o Claude Opus 5.5 e o Claude Sonnet 5.5 leem os blocos do Claude Haiku 5.5 e nenhum outro modelo o faz. Remova você mesmo os blocos thinking e redacted_thinking anteriores apenas para economizar tokens de entrada em modelos que os ignoram em vez de descartá-los, e nunca ao resgatar um crédito de fallback, que exige o corpo inalterado.

Pensamento preservado

O pensamento preservado determina se o modelo pode usar um bloco de pensamento que você envia de volta de um turno anterior. A partir do Claude Fable 5.1, a API verifica a signature de cada bloco thinking ou redacted_thinking em uma solicitação quanto a duas coisas:

• O modelo que o produziu. Cada modelo lê seus próprios blocos de pensamento e os de um conjunto fixo de outros modelos. O Claude Fable 5.1 lê blocos do Claude Opus 5 e, na Claude API, do Claude Opus 5.5; nem o Claude Opus 5 nem o Claude Opus 5.5 leem blocos do Claude Fable 5.1. A API descarta um bloco que o modelo atual não consegue ler, sem erro e sem cobrá-lo. Consulte Trocar de modelo no meio da conversa.
• Tudo o que foi enviado antes dele. Um bloco permanece válido apenas enquanto o prompt system de nível superior, as tools e as mensagens anteriores a ele permanecem inalterados. Se qualquer um deles mudar, esse bloco e todos os blocos de pensamento posteriores se tornam inválidos, e a API rejeita a solicitação com um erro 400 ou descarta os blocos inválidos, conforme sua escolha. Consulte Manter o prefixo inalterado.

Os blocos de pensamento do Claude Sonnet 5.5 e do Claude Haiku 5.5 também estão vinculados à conta que os produziu. Consulte Os blocos de pensamento permanecem com a conta que os produziu para saber onde a API aplica isso.

A verificação de modelo se aplica a todas as contas. A API aplica a verificação de prefixo por padrão para contas criadas em ou após 31 de agosto de 2026, 00:00 UTC. Em contas mais antigas, ela aplica a verificação apenas em solicitações que definem thinking.block_binding.prefix_mismatch_behavior. Torne sua integração somente de acréscimo (append-only), independentemente da idade da sua conta, para que o mesmo código funcione em todas as contas, incluindo contas mais novas com aplicação por padrão.

Para manter o pensamento válido, envie cada turno do assistente de volta exatamente como você o recebeu e adicione novas mensagens apenas no final de messages. Se o seu código constrói o array messages por conta própria, a página de Pensamento preservado aborda:

• O que conta como uma edição e como verificar se o seu código faz uma.
• O recurso da API que substitui cada edição comum: mensagens de sistema no meio da conversa para novas instruções e lembretes por turno, blocos tool_addition e tool_removal para alterações de ferramentas, output_config por mensagem para alterações de esforço, e compactação e edição de contexto no lado do servidor para redução.
• Compactação no lado do cliente: quais padrões mantêm o pensamento válido e quais não.
• O cabeçalho beta thinking-binding-controls-2026-08-01. Ele adiciona um campo block_binding.prefix_mismatch_behavior ("error" ou "drop_block") à configuração de pensamento e um array input_transformations a cada resposta. O array lista cada bloco de pensamento que a API descartou, ou que falhou na verificação de prefixo e foi deixado passar.

Pensamento e cache de prompt

O "prompt caching" (cache de prompt) interage com o pensamento de algumas maneiras específicas. As regras a seguir se aplicam em ambos os modos de pensamento.

Alterações de configuração invalidam o cache. A configuração de pensamento e o nível de effort resolvido são renderizados no próprio prompt, portanto alterar qualquer um deles inicia um novo prefixo de cache. Alternar entre adaptive, enabled e disabled, alterar budget_tokens e alterar o valor de esforço invalidam os pontos de interrupção de cache: pontos de interrupção no nível de mensagem sempre falham, e pontos de interrupção de ferramentas e do prompt do sistema também podem falhar, dependendo de onde o modelo renderiza a configuração. Trate qualquer alteração de pensamento ou de esforço de nível superior como um reinício do cache. Em modelos que suportam esforço por mensagem, uma alteração de esforço transmitida em uma mensagem role: "system" dentro de messages mantém o prefixo em cache intacto. Solicitações consecutivas que mantêm a mesma configuração preservam o cache, e definir um parâmetro explicitamente com seu valor padrão equivale a omiti-lo. Um bloco de pensamento que a API descarta sob qualquer condição de pensamento preservado altera o prefixo em cache a partir da posição desse bloco. Blocos enviados de volta sem alterações mantêm o cache intacto. Uma demonstração prática com a saída de uso está na página Direcionando o pensamento.

Blocos de pensamento são armazenados em cache com os resultados das ferramentas. Durante um loop de uso de ferramentas, o cache ocorre quando você faz uma solicitação de acompanhamento que inclui resultados de ferramentas. Nesse ponto, o histórico de conversa anterior, incluindo seus blocos de pensamento, pode ser armazenado em cache, e esses blocos de pensamento em cache contam como tokens de entrada nas suas métricas de uso quando lidos do cache. Isso ocorre automaticamente, mesmo sem marcadores cache_control explícitos, e se comporta da mesma forma para pensamento regular e intercalado. A contrapartida: blocos de pensamento que você nunca mais vê nas respostas ainda contribuem para o uso de tokens de entrada quando lidos do cache.

Se os blocos anteriores estão no contexto depende do modelo. O padrão de preservação rege isso. Em modelos que mantêm tudo, os blocos de pensamento dos turnos anteriores permanecem em cache e no contexto. Em modelos que mantêm apenas o último turno, assim que você envia uma mensagem de usuário que não é um resultado de ferramenta, todos os blocos de pensamento anteriores são removidos do contexto. Nesses modelos, uma conversa como esta:

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

é processada como se os blocos de pensamento nunca tivessem existido:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

Em modelos que mantêm tudo, a mesma solicitação mantém thinking_block_1 e thinking_block_2 no contexto e no cache.

A degradação remove o pensamento do histórico armazenável em cache. Se o pensamento for desativado no meio do turno e você enviar conteúdo de pensamento no turno atual de uso de ferramentas, o conteúdo de pensamento é removido e o pensamento permanece desativado para essa solicitação (consulte degradação graciosa). O pensamento intercalado amplifica os efeitos de invalidação de cache, porque blocos de pensamento podem ocorrer entre várias chamadas de ferramentas.

Pensamento e a janela de contexto

max_tokens, que inclui todo o pensamento que Claude gera no turno atual, é aplicado como um limite estrito. Nos modelos Claude 4.5 e mais recentes, se os tokens de entrada mais max_tokens excederem o tamanho da "context window" (janela de contexto), a API aceita a solicitação. Se a geração então atingir o limite da janela de contexto, ela para com stop_reason: "model_context_window_exceeded" em vez de retornar um erro. Em modelos anteriores, a API retorna um erro de validação. Consulte Lidando com motivos de parada.

Como o pensamento conta na janela depende de quando ele foi gerado:

• O pensamento do turno atual sempre conta para max_tokens, é cobrado como tokens de saída e ocupa espaço na janela de contexto durante o turno que o gerou.
• O pensamento de turnos anteriores depende do padrão de preservação. Em modelos que mantêm todos os turnos anteriores, os blocos de pensamento anteriores permanecem no contexto, contam para a janela e são cobrados como tokens de entrada, como o restante do histórico da conversa. Em modelos que mantêm apenas o último turno, a API remove automaticamente os blocos de pensamento mais antigos quando você os envia de volta, de modo que eles não consomem espaço na janela nem tokens de entrada.

Na prática:

• Em modelos que mantêm tudo, planeje sua janela de contexto como se o pensamento fosse um histórico de conversa comum, porque ele é. Sessões agênticas longas acumulam pensamento no contexto. Use a limpeza de blocos de pensamento se precisar recuperar espaço.
• Em modelos que mantêm apenas o último turno, o pensamento é apenas um custo por turno: o pensamento de cada turno conta para o max_tokens desse turno e depois sai da janela.

Os diagramas a seguir ilustram o regime de apenas o último turno (remoção). O primeiro mostra uma conversa de vários turnos: o bloco de pensamento de cada turno é gerado na saída, mas não é levado para a entrada dos turnos posteriores.

O segundo mostra o mesmo regime com uso de ferramentas: o pensamento permanece no contexto junto com seu resultado de ferramenta durante o turno do assistente e depois sai no próximo turno do usuário.

Use a API de contagem de tokens para obter contagens precisas para o seu caso de uso específico, especialmente para conversas de vários turnos que incluem pensamento.

Criptografia do pensamento

O conteúdo completo do pensamento é criptografado e retornado no campo signature de cada bloco de pensamento. A API usa a assinatura para verificar se os blocos de pensamento foram gerados por Claude quando você os devolve.

Tenha em mente o seguinte ao trabalhar com assinaturas:

• Só é estritamente necessário devolver blocos de pensamento ao usar ferramentas com pensamento. Caso contrário, você pode omitir os blocos de pensamento de turnos anteriores. Se você os devolver, se a API os mantém ou os remove depende do modelo (consulte Preservação de blocos de pensamento por modelo). Use a edição de contexto para configurar isso.
• Ao devolver blocos de pensamento, devolva tudo exatamente como recebeu, para manter a consistência e evitar possíveis problemas.
• Ao fazer streaming de respostas, a assinatura chega como um signature_delta dentro de um evento content_block_delta logo antes do evento content_block_stop.
• Os valores de signature são significativamente mais longos no Claude 4 e em modelos posteriores do que em modelos anteriores.
• O campo signature é opaco: não o interprete nem o analise.
• Os valores de signature são compatíveis entre plataformas (a Claude API, Amazon Bedrock e Google Cloud). Valores gerados em uma plataforma funcionam em outra, exceto que os blocos de pensamento do Claude Sonnet 5.5 e do Claude Haiku 5.5 funcionam apenas na conta que os produziu ou em uma conta vinculada a ela. Consulte Os blocos de pensamento permanecem com a conta que os produziu.

Blocos de pensamento redigidos

Além dos blocos thinking regulares, a API pode retornar blocos redacted_thinking quando partes do raciocínio de Claude são redigidas por motivos de segurança. Um bloco redacted_thinking contém conteúdo de pensamento criptografado em um campo data, sem texto legível:

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

O campo data é opaco e criptografado. Assim como o campo signature em blocos de pensamento regulares, devolva os blocos redacted_thinking à API sem alterações ao continuar uma conversa de vários turnos com ferramentas.

Limites e compatibilidade de recursos

Parâmetros de amostragem

No Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 e Claude Haiku 5.5, valores não padrão de temperature, top_p ou top_k retornam um erro 400 em todas as solicitações, independentemente de o pensamento ser usado. Nesses modelos, o padrão de top_p é 0.99, então um top_p de 1 retorna um erro 400, assim como uma solicitação que inclui tanto temperature quanto top_p, mesmo com seus valores padrão. Consulte Remova os parâmetros de amostragem. Em modelos mais antigos, a restrição se aplica apenas enquanto o pensamento está ativado: temperature e top_k são incompatíveis com o pensamento, e top_p é permitido com valores entre 0,95 e 1.

Preenchimento prévio da resposta e uso forçado de ferramentas

Os modelos Claude 4.6 e posteriores e o Claude Mythos Preview rejeitam um turno final do assistente preenchido previamente com um erro 400, esteja o pensamento ativado ou não (consulte Prefill não suportado). Em modelos anteriores, você não pode preencher previamente a resposta do assistente enquanto o pensamento está ativado. O uso forçado de ferramentas (tool_choice: {"type": "any"} ou {"type": "tool", ...}) é incompatível com o pensamento estendido manual, mas funciona com o pensamento adaptativo. As exceções são o Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, que rejeitam o uso forçado de ferramentas em todas as solicitações com um erro 400. Nesses modelos, use tool_choice: {"type": "auto"} com uso estrito de ferramentas ou saídas estruturadas. Onde o uso forçado de ferramentas é aceito, a resposta começa com a chamada da ferramenta e não tem bloco thinking. Para permitir que o modelo pense antes de chamar uma ferramenta, use tool_choice: {"type": "auto"} e diga no prompt quando usar a ferramenta. Consulte Pensamento com uso de ferramentas.

Limites de saída

Cada modelo aceita max_tokens até o teto listado aqui. Na Message Batches API, o cabeçalho beta output-300k-2026-03-24 eleva esse teto para os modelos com um teto de lotes listado.

Consulte a visão geral dos modelos para ver os limites dos modelos legados.

Solicitações longas

O SDK exige streaming quando max_tokens é maior que 21.333, para evitar timeouts HTTP em solicitações de longa duração. Esta é uma validação no lado do cliente, não uma restrição da API. Se você não precisa processar eventos de forma incremental, use .stream() com .get_final_message() para obter o objeto Message completo sem precisar montá-lo você mesmo a partir de eventos individuais. Consulte Streaming de mensagens. Espere tempos de resposta mais longos quando o pensamento estiver ativo, porque gerar blocos de pensamento adiciona tempo de processamento. Para cargas de trabalho que levam o pensamento acima de aproximadamente 32 mil tokens por solicitação, use o processamento em lote para evitar problemas de rede: essas solicitações podem durar o suficiente para atingir timeouts do sistema e limites de conexões abertas.

Próximos passos