Documentation

Introdução ao uso da API para Claude

Este guia foi projetado para fornecer ao Claude os fundamentos do uso da API do Claude. Ele oferece explicações e exemplos de IDs de modelos/a API básica de mensagens, uso de ferramentas, streaming, pensamento estendido, e nada mais.

Introdução ao uso da API para Claude

Este guia foi projetado para fornecer ao Claude os fundamentos do uso da API do Claude. Ele oferece explicações e exemplos de IDs de modelos/a API básica de mensagens, uso de ferramentas, streaming, pensamento estendido, e nada mais.

Modelos

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001

Chamando a API

Requisição e resposta básicas

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Múltiplos turnos de conversa

A Messages API é "stateless" (sem estado), o que significa que você sempre envia o histórico completo da conversa para a API. Você pode usar esse padrão para construir uma conversa ao longo do tempo. Turnos de conversa anteriores não precisam necessariamente ter sido originados pelo Claude. Você pode usar mensagens assistant sintéticas.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Colocando palavras na boca do Claude

Você pode preencher previamente parte da resposta do Claude na última posição da lista de mensagens de entrada. Isso pode ser usado para moldar a resposta do Claude. O exemplo abaixo usa "max_tokens": 1 para obter uma única resposta de múltipla escolha do Claude.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)

Visão

O Claude pode ler tanto texto quanto imagens nas requisições. Os tipos de fonte base64 e url são suportados para imagens, juntamente com os tipos de mídia image/jpeg, image/png, image/gif e image/webp.

import anthropic
import base64
import httpx

# Opção 1: Imagem codificada em Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message.content[0].text)

# Opção 2: Imagem referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)

Pensamento estendido

O "extended thinking" (pensamento estendido) pode às vezes ajudar o Claude com tarefas muito difíceis. Em modelos anteriores ao Claude Opus 4.7, a temperatura deve ser definida como 1 quando o pensamento estendido está habilitado.

O pensamento estendido é suportado nos seguintes modelos:

Claude Opus 4.8 (claude-opus-4-8, apenas pensamento adaptativo)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

No Claude Opus 4.8 e Claude Opus 4.7, o pensamento estendido manual (type: enabled com um valor de budget_tokens) não é suportado e retorna um erro 400. Use o pensamento adaptativo (type: adaptive) em vez disso.

Como o pensamento estendido funciona

Quando o pensamento estendido está ativado, o Claude cria blocos de conteúdo thinking onde ele produz seu raciocínio interno. A resposta da API incluirá blocos de conteúdo thinking, seguidos por blocos de conteúdo text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta conterá blocos de pensamento resumidos e blocos de texto
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Ao usar o pensamento estendido manual (type: enabled), o parâmetro budget_tokens determina o número máximo de tokens que o Claude pode usar para seu processo de raciocínio interno. Nos modelos Claude 4 e posteriores, esse limite se aplica aos tokens completos de pensamento, e não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir uma análise mais completa para problemas complexos. A menos que você esteja usando pensamento intercalado, budget_tokens deve ser menor que max_tokens para que o Claude tenha espaço para escrever sua resposta após a conclusão do pensamento.

Pensamento estendido com uso de ferramentas

O pensamento estendido pode ser usado junto com o uso de ferramentas, permitindo que o Claude raciocine sobre a seleção de ferramentas e o processamento de resultados.

Limitações importantes:

Limitação de escolha de ferramenta: Suporta apenas tool_choice: {"type": "auto"} (padrão) ou tool_choice: {"type": "none"}.
Preservação de blocos de pensamento: Durante o uso de ferramentas, você deve passar os blocos thinking de volta para a API na última mensagem do assistente.

Preservando blocos de pensamento

import anthropic

client = anthropic.Anthropic()

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

weather_data = {"temperature": 72}

# Primeira requisiçã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", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrai o bloco de pensamento e o bloco de uso de ferramentas
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
)

# Segunda requisição - Inclui o bloco de pensamento e o resultado da ferramenta
continuation = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Observe que o thinking_block é passado junto com o tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

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

Pensamento intercalado

O pensamento estendido com uso de ferramentas nos modelos Claude 4 suporta "interleaved thinking" (pensamento intercalado), que permite ao Claude pensar entre chamadas de ferramentas. Para habilitar nos modelos Claude 4, 4.5 e Sonnet 4.6, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua requisição de API.

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Com o pensamento intercalado e SOMENTE com o pensamento intercalado (não com o pensamento estendido regular), o budget_tokens pode exceder o parâmetro max_tokens, pois budget_tokens nesse caso representa o orçamento total entre todos os blocos de pensamento dentro de um turno do assistente.

Para Claude Opus 4.8, Claude Opus 4.7 e Claude Opus 4.6, o pensamento intercalado é habilitado automaticamente ao usar o pensamento adaptativo (thinking: {type: "adaptive"}). Nenhum cabeçalho beta é necessário. O Sonnet 4.6 suporta tanto o cabeçalho beta interleaved-thinking-2025-05-14 com pensamento estendido manual quanto o pensamento adaptativo.

Uso de ferramentas

Especificando ferramentas do cliente

As ferramentas do cliente são especificadas no parâmetro de nível superior tools da requisição de API. Cada definição de ferramenta inclui:

Parâmetro	Descrição
`name`	O nome da ferramenta. Deve corresponder à regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Uma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.
`input_schema`	Um objeto JSON Schema definindo os parâmetros esperados para a ferramenta.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Melhores práticas para definições de ferramentas

Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho da ferramenta. Suas descrições devem explicar todos os detalhes sobre a ferramenta, incluindo:

O que a ferramenta faz
Quando ela deve ser usada (e quando não deve)
O que cada parâmetro significa e como afeta o comportamento da ferramenta
Quaisquer ressalvas ou limitações importantes

Considere usar input_examples para ferramentas complexas. Para ferramentas com objetos aninhados, parâmetros opcionais ou entradas sensíveis a formato, você pode fornecer exemplos concretos usando o campo input_examples (beta). Isso ajuda o Claude a entender os padrões de entrada esperados. Consulte Fornecendo exemplos de uso de ferramentas para mais detalhes.

Exemplo de uma boa descrição de ferramenta:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Controlando a saída do Claude

Forçando o uso de ferramentas

Você pode forçar o Claude a usar uma ferramenta específica especificando a ferramenta no campo tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

Ao trabalhar com o parâmetro tool_choice, há quatro opções possíveis:

auto permite que o Claude decida se deve ou não chamar alguma das ferramentas fornecidas (padrão).
any informa ao Claude que ele deve usar uma das ferramentas fornecidas.
tool força o Claude a sempre usar uma ferramenta específica.
none impede o Claude de usar qualquer ferramenta.

Saída JSON

As ferramentas não precisam necessariamente ser funções do cliente. Você pode usar ferramentas sempre que quiser que o modelo retorne uma saída JSON que siga um esquema fornecido.

Cadeia de pensamento

Ao usar ferramentas, o Claude frequentemente mostrará sua "chain of thought" (cadeia de pensamento), ou seja, o raciocínio passo a passo que ele usa para decompor o problema e decidir quais ferramentas usar.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Uso paralelo de ferramentas

Por padrão, o Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar esse comportamento definindo disable_parallel_tool_use=true.

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

A resposta terá um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:

id: Um identificador único para este bloco específico de uso de ferramenta.
name: O nome da ferramenta sendo usada.
input: Um objeto contendo a entrada sendo passada para a ferramenta.

Quando você receber uma resposta de uso de ferramenta, você deve:

Extrair o name, id e input do bloco tool_use.
Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta.
Continuar a conversa enviando uma nova mensagem com um tool_result:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Lidando com o stop reason `max_tokens`

Se a resposta do Claude for cortada devido ao atingimento do limite de max_tokens durante o uso de ferramentas, tente a requisição novamente com um valor maior de max_tokens.

Lidando com o stop reason `pause_turn`

Ao usar ferramentas de servidor como busca na web, a API pode retornar um stop reason pause_turn. Continue a conversa passando a resposta pausada de volta como está em uma requisição subsequente.

Solucionando erros

Erro de execução de ferramenta

Se a própria ferramenta lançar um erro durante a execução, retorne a mensagem de erro com "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Nome de ferramenta inválido

Se a tentativa de uso de uma ferramenta pelo Claude for inválida (por exemplo, parâmetros obrigatórios ausentes), tente a requisição novamente com valores de description mais detalhados em suas definições de ferramentas.

Streaming de mensagens

Ao criar uma Message, você pode definir "stream": true para transmitir incrementalmente a resposta usando "server-sent events" (eventos enviados pelo servidor), ou SSE.

Streaming com SDKs

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Tipos de eventos

Cada evento enviado pelo servidor inclui um tipo de evento nomeado e dados JSON associados. Cada stream usa o seguinte fluxo de eventos:

message_start: contém um objeto Message com content vazio.
Uma série de blocos de conteúdo, cada um com content_block_start, um ou mais eventos content_block_delta e content_block_stop.
Um ou mais eventos message_delta, indicando alterações de nível superior no objeto Message final.
Um evento final message_stop.

Aviso: As contagens de tokens mostradas no campo usage do evento message_delta são cumulativas.

Tipos de delta de bloco de conteúdo

Delta de texto

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}

Delta de JSON de entrada

Para blocos de conteúdo tool_use, os deltas são strings JSON parciais:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Delta de pensamento

Ao usar pensamento estendido com streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}

Exemplo básico de requisição com streaming

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

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

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Was this page helpful?

Documentation

Introdução ao uso da API para Claude

Este guia foi projetado para fornecer ao Claude os fundamentos do uso da API do Claude. Ele oferece explicações e exemplos de IDs de modelos/a API básica de mensagens, uso de ferramentas, streaming, pensamento estendido, e nada mais.

Modelos

Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001

Chamando a API

Requisição e resposta básicas

import anthropic
import os

message = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Múltiplos turnos de conversa

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Colocando palavras na boca do Claude

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)

Visão

import anthropic
import base64
import httpx

# Opção 1: Imagem codificada em Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message.content[0].text)

# Opção 2: Imagem referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url.content[0].text)

Pensamento estendido

O pensamento estendido é suportado nos seguintes modelos:

Claude Opus 4.8 (claude-opus-4-8, apenas pensamento adaptativo)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)

Como o pensamento estendido funciona

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta conterá blocos de pensamento resumidos e blocos de texto
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Pensamento estendido com uso de ferramentas

O pensamento estendido pode ser usado junto com o uso de ferramentas, permitindo que o Claude raciocine sobre a seleção de ferramentas e o processamento de resultados.

Limitações importantes:

Limitação de escolha de ferramenta: Suporta apenas tool_choice: {"type": "auto"} (padrão) ou tool_choice: {"type": "none"}.
Preservação de blocos de pensamento: Durante o uso de ferramentas, você deve passar os blocos thinking de volta para a API na última mensagem do assistente.

Preservando blocos de pensamento

import anthropic

client = anthropic.Anthropic()

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

weather_data = {"temperature": 72}

# Primeira requisiçã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", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrai o bloco de pensamento e o bloco de uso de ferramentas
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
)

# Segunda requisição - Inclui o bloco de pensamento e o resultado da ferramenta
continuation = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Observe que o thinking_block é passado junto com o tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_use_block.id,
                    "content": f"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

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

Pensamento intercalado

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Uso de ferramentas

Especificando ferramentas do cliente

As ferramentas do cliente são especificadas no parâmetro de nível superior tools da requisição de API. Cada definição de ferramenta inclui:

Parâmetro	Descrição
`name`	O nome da ferramenta. Deve corresponder à regex `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Uma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.
`input_schema`	Um objeto JSON Schema definindo os parâmetros esperados para a ferramenta.

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Melhores práticas para definições de ferramentas

O que a ferramenta faz
Quando ela deve ser usada (e quando não deve)
O que cada parâmetro significa e como afeta o comportamento da ferramenta
Quaisquer ressalvas ou limitações importantes

Exemplo de uma boa descrição de ferramenta:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Controlando a saída do Claude

Forçando o uso de ferramentas

Você pode forçar o Claude a usar uma ferramenta específica especificando a ferramenta no campo tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

Ao trabalhar com o parâmetro tool_choice, há quatro opções possíveis:

auto permite que o Claude decida se deve ou não chamar alguma das ferramentas fornecidas (padrão).
any informa ao Claude que ele deve usar uma das ferramentas fornecidas.
tool força o Claude a sempre usar uma ferramenta específica.
none impede o Claude de usar qualquer ferramenta.

Saída JSON

As ferramentas não precisam necessariamente ser funções do cliente. Você pode usar ferramentas sempre que quiser que o modelo retorne uma saída JSON que siga um esquema fornecido.

Cadeia de pensamento

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Uso paralelo de ferramentas

Por padrão, o Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar esse comportamento definindo disable_parallel_tool_use=true.

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

A resposta terá um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:

id: Um identificador único para este bloco específico de uso de ferramenta.
name: O nome da ferramenta sendo usada.
input: Um objeto contendo a entrada sendo passada para a ferramenta.

Quando você receber uma resposta de uso de ferramenta, você deve:

Extrair o name, id e input do bloco tool_use.
Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta.
Continuar a conversa enviando uma nova mensagem com um tool_result:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

Lidando com o stop reason `max_tokens`

Se a resposta do Claude for cortada devido ao atingimento do limite de max_tokens durante o uso de ferramentas, tente a requisição novamente com um valor maior de max_tokens.

Lidando com o stop reason `pause_turn`

Solucionando erros

Erro de execução de ferramenta

Se a própria ferramenta lançar um erro durante a execução, retorne a mensagem de erro com "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Nome de ferramenta inválido

Streaming de mensagens

Ao criar uma Message, você pode definir "stream": true para transmitir incrementalmente a resposta usando "server-sent events" (eventos enviados pelo servidor), ou SSE.

Streaming com SDKs

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-4-8",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Tipos de eventos

Cada evento enviado pelo servidor inclui um tipo de evento nomeado e dados JSON associados. Cada stream usa o seguinte fluxo de eventos:

message_start: contém um objeto Message com content vazio.
Uma série de blocos de conteúdo, cada um com content_block_start, um ou mais eventos content_block_delta e content_block_stop.
Um ou mais eventos message_delta, indicando alterações de nível superior no objeto Message final.
Um evento final message_stop.

Aviso: As contagens de tokens mostradas no campo usage do evento message_delta são cumulativas.

Tipos de delta de bloco de conteúdo

Delta de texto

{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Hello frien" }
}

Delta de JSON de entrada

Para blocos de conteúdo tool_use, os deltas são strings JSON parciais:

{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

Delta de pensamento

Ao usar pensamento estendido com streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}

Exemplo básico de requisição com streaming

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

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

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Was this page helpful?

Introdução ao uso da API para Claude

Modelos

Chamando a API

Requisição e resposta básicas

Múltiplos turnos de conversa

Colocando palavras na boca do Claude

Visão

Pensamento estendido

Como o pensamento estendido funciona

Pensamento estendido com uso de ferramentas

Preservando blocos de pensamento

Pensamento intercalado

Uso de ferramentas

Especificando ferramentas do cliente

Melhores práticas para definições de ferramentas

Controlando a saída do Claude

Forçando o uso de ferramentas

Saída JSON

Cadeia de pensamento

Uso paralelo de ferramentas

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

Lidando com o stop reason max_tokens

Lidando com o stop reason pause_turn

Solucionando erros

Erro de execução de ferramenta

Nome de ferramenta inválido

Streaming de mensagens

Streaming com SDKs

Tipos de eventos

Tipos de delta de bloco de conteúdo

Delta de texto

Delta de JSON de entrada

Delta de pensamento

Exemplo básico de requisição com streaming

Introdução ao uso da API para Claude

Modelos

Chamando a API

Requisição e resposta básicas

Múltiplos turnos de conversa

Colocando palavras na boca do Claude

Visão

Pensamento estendido

Como o pensamento estendido funciona

Pensamento estendido com uso de ferramentas

Preservando blocos de pensamento

Pensamento intercalado

Uso de ferramentas

Especificando ferramentas do cliente

Melhores práticas para definições de ferramentas

Controlando a saída do Claude

Forçando o uso de ferramentas

Saída JSON

Cadeia de pensamento

Uso paralelo de ferramentas

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

Lidando com o stop reason max_tokens

Lidando com o stop reason pause_turn

Solucionando erros

Erro de execução de ferramenta

Nome de ferramenta inválido

Streaming de mensagens

Streaming com SDKs

Tipos de eventos

Tipos de delta de bloco de conteúdo

Delta de texto

Delta de JSON de entrada

Delta de pensamento

Exemplo básico de requisição com streaming

Introdução ao uso da API para Claude

Modelos

Chamando a API

Requisição e resposta básicas

Múltiplos turnos de conversa

Colocando palavras na boca do Claude

Visão

Pensamento estendido

Como o pensamento estendido funciona

Pensamento estendido com uso de ferramentas

Preservando blocos de pensamento

Pensamento intercalado

Uso de ferramentas

Especificando ferramentas do cliente

Melhores práticas para definições de ferramentas

Controlando a saída do Claude

Forçando o uso de ferramentas

Saída JSON

Cadeia de pensamento

Uso paralelo de ferramentas

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

Lidando com o stop reason `max_tokens`

Lidando com o stop reason `pause_turn`

Solucionando erros

Erro de execução de ferramenta

Nome de ferramenta inválido

Streaming de mensagens

Streaming com SDKs

Tipos de eventos

Tipos de delta de bloco de conteúdo

Delta de texto

Delta de JSON de entrada

Delta de pensamento

Exemplo básico de requisição com streaming

Introdução ao uso da API para Claude

Modelos

Chamando a API

Requisição e resposta básicas

Múltiplos turnos de conversa

Colocando palavras na boca do Claude

Visão

Pensamento estendido

Como o pensamento estendido funciona

Pensamento estendido com uso de ferramentas

Preservando blocos de pensamento

Pensamento intercalado

Uso de ferramentas

Especificando ferramentas do cliente

Melhores práticas para definições de ferramentas

Controlando a saída do Claude

Forçando o uso de ferramentas

Saída JSON

Cadeia de pensamento

Uso paralelo de ferramentas

Lidando com blocos de conteúdo de uso de ferramentas e resultados de ferramentas

Lidando com resultados de ferramentas do cliente

Lidando com o stop reason `max_tokens`

Lidando com o stop reason `pause_turn`

Solucionando erros

Erro de execução de ferramenta

Nome de ferramenta inválido

Streaming de mensagens

Streaming com SDKs

Tipos de eventos

Tipos de delta de bloco de conteúdo

Delta de texto

Delta de JSON de entrada

Delta de pensamento

Exemplo básico de requisição com streaming