Construindo com pensamento estendido

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

Modelos suportados

O pensamento estendido é suportado nos seguintes modelos:

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)

O comportamento da API difere entre os modelos Claude Sonnet 3.7 e Claude 4, mas as formas da API permanecem exatamente as mesmas.

Para mais informações, consulte Diferenças no pensamento entre versões de modelos.

Como funciona o pensamento estendido

Quando o pensamento estendido está 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": "Deixe-me analisar isso passo a passo...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Com base na minha análise..."
    }
  ]
}

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

Como usar o pensamento estendido

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

Shell

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-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "Existe um número infinito de números primos tal que n mod 4 == 3?"
        }
    ]
}'

Para ativar o pensamento 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 o pensamento estendido.

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, este limite se aplica aos tokens de pensamento completos, e não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta permitindo análises mais minuciosas para problemas complexos, embora Claude possa não usar todo o orçamento alocado, especialmente em faixas acima de 32k.

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

Pensamento resumido

Com o pensamento estendido habilitado, a API Messages para modelos Claude 4 retorna um resumo do processo de pensamento completo do Claude. O pensamento resumido fornece todos os benefícios de inteligência do pensamento estendido, enquanto previne o uso indevido.

Aqui estão algumas considerações importantes para o 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 faturada não corresponderá à contagem de tokens que você vê na resposta.
• As primeiras linhas da saída de pensamento são mais verbosas, fornecendo raciocínio detalhado que é particularmente útil para fins de engenharia de prompt.
• Como a Anthropic busca melhorar o recurso de pensamento estendido, o comportamento de resumo está sujeito a mudanças.
• O resumo preserva as ideias-chave do processo de pensamento do Claude com latência mínima adicionada, permitindo uma experiência de usuário transmissível e migração fácil dos modelos Claude Sonnet 3.7 para Claude 4.
• O resumo é processado por um modelo diferente daquele que você direciona em suas solicitações. O modelo de pensamento não vê a saída resumida.

Claude Sonnet 3.7 continua a retornar saída de pensamento completa.

Em casos raros onde você precisa de acesso à saída de pensamento completa para modelos Claude 4, entre em contato com nossa equipe de vendas.

Transmissão de pensamento

Você pode transmitir respostas de pensamento estendido usando eventos enviados pelo servidor (SSE).

Quando a transmissão está habilitada para pensamento estendido, você recebe conteúdo de pensamento via eventos thinking_delta.

Para mais documentação sobre transmissão via API Messages, consulte Transmissão de Mensagens.

Aqui está como lidar com transmissão com pensamento:

Shell

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-20250514",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "Quanto é 27 * 453?"
        }
    ]
}'

Exemplo de saída de transmissão:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-20250514", "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": "Deixe-me resolver isso passo a passo:\n\n1. Primeiro quebrar 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Deltas de pensamento adicionais...

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": "27 * 453 = 12.231"}}

// Deltas de texto adicionais...

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

Ao usar transmissão com pensamento habilitado, você pode notar que o texto às vezes chega em blocos maiores alternando com entrega menor, token por token. Este é o comportamento esperado, especialmente para conteúdo de pensamento.

O sistema de transmissão precisa processar conteúdo em lotes para desempenho ideal, o que pode resultar neste padrão de entrega “em blocos”, com possíveis atrasos entre eventos de transmissão. Estamos trabalhando continuamente para melhorar esta experiência, com futuras atualizações focadas em fazer o conteúdo de pensamento transmitir de forma mais suave.

Pensamento estendido com uso de ferramentas

O pensamento 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 pensamento estendido com uso de ferramentas, esteja ciente das seguintes limitações:

1. Limitação de escolha de ferramenta: O uso de ferramentas com pensamento suporta apenas tool_choice: {"type": "auto"} (o padrão) ou tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} resultará em erro porque essas opções forçam o uso de ferramentas, o que é incompatível com o pensamento estendido.

2. Preservando blocos de pensamento: 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.

Exemplo: Passando blocos de pensamento com resultados de ferramentas

Aqui está um exemplo prático mostrando como preservar blocos de pensamento ao fornecer resultados de ferramentas:

Python

weather_tool = {
    "name": "get_weather",
    "description": "Obter clima atual para uma localização",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
}

# Primeira solicitação - Claude responde com pensamento e solicitação de ferramenta
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Qual é o clima em Paris?"}
    ]
)

A resposta da API incluirá blocos de pensamento, texto e tool_use:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "O usuário quer saber o clima atual em Paris. Tenho acesso a uma função `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "Posso ajudá-lo a obter as informações atuais do clima para Paris. Deixe-me verificar isso para você"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

Agora vamos continuar a conversa e usar a ferramenta

Python

# Extrair bloco de pensamento e bloco de uso de ferramenta
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Chamar sua API de clima real, aqui é onde sua chamada de API real iria
# vamos fingir que isso é o que recebemos de volta
weather_data = {"temperature": 88}

# Segunda solicitação - Incluir bloco de pensamento e resultado da ferramenta
# Nenhum novo bloco de pensamento será gerado na resposta
continuation = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Qual é o clima em Paris?"},
        # observe que o thinking_block é passado junto com o tool_use_block
        # se isso não for passado, um erro é levantado
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Temperatura atual: {weather_data['temperature']}°F"
        }]}
    ]
)

A resposta da API agora incluirá apenas texto

{
    "content": [
        {
            "type": "text",
            "text": "Atualmente em Paris, a temperatura é 88°F (31°C)"
        }
    ]
}

Preservando blocos de pensamento

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

Embora você possa omitir blocos thinking de turnos assistant anteriores, sugerimos sempre passar de volta todos os blocos de pensamento para a API para qualquer conversa multi-turno. A API irá:

• Filtrar automaticamente os blocos de pensamento fornecidos
• Usar os blocos de pensamento relevantes necessários para preservar o raciocínio do modelo
• Cobrar apenas pelos tokens de entrada para os blocos mostrados ao Claude

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

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

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

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

Pensamento intercalado

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

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

Para habilitar o pensamento intercalado, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua solicitação de API.

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

• Com pensamento intercalado, o budget_tokens pode exceder o parâmetro max_tokens, pois representa o orçamento total através de todos os blocos de pensamento dentro de um turno do assistente.
• O pensamento intercalado é suportado apenas para ferramentas usadas via API Messages.
• O pensamento intercalado é suportado apenas para modelos Claude 4, com o cabeçalho beta interleaved-thinking-2025-05-14.
• Chamadas diretas para a API da Anthropic permitem que você passe interleaved-thinking-2025-05-14 em solicitações 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 do Claude Opus 4.1, Opus 4, ou Sonnet 4, sua solicitação falhará.

Uso de ferramentas sem pensamento intercalado

Python

import anthropic

client = anthropic.Anthropic()

# Definir ferramentas
calculator_tool = {
    "name": "calculator",
    "description": "Realizar cálculos matemáticos",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Expressão matemática para avaliar"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Consultar banco de dados de produtos",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Consulta SQL para executar"
            }
        },
        "required": ["query"]
    }
}

# Primeira solicitação - Claude pensa uma vez antes de todas as chamadas de ferramentas
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "Qual é a receita total se vendêssemos 150 unidades do produto A a $50 cada, e como isso se compara à nossa receita mensal média do banco de dados?"
    }]
)

# A resposta inclui pensamento seguido por usos de ferramentas
# Nota: Claude pensa uma vez no início, depois toma todas as decisões de ferramentas
print("Primeira resposta:")
for block in response.content:
    if block.type == "thinking":
        print(f"Pensamento (resumido): {block.thinking}")
    elif block.type == "tool_use":
        print(f"Uso de ferramenta: {block.name} com entrada {block.input}")
    elif block.type == "text":
        print(f"Texto: {block.text}")

# Você executaria as ferramentas e retornaria os resultados...
# Após obter ambos os resultados das ferramentas de volta, Claude responde diretamente sem pensamento adicional

Neste exemplo sem pensamento intercalado:

1. Claude pensa uma vez no início para entender a tarefa
2. Toma todas as decisões de uso de ferramentas antecipadamente
3. Quando os resultados das ferramentas são retornados, Claude imediatamente fornece uma resposta sem pensamento adicional

Uso de ferramentas com pensamento intercalado

Python

import anthropic

client = anthropic.Anthropic()

# Mesmas definições de ferramentas de antes
calculator_tool = {
    "name": "calculator",
    "description": "Realizar cálculos matemáticos",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Expressão matemática para avaliar"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Consultar banco de dados de produtos",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Consulta SQL para executar"
            }
        },
        "required": ["query"]
    }
}

# Primeira solicitação com pensamento intercalado hab
response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{
        "role": "user",
        "content": "Qual é a receita total se vendêssemos 150 unidades do produto A a $50 cada, e como isso se compara à nossa receita mensal média do banco de dados?"
    }]
)

print("Resposta inicial:")
thinking_blocks = []
tool_use_blocks = []

for block in response.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Pensamento: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Uso de ferramenta: {block.name} com entrada {block.input}")
    elif block.type == "text":
        print(f"Texto: {block.text}")

# Primeiro resultado da ferramenta (calculadora)
calculator_result = "7500"  # 150 * 50

# Continuar com primeiro resultado da ferramenta
response2 = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "Qual é a receita total se vendêssemos 150 unidades do produto A a $50 cada, e como isso se compara à nossa receita mensal média do banco de dados?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        }
    ]
)

print("\nApós resultado da calculadora:")
# Com pensamento intercalado, Claude pode pensar sobre o resultado da calculadora
# antes de decidir consultar o banco de dados
for block in response2.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Pensamento intercalado: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Uso de ferramenta: {block.name} com entrada {block.input}")

# Segundo resultado da ferramenta (banco de dados)
database_result = "5200"  # Exemplo de receita mensal média

# Continuar com segundo resultado da ferramenta
response3 = client.beta.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "Qual é a receita total se vendêssemos 150 unidades do produto A a $50 cada, e como isso se compara à nossa receita mensal média do banco de dados?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        },
        {
            "role": "assistant",
            "content": thinking_blocks[1:] + tool_use_blocks[1:]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[1].id,
                "content": database_result
            }]
        }
    ]
)

print("\nApós resultado do banco de dados:")
# Com pensamento intercalado, Claude pode pensar sobre ambos os resultados
# antes de formular a resposta final
for block in response3.content:
    if block.type == "thinking":
        print(f"Pensamento final: {block.thinking}")
    elif block.type == "text":
        print(f"Resposta final: {block.text}")

Neste exemplo com pensamento intercalado:

1. Claude pensa sobre a tarefa inicialmente
2. Após receber o resultado da calculadora, Claude pode pensar novamente sobre o que esse resultado significa
3. Claude então decide como consultar o banco de dados baseado no primeiro resultado
4. Após receber o resultado do banco de dados, Claude pensa mais uma vez sobre ambos os resultados antes de formular uma resposta final
5. O orçamento de pensamento é distribuído através de todos os blocos de pensamento dentro do turno

Este padrão permite cadeias de raciocínio mais sofisticadas onde a saída de cada ferramenta informa a próxima decisão.

Pensamento estendido com cache de prompt

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

Tarefas de pensamento estendido frequentemente levam mais de 5 minutos para completar. Considere usar a duração de cache de 1 hora para manter acertos de cache através de sessões de pensamento mais longas e fluxos de trabalho multi-etapas.

Remoção de contexto de bloco de pensamento

• Blocos de pensamento 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 pensamento são armazenados em cache e contam como tokens de entrada quando lidos do cache
• Isso cria um trade-off: embora blocos de pensamento não consumam espaço da janela de contexto visualmente, eles ainda contam para seu uso de tokens de entrada quando armazenados em cache
• Se o pensamento se tornar desabilitado, as solicitações falharão se você passar conteúdo de pensamento no turno atual de uso de ferramentas. Em outros contextos, conteúdo de pensamento passado para a API é simplesmente ignorado

Padrões de invalidação de cache

• Mudanças nos parâmetros de pensamento (habilitado/desabilitado ou alocação de orçamento) invalidam pontos de quebra de cache de mensagem
• Pensamento intercalado amplifica a invalidação de cache, pois blocos de pensamento podem ocorrer entre múltiplas chamadas de ferramentas
• Prompts de sistema e ferramentas permanecem em cache apesar de mudanças nos parâmetros de pensamento ou remoção de blocos

Embora blocos de pensamento sejam removidos para cache e cálculos de contexto, eles devem ser preservados ao continuar conversas com uso de ferramentas,especialmente com pensamento intercalado.

Entendendo o comportamento de cache de bloco de pensamento

Ao usar pensamento estendido com uso de ferramentas, blocos de pensamento exibem comportamento específico de cache 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 armazenados em cache contam como tokens de entrada em suas métricas de uso quando lidos do cache
4. Quando um bloco de usuário não-resultado-de-ferramenta é incluído, todos os blocos de pensamento anteriores são ignorados e removidos do contexto

Exemplo de fluxo detalhado:

Solicitação 1:

Usuário: "Qual é o clima em Paris?"

Resposta 1:

[bloco_de_pensamento_1] + [bloco de uso de ferramenta 1]

Solicitação 2:

Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True]

Resposta 2:

[bloco_de_pensamento_2] + [bloco de texto 2]

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

Solicitação 3:

Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True], 
Assistente: [bloco_de_pensamento_2] + [bloco de texto 2], 
Usuário: [Resposta de texto, cache=True]

Como um bloco de usuário 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:

Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True], 
Assistente: [bloco de texto 2], 
Usuário: [Resposta de texto, cache=True]

Pontos-chave:

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

Cache de prompt de sistema (preservado quando o pensamento muda)

Python

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remover elementos script e style
    for script in soup(["script", "style"]):
        script.decompose()

    # Obter texto
    text = soup.get_text()

    # Quebrar em linhas e remover espaço inicial e final em cada
    lines = (line.strip() for line in text.splitlines())
    # Quebrar multi-títulos em uma linha cada
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Descartar linhas em branco
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Buscar o conteúdo do artigo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usar apenas texto suficiente para cache (primeiros capítulos)
LARGE_TEXT = book_content[:5000]

SYSTEM_PROMPT=[
    {
        "type": "text",
        "text": "Você é um assistente de IA que tem a tarefa de análise literária. Analise o seguinte texto cuidadosamente.",
    },
    {
        "type": "text",
        "text": LARGE_TEXT,
        "cache_control": {"type": "ephemeral"}
    }
]

MESSAGES = [
    {
        "role": "user",
        "content": "Analise o tom desta passagem."
    }
]

# Primeira solicitação - estabelecer cache
print("Primeira solicitação - estabelecendo cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Uso da primeira resposta: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analise os personagens nesta passagem."
})
# Segunda solicitação - mesmos parâmetros de pensamento (acerto de cache esperado)
print("\nSegunda solicitação - mesmos parâmetros de pensamento (acerto de cache esperado)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Uso da segunda resposta: {response2.usage}")

# Terceira solicitação - parâmetros de pensamento diferentes (erro de cache para mensagens)
print("\nTerceira solicitação - parâmetros de pensamento diferentes (erro de cache para mensagens)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Orçamento de pensamento alterado
    },
    system=SYSTEM_PROMPT,  # Prompt de sistema permanece em cache
    messages=MESSAGES  # Cache de mensagens é invalidado
)

print(f"Uso da terceira resposta: {response3.usage}")

Cache de mensagens (invalidado quando o pensamento muda)

Python

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remover elementos script e style
    for script in soup(["script", "style"]):
        script.decompose()

    # Obter texto
    text = soup.get_text()

    # Quebrar em linhas e remover espaço inicial e final em cada
    lines = (line.strip() for line in text.splitlines())
    # Quebrar multi-títulos em uma linha cada
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Descartar linhas em branco
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Buscar o conteúdo do artigo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usar apenas texto suficiente para cache (primeiros capítulos)
LARGE_TEXT = book_content[:5000]

# Nenhum prompt de sistema - cache em mensagens em vez disso
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {
                "type": "text",
                "text": "Analise o tom desta passagem."
            }
        ]
    }
]

# Primeira solicitação - estabelecer cache
print("Primeira solicitação - estabelecendo cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    messages=MESSAGES
)

print(f"Uso da primeira resposta: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analise os personagens nesta passagem."
})
# Segunda solicitação - mesmos parâmetros de pensamento (acerto de cache esperado)
print("\nSegunda solicitação - mesmos parâmetros de pensamento (acerto de cache esperado)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000  # Mesmo orçamento de pensamento
    },
    messages=MESSAGES
)

print(f"Uso da segunda resposta: {response2.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response2.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analise o cenário nesta passagem."
})

# Terceira solicitação - orçamento de pensamento diferente (erro de cache esperado)
print("\nTerceira solicitação - orçamento de pensamento diferente (erro de cache esperado)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Orçamento de pensamento diferente quebra o cache
    },
    messages=MESSAGES
)

print(f"Uso da terceira resposta: {response3.usage}")

Aqui está a saída do script (você pode ver números ligeiramente diferentes)

Primeira solicitação - estabelecendo cache
Uso da primeira resposta: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Segunda solicitação - mesmos parâmetros de pensamento (acerto de cache esperado)

Uso da segunda resposta: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Terceira solicitação - orçamento de pensamento diferente (erro de cache esperado)
Uso da terceira resposta: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

Este exemplo demonstra que quando o cache é configurado no array de mensagens, alterar os parâmetros de pensamento (budget_tokens aumentado de 4000 para 8000) invalida o cache. A terceira solicitação mostra nenhum acerto de cache com cache_creation_input_tokens=1370 e cache_read_input_tokens=0, provando que o cache baseado em mensagens é invalidado quando os parâmetros de pensamento mudam.

Tokens máximos 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 valor grande 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 estrito. O sistema agora retornará um erro de validação se tokens de prompt + max_tokens exceder o tamanho da janela de contexto.

Você pode ler nosso guia sobre janelas de contexto para um mergulho mais profundo.

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:

janela de contexto =
  (tokens de entrada atuais - tokens de pensamento anteriores) +
  (tokens de pensamento + tokens de pensamento criptografados + tokens de saída de texto)

Recomendamos usar a API de contagem de tokens para obter contagens precisas de tokens 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:

janela de contexto =
  (tokens de entrada atuais + tokens de pensamento anteriores + tokens de uso de ferramentas) +
  (tokens de pensamento + tokens de pensamento criptografados + tokens de saída de texto)

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 os modelos Claude 3.7 e 4 de pensamento estendido, você pode precisar:

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

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

Criptografia de pensamento

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

É estritamente necessário enviar de volta blocos de pensamento apenas ao usar ferramentas com pensamento estendido. Caso contrário, você pode omitir blocos de pensamento de turnos anteriores, ou deixar a API removê-los para você se os passar de volta.

Se enviando de volta blocos de pensamento, recomendamos passar tudo de volta como você recebeu para consistência e para evitar problemas potenciais.

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

• Ao transmitir respostas, a assinatura é adicionada via signature_delta dentro de um evento content_block_delta logo antes do evento content_block_stop.
• Valores de signature são significativamente mais longos nos modelos Claude 4 do que em modelos anteriores.
• O campo signature é um campo opaco e não deve ser interpretado ou analisado - existe apenas para fins de verificação.
• Valores de signature são compatíveis entre plataformas (APIs Anthropic, Amazon Bedrock, e Vertex AI). Valores gerados em uma plataforma serão compatíveis com outra.

Redação de pensamento

Ocasionalmente, o raciocínio interno do Claude será sinalizado por nossos sistemas de segurança. Quando isso ocorre, criptografamos parte ou todo o bloco thinking e o retornamos para você como um bloco redacted_thinking. Blocos redacted_thinking são descriptografados quando passados de volta para a API, permitindo que Claude continue sua resposta sem perder contexto.

Ao construir aplicações voltadas para o cliente que usam pensamento estendido:

• Esteja ciente de que blocos de pensamento redigidos contêm conteúdo criptografado que não é legível por humanos
• Considere fornecer uma explicação simples como: “Parte do raciocínio interno do Claude foi automaticamente criptografada por razões de segurança. Isso não afeta a qualidade das respostas.”
• Se mostrando blocos de pensamento aos usuários, você pode filtrar blocos redigidos enquanto preserva blocos de pensamento normais
• Seja transparente que usar recursos de pensamento estendido pode ocasionalmente resultar em algum raciocínio sendo criptografado
• Implemente tratamento de erro apropriado para gerenciar graciosamente pensamento redigido sem quebrar sua UI

Aqui está um exemplo mostrando blocos de pensamento normais e redigidos:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Deixe-me analisar isso passo a passo...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Com base na minha análise..."
    }
  ]
}

Ver blocos de pensamento redigidos em sua saída é comportamento esperado. O modelo ainda pode usar esse raciocínio redigido para informar suas respostas enquanto mantém proteções de segurança.

Se você precisar testar o tratamento de pensamento redigido em sua aplicação, pode usar esta string de teste especial como seu prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

Ao passar blocos thinking e redacted_thinking de volta para a API em uma conversa multi-turno, você deve incluir o bloco completo não modificado de volta para a API para o último turno do assistente. Isso é crítico para manter o fluxo de raciocínio do modelo. Sugerimos sempre passar de volta todos os blocos de pensamento para a API. Para mais detalhes, consulte a seção Preservando blocos de pensamento acima.

Exemplo: Trabalhando com blocos de pensamento redigidos

Este exemplo demonstra como lidar com blocos redacted_thinking que podem aparecer em respostas quando o raciocínio interno do Claude contém conteúdo sinalizado por sistemas de segurança:

Python

import anthropic

client = anthropic.Anthropic()

# Usando um prompt especial que aciona pensamento redigido (apenas para fins de demonstração)
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identificar blocos de pensamento redigidos
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("Resposta contém blocos de pensamento redigidos")
    # Esses blocos ainda são utilizáveis em solicitações subsequentes

    # Extrair todos os blocos (tanto redigidos quanto não-redigidos)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # Ao passar para solicitações subsequentes, incluir todos os blocos sem modificação
    # Isso preserva a integridade do raciocínio do Claude

    print(f"Encontrados {len(all_thinking_blocks)} blocos de pensamento no total")
    print(f"Esses blocos ainda são faturáveis como tokens de saída")

Diferenças no pensamento entre versões de modelos

A API Messages 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:

Recurso	Claude Sonnet 3.7	Modelos Claude 4
Saída de Pensamento	Retorna saída de pensamento completa	Retorna pensamento resumido
Pensamento Intercalado	Não suportado	Suportado com cabeçalho beta interleaved-thinking-2025-05-14

Preços

O pensamento estendido usa o esquema de preços de tokens padrão:

Modelo	Tokens de Entrada Base	Escritas de Cache	Acertos de Cache	Tokens de Saída
Claude Opus 4.1	$15 / MTok	$18,75 / MTok	$1,50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18,75 / MTok	$1,50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3,75 / MTok	$0,30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3,75 / MTok	$0,30 / MTok	$15 / MTok

O processo de pensamento incorre em cobranças por:

• Tokens usados durante o pensamento (tokens de saída)
• Blocos de pensamento do último turno do assistente incluídos em solicitações subsequentes (tokens de entrada)
• Tokens de saída de texto padrão

Quando o pensamento estendido está habilitado, um prompt de sistema especializado é automaticamente incluído para suportar este recurso.

Ao usar pensamento resumido:

• Tokens de entrada: Tokens em sua solicitação original (exclui tokens de pensamento de turnos anteriores)
• Tokens de saída (faturados): Os tokens de pensamento originais que 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

A contagem de tokens de saída faturada não corresponderá à contagem de tokens visível na resposta. Você é cobrado pelo processo de pensamento completo, não pelo resumo que você vê.

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

Trabalhando com orçamentos de pensamento

• Otimização de orçamento: O orçamento mínimo é 1.024 tokens. Sugerimos começar no mínimo e aumentar o orçamento de pensamento incrementalmente para encontrar a faixa 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 com o trade-off de maior latência. Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio ideal. Note que o orçamento de pensamento é um alvo em vez de um limite estrito—o uso real de tokens pode variar baseado na tarefa.
• Pontos de partida: Comece com orçamentos de pensamento maiores (16k+ tokens) para tarefas complexas e ajuste baseado em suas necessidades.
• Orçamentos grandes: Para orçamentos de pensamento acima de 32k, recomendamos usar processamento em lote para evitar problemas de rede. Solicitações empurrando o modelo para pensar acima de 32k tokens causam solicitações de longa duração que podem esbarrar em timeouts 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 transmissão: A transmissão é necessária quando max_tokens é maior que 21.333. Ao transmitir, esteja preparado para lidar com blocos de conteúdo de pensamento e texto conforme chegam.

Compatibilidade de recursos

• O 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é-preencher respostas quando o pensamento está habilitado.
• Mudanças 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 a funcionar quando os parâmetros de pensamento mudarem.

Diretrizes de uso

• Seleção de tarefas: Use pensamento estendido para tarefas particularmente complexas que se beneficiam de raciocínio passo a passo como matemática, codificação e análise.
• Tratamento de contexto: Você não precisa remover blocos de pensamento anteriores você mesmo. A API Anthropic ignora automaticamente 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 prompting de pensamento estendido se quiser maximizar as capacidades de pensamento do Claude.

Próximos passos

Experimente o cookbook de pensamento estendido

Explore exemplos práticos de pensamento em nosso cookbook.

Dicas de prompting de pensamento estendido

Aprenda melhores práticas de engenharia de prompt para pensamento estendido.