Introdução ao uso da API para o Claude

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

Modelos

Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2.5x Claude Opus 5.5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5: claude-sonnet-5
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

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "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 anteriores da conversa não precisam necessariamente ter se originado do Claude. Você pode usar mensagens assistant sintéticas.

import anthropic

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

Preenchendo previamente a resposta do Claude

Você pode preencher previamente parte da resposta do Claude na última posição da lista de mensagens de entrada. Use essa técnica para moldar a resposta do Claude. O exemplo a seguir usa "max_tokens": 1 para obter uma única resposta de múltipla escolha do Claude.

import anthropic

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 origem 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 httpx2

# Opção 1: imagem codificada em Base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    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(next(block.text for block in message.content if block.type == "text"))

# Opção 2: imagem referenciada por URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))

Pensamento

O pensamento às vezes pode ajudar o Claude em tarefas muito difíceis. O mecanismo atual é o adaptive thinking (pensamento adaptativo) (thinking: {"type": "adaptive"}): o Claude decide quando e quanto pensar, e você direciona a profundidade do pensamento com o parâmetro effort em vez de um orçamento de tokens. O pensamento adaptativo é suportado nos modelos Claude 4.6 e posteriores e no Claude Mythos Preview. Nos modelos Claude 5 e no Claude Mythos Preview, o pensamento está ativado por padrão quando o parâmetro thinking é omitido.

A temperatura deve ser definida como 1 (ou deixada sem definição) sempre que o pensamento estiver ativado, em todos os modelos. Nos modelos Claude 4.7 e posteriores e no Claude Mythos Preview, temperature está descontinuado e apenas seu valor padrão é aceito, mesmo quando o pensamento está desativado.

O pensamento é suportado nos seguintes modelos:

• Claude Opus 5.5 (claude-opus-5-5, apenas pensamento adaptativo, sempre ativado)
• Claude Opus 5 (claude-opus-5, apenas pensamento adaptativo, ativado por padrão)
• Claude Sonnet 5 (claude-sonnet-5, apenas pensamento adaptativo, ativado por padrão)
• Claude Opus 4.8 (claude-opus-4-8, apenas pensamento adaptativo)
• Claude Opus 4.7 (claude-opus-4-7, apenas pensamento adaptativo)
• Claude Opus 4.6 (claude-opus-4-6, pensamento adaptativo ou pensamento manual legado)
• Claude Sonnet 4.6 (claude-sonnet-4-6, pensamento adaptativo ou pensamento manual legado)
• Claude Opus 4.5 (claude-opus-4-5-20251101, apenas pensamento manual legado)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, apenas pensamento manual legado)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, apenas pensamento manual legado)

Como o pensamento funciona

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 contém blocos de pensamento resumidos e blocos de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

O pensamento estendido manual (thinking: {"type": "enabled", "budget_tokens": N}) é o mecanismo legado. Ele funciona apenas nos modelos Claude 4 a 4.6 que suportam pensamento; os modelos Claude 4.7 e posteriores rejeitam type: enabled com um erro 400 e usam o pensamento adaptativo em vez disso. Com o pensamento estendido manual, budget_tokens define o número máximo de tokens que o Claude pode usar em seu processo de raciocínio interno; o limite se aplica aos tokens de pensamento completos, não à saída resumida. A menos que você esteja usando o 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 com uso de ferramentas

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

Limitações importantes:

1. Limitação de escolha de ferramenta: Suporta apenas tool_choice: {"type": "auto"} (padrão) ou tool_choice: {"type": "none"}.
2. 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-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Extrair 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 - Incluir o bloco de pensamento e o resultado da ferramenta
continuation = client.messages.create(
    model="claude-opus-5-5",
    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 "interleaved thinking" (pensamento intercalado) permite que o Claude pense entre chamadas de ferramentas, raciocinando sobre os resultados das ferramentas antes de decidir o próximo passo.

Em modelos mais antigos que usam pensamento estendido manual (modelos Claude 4, 4.5 e Sonnet 4.6), ative o pensamento intercalado adicionando 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:
    match block.type:
        case "thinking":
            print(f"Thinking: {block.thinking}")
        case "tool_use":
            print(f"Tool call: {block.name}({block.input})")
        case "text":
            print(f"Response: {block.text}")

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

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:

{
  "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 das ferramentas. Suas descrições devem explicar cada detalhe 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 ele 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 determine 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.

Nos modelos Claude Opus 5.5, Claude Fable 5.1, e Claude Mythos 5.1, any e tool retornam um erro 400. Deixe tool_choice em auto e defina "strict": true na definição da ferramenta para garantir que qualquer chamada feita pelo Claude corresponda ao input_schema da ferramenta. Consulte Uso estrito de ferramentas.

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 mostra sua "chain of thought" (cadeia de pensamento), ou seja, o raciocínio passo a passo que ele usa para decompor o problema e determinar 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 desativar esse comportamento definindo disable_parallel_tool_use=true.

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

Lidando com resultados de ferramentas do cliente

A resposta tem 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 de uso de ferramenta específico.
• name: O nome da ferramenta que está sendo usada.
• input: Um objeto contendo a entrada que está sendo passada para a ferramenta.

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

1. Extrair o name, o id e o input do bloco tool_use.
2. Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta.
3. 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 motivo de parada max_tokens

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

Lidando com o motivo de parada pause_turn

Ao usar ferramentas de servidor, como a busca na web, a API pode retornar um motivo de parada 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 do Claude de usar uma ferramenta 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 a resposta de forma incremental via streaming 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-5-5",
) 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:

1. message_start: contém um objeto Message com content vazio.
2. 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.
3. Um ou mais eventos message_delta, indicando alterações de nível superior no objeto Message final.
4. Um evento message_stop final.

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