MensagensPensamento

Pensamento em fluxos de trabalho com ferramentas e múltiplos turnos

Percorra uma ida e volta completa de uso de ferramentas em dois turnos que preserva os blocos de pensamento corretamente, e veja como o pensamento intercalado muda o fluxo.

Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte API e retenção de dados.

Esta página percorre uma ida e volta completa de uso de ferramentas em dois turnos com o pensamento habilitado: Claude pensa, solicita uma chamada de ferramenta, recebe o resultado e finaliza sua resposta, com os blocos de pensamento tratados corretamente em cada etapa. As regras completas estão na página Pensamento, em Pensamento com uso de ferramentas e Preservando blocos de pensamento; esta página mostra essas regras aplicadas em código executável.

As regras que este passo a passo aplica

Cada link leva à declaração completa na página de Pensamento:

Limite a escolha de ferramenta a auto ou none no modo manual: opções de tool_choice que forçam o uso de ferramentas retornam um erro com o "extended thinking" (pensamento estendido) manual (thinking: {type: "enabled"}); o pensamento adaptativo suporta uso forçado de ferramentas.
Mantenha uma configuração de pensamento por turno do assistente: um loop de uso de ferramentas é um único turno do assistente, então altere a configuração apenas entre turnos.
Passe os blocos de pensamento de volta completos e sem modificações: quando você retorna um resultado de ferramenta, os blocos de pensamento da mensagem do assistente devem voltar junto com ele.
Ecoe a mensagem do assistente exatamente como recebida: reconstruir a mensagem ou filtrar blocos redacted_thinking dispara um erro 400.

Os exemplos usam pensamento adaptativo; em modelos que suportam apenas pensamento estendido, substitua por thinking: {type: "enabled", budget_tokens: N}. As regras de ida e volta são idênticas.

Percorra uma ida e volta de uso de ferramentas em dois turnos

O exemplo define uma ferramenta get_weather, deixa Claude pensar e solicitar uma chamada de ferramenta, e então retorna o resultado da ferramenta junto com o turno do assistente ecoado exatamente como recebido, incluindo o bloco de pensamento.

Faça a primeira requisição com uma ferramenta disponível

Envie uma requisição com o pensamento adaptativo habilitado e a ferramenta definida. Além do parâmetro thinking, esta é uma requisição padrão de uso de ferramentas:


client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "City name"}},
        "required": ["location"],
    },
}

# Primeira solicitação - Claude responde com pensamento e solicitação de ferramenta
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
print(response)

Capture o array de conteúdo para ecoar de volta
Você deve ver blocos thinking, text e tool_use no conteúdo da resposta em uma execução em que Claude escolheu pensar (em requisições mais simples, o modo adaptativo pode pular o bloco de pensamento). Mantenha esse array de conteúdo intacto: a próxima etapa o envia de volta literalmente.
Para ver o texto de pensamento como nesta saída, adicione display: "summarized" à requisição. Em modelos onde a exibição é omitida por padrão, incluindo claude-opus-4-8, o campo thinking caso contrário volta como uma string vazia com apenas o signature preenchido. De qualquer forma, ecoe o array de conteúdo de volta sem alterações; consulte Controlando a exibição do pensamento.
Output
{ "content": [ { "type": "thinking", "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...", "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5T...." }, { "type": "text", "text": "I can help you get the current weather information for Paris. Let me check that for you" }, { "type": "tool_use", "id": "toolu_01CswdEQBMshySk6Y9DFKrfq", "name": "get_weather", "input": { "location": "Paris" } } ] }

Retorne o resultado da ferramenta, ecoando o turno do assistente literalmente

Execute a ferramenta do seu lado e, em seguida, envie uma segunda requisição que acrescenta duas mensagens à conversa. A primeira é o conteúdo do assistente ecoado de volta exatamente como recebido, para que o bloco de pensamento permaneça inalterado ao lado do bloco tool_use. A segunda é uma mensagem de usuário carregando o tool_result.

Cada exemplo é um script autocontido: ele repete a primeira requisição e, em seguida, envia imediatamente a continuação usando a resposta que acabou de receber.


client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "City name"}},
        "required": ["location"],
    },
}
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Extraia o bloco de uso de ferramentas para obter seu ID para o tool_result
tool_use_block = next(block for block in response.content if block.type == "tool_use")

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

# Segunda requisição - Inclua o turno do assistente e o tool_result
continuation = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Ecoe o conteúdo do assistente exatamente como recebido. Quando um bloco
        # de pensamento está presente, ele deve acompanhar o bloco tool_use.
        {"role": "assistant", "content": response.content},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)
print(continuation)

Leia a resposta final
Você deve ver Claude completar o turno com texto. Como o pensamento intercalado é automático no modo adaptativo, a continuação também pode começar com um novo bloco de pensamento antes do texto final:
Output
{ "content": [ { "type": "text", "text": "Currently in Paris, the temperature is 88°F (31°C)" } ] }

Como o pensamento intercalado muda o fluxo

O pensamento intercalado permite que Claude pense entre chamadas de ferramentas, raciocinando sobre cada resultado de ferramenta antes de agir sobre ele. O conceito e a disponibilidade por modelo são abordados em Pensamento intercalado na página de Pensamento; a intercalação muda onde os blocos de pensamento aparecem, não se as chamadas de ferramentas podem ser encadeadas. A comparação a seguir mostra o que o pensamento intercalado muda em um fluxo de trabalho com duas ferramentas:

Próximos passos

Pensamento

A visão geral: ative o pensamento, leia a saída de pensamento e revise as regras completas para uso de ferramentas, cache e streaming.

Direcionando o pensamento

Direcione com que frequência e com que profundidade Claude pensa com níveis de esforço e orientação baseada em prompt.

Pensamento estendido

Orçamentos manuais de pensamento em modelos mais antigos: mecânica de budget_tokens e migração para o adaptativo.

Was this page helpful?

As regras que este passo a passo aplica

Cada link leva à declaração completa na página de Pensamento:

Limite a escolha de ferramenta a auto ou none no modo manual: opções de tool_choice que forçam o uso de ferramentas retornam um erro com o "extended thinking" (pensamento estendido) manual (thinking: {type: "enabled"}); o pensamento adaptativo suporta uso forçado de ferramentas.

Mantenha uma configuração de pensamento por turno do assistente: um loop de uso de ferramentas é um único turno do assistente, então altere a configuração apenas entre turnos.

Passe os blocos de pensamento de volta completos e sem modificações: quando você retorna um resultado de ferramenta, os blocos de pensamento da mensagem do assistente devem voltar junto com ele.

Ecoe a mensagem do assistente exatamente como recebida: reconstruir a mensagem ou filtrar blocos redacted_thinking dispara um erro 400.

Os exemplos usam pensamento adaptativo; em modelos que suportam apenas pensamento estendido, substitua por thinking: {type: "enabled", budget_tokens: N}. As regras de ida e volta são idênticas.

Percorra uma ida e volta de uso de ferramentas em dois turnos

Faça a primeira requisição com uma ferramenta disponível

Envie uma requisição com o pensamento adaptativo habilitado e a ferramenta definida. Além do parâmetro thinking, esta é uma requisição padrão de uso de ferramentas:


client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "City name"}},
        "required": ["location"],
    },
}

# Primeira solicitação - Claude responde com pensamento e solicitação de ferramenta
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
print(response)

Capture o array de conteúdo para ecoar de volta
Você deve ver blocos thinking, text e tool_use no conteúdo da resposta em uma execução em que Claude escolheu pensar (em requisições mais simples, o modo adaptativo pode pular o bloco de pensamento). Mantenha esse array de conteúdo intacto: a próxima etapa o envia de volta literalmente.
Para ver o texto de pensamento como nesta saída, adicione display: "summarized" à requisição. Em modelos onde a exibição é omitida por padrão, incluindo claude-opus-4-8, o campo thinking caso contrário volta como uma string vazia com apenas o signature preenchido. De qualquer forma, ecoe o array de conteúdo de volta sem alterações; consulte Controlando a exibição do pensamento.
Output
{ "content": [ { "type": "thinking", "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...", "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5T...." }, { "type": "text", "text": "I can help you get the current weather information for Paris. Let me check that for you" }, { "type": "tool_use", "id": "toolu_01CswdEQBMshySk6Y9DFKrfq", "name": "get_weather", "input": { "location": "Paris" } } ] }

Retorne o resultado da ferramenta, ecoando o turno do assistente literalmente

Cada exemplo é um script autocontido: ele repete a primeira requisição e, em seguida, envia imediatamente a continuação usando a resposta que acabou de receber.


client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "City name"}},
        "required": ["location"],
    },
}
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Extraia o bloco de uso de ferramentas para obter seu ID para o tool_result
tool_use_block = next(block for block in response.content if block.type == "tool_use")

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

# Segunda requisição - Inclua o turno do assistente e o tool_result
continuation = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Ecoe o conteúdo do assistente exatamente como recebido. Quando um bloco
        # de pensamento está presente, ele deve acompanhar o bloco tool_use.
        {"role": "assistant", "content": response.content},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)
print(continuation)

Leia a resposta final
Você deve ver Claude completar o turno com texto. Como o pensamento intercalado é automático no modo adaptativo, a continuação também pode começar com um novo bloco de pensamento antes do texto final:
Output
{ "content": [ { "type": "text", "text": "Currently in Paris, the temperature is 88°F (31°C)" } ] }

Como o pensamento intercalado muda o fluxo

As regras que este passo a passo aplica

Percorra uma ida e volta de uso de ferramentas em dois turnos

Como o pensamento intercalado muda o fluxo

Uso de ferramentas sem pensamento intercalado

Uso de ferramentas com pensamento intercalado

Próximos passos

As regras que este passo a passo aplica

Percorra uma ida e volta de uso de ferramentas em dois turnos

Como o pensamento intercalado muda o fluxo

Uso de ferramentas sem pensamento intercalado

Uso de ferramentas com pensamento intercalado

Próximos passos

As regras que este passo a passo aplica

Percorra uma ida e volta de uso de ferramentas em dois turnos

Como o pensamento intercalado muda o fluxo

Próximos passos

As regras que este passo a passo aplica

Percorra uma ida e volta de uso de ferramentas em dois turnos

Como o pensamento intercalado muda o fluxo

Próximos passos