---
title: Introdução ao uso da API para o Claude
url: https://platform.claude.com/docs/pt-BR/claude_api_primer
description: 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.
---

# 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

```text wrap
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.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Chamando a API

### Requisição e resposta básicas

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{"role": "user", "content": "Hello, Claude"}'
  ```

  ```python Python
  import anthropic

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

```json Output
{
  "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.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create <<'YAML'
  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?
  YAML
  ```

  ```python Python
  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)
  ```
</CodeGroup>

### 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.

<Note>
  Os modelos Claude 4.6 e posteriores e o Claude Mythos Preview não suportam o preenchimento prévio de mensagens do assistente; as requisições para esses modelos devem terminar com uma mensagem do usuário. Os exemplos abaixo usam um modelo que suporta preenchimento prévio.
</Note>

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create <<'YAML'
  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 ("
  YAML
  ```

  ```python Python
  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)
  ```
</CodeGroup>

### 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`.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"

  # Opção 1: imagem codificada em Base64 (o prefixo @ codifica arquivos binários em base64 automaticamente)
  curl -sSo vision-example.jpg "$IMAGE_URL"

  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content:
        - type: image
          source:
            type: base64
            media_type: image/jpeg
            data: "@./vision-example.jpg"
        - type: text
          text: What is in the above image?
  YAML

  # Opção 2: imagem referenciada por URL
  ant messages create <<YAML
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content:
        - type: image
          source:
            type: url
            url: $IMAGE_URL
        - type: text
          text: What is in the above image?
  YAML
  ```

  ```python Python
  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"))
  ```
</CodeGroup>

## Pensamento

O pensamento às vezes pode ajudar o Claude em tarefas muito difíceis. O mecanismo atual é o [adaptive thinking](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) (pensamento adaptativo) (`thinking: {"type": "adaptive"}`): o Claude determina quando e quanto pensar, e você direciona a profundidade do pensamento com o parâmetro [`effort`](https://platform.claude.com/docs/pt-BR/build-with-claude/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 posteriores e no Claude Mythos Preview, o pensamento fica 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 Sonnet 5.5 (`claude-sonnet-5-5`, apenas pensamento adaptativo, ativado por padrão; `thinking: {"type": "disabled"}` retorna um erro 400, então envie `thinking: {"type": "between_tools"}` para desativar o pensamento antecipado)
* Claude Haiku 5.5 (`claude-haiku-5-5`, apenas pensamento adaptativo, ativado por padrão)
* Claude Fable 5.1 (`claude-fable-5-1`, apenas pensamento adaptativo, sempre ativado)
* Claude Mythos 5.1 (`claude-mythos-5-1`, apenas pensamento adaptativo, sempre ativado)
* Claude Fable 5 (`claude-fable-5`, apenas pensamento adaptativo, sempre ativado)
* Claude Mythos 5 (`claude-mythos-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 manual legado)
* Claude Sonnet 4.6 (`claude-sonnet-4-6`, pensamento adaptativo ou manual legado)
* Claude Opus 4.5 (`claude-opus-4-5-20251101`, apenas pensamento manual legado)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`, [descontinuado](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations), apenas pensamento manual legado)
* Claude Haiku 4.5 (`claude-haiku-4-5-20251001`, apenas pensamento manual legado)

<Note>
  Nos modelos Claude 4.7 e posteriores, o "extended thinking" (pensamento estendido) manual (`type: enabled` com um valor de `budget_tokens`) não é suportado e retorna um erro 400. Use o [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) (`type: adaptive`) em vez disso.
</Note>

### 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`.

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create --transform content --format yaml <<'YAML'
  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?
  YAML
  ```

  ```python Python
  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}")
  ```
</CodeGroup>

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](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) 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](https://platform.claude.com/docs/pt-BR/claude_api_primer#interleaved-thinking), `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:** Com o pensamento estendido manual (`thinking: {"type": "enabled"}`), apenas `tool_choice: {"type": "auto"}` (padrão) ou `tool_choice: {"type": "none"}` é suportado. O pensamento adaptativo aceita o uso forçado de ferramentas, exceto nos modelos listados em [Forçando o uso de ferramentas](https://platform.claude.com/docs/pt-BR/claude_api_primer#forcing-tool-use). Onde é aceita, uma chamada de ferramenta forçada pula o pensamento: a resposta começa com a chamada de ferramenta e não tem bloco `thinking`.
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

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  # Primeira requisição: capture o array de conteúdo do assistente (blocos thinking + tool_use,
  # com assinaturas intactas) como JSON compacto.
  ASSISTANT_CONTENT=$(ant messages create \
    --transform content --format jsonl <<'YAML'
  model: claude-opus-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
    display: summarized
  tools:
    - 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]
  messages:
    - role: user
      content: "What's the weather in Paris?"
  YAML
  )

  TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT" \
    | jq -r '.[] | select(.type == "tool_use") | .id')

  # Segunda requisição: envie de volta os blocos capturados, sem alterações, como a mensagem
  # do assistente. O bloco thinking deve acompanhar o bloco tool_use.
  ant messages create <<YAML
  model: claude-opus-5-5
  max_tokens: 16000
  thinking:
    type: adaptive
    display: summarized
  tools:
    - 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]
  messages:
    - role: user
      content: "What's the weather in Paris?"
    - role: assistant
      content: $ASSISTANT_CONTENT
    - role: user
      content:
        - type: tool_result
          tool_use_id: $TOOL_USE_ID
          content: "Current temperature: 72°F"
  YAML
  ```

  ```python Python
  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)
  ```
</CodeGroup>

### Pensamento intercalado

O "interleaved thinking" (pensamento intercalado) permite que o Claude pense entre chamadas de ferramentas, raciocinando sobre os resultados das ferramentas antes de determinar o próximo passo.

<Info>
  Em modelos com [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) (`thinking: {type: "adaptive"}`), o pensamento intercalado é ativado automaticamente. 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.
</Info>

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:

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  tools:
    - name: calculator
      description: Perform arithmetic calculations.
      input_schema:
        type: object
        properties:
          expression:
            type: string
            description: The math expression to evaluate.
        required:
          - expression
    - name: database_query
      description: Query the product database.
      input_schema:
        type: object
        properties:
          query:
            type: string
            description: The database query.
        required:
          - query
  messages:
    - role: user
      content: "What's the total revenue if we sold 150 units of product A at $50 each?"
  YAML
  ```

  ```python Python
  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}")
  ```
</CodeGroup>

Com o pensamento intercalado e SOMENTE com o pensamento intercalado (não com o pensamento estendido manual comum), 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:

| Parâmetro      | Descrição                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `name`         | O nome da ferramenta. Deve corresponder à regex `^[a-zA-Z0-9_-]{1,128}$`.                                   |
| `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](https://json-schema.org/) que define os parâmetros esperados para a ferramenta.     |

```json
{
  "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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) para mais detalhes.

Exemplo de uma boa descrição de ferramenta:

```json
{
  "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`:

```python
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 chamar alguma das ferramentas fornecidas ou não (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.

No Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, `any` e `tool` retornam um erro 400. Mantenha `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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use).

### 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.

### 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` igual a `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 sendo usada.
* `input`: Um objeto contendo a entrada sendo passada para a ferramenta.

```json
{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}
```

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

1. Extrair `name`, `id` e `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`:

```json
{
  "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`:

```json
{
  "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

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create --stream --format jsonl \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello"}' \
    | jq -rj 'select(.delta.type? == "text_delta") | .delta.text'
  ```

  ```python Python
  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)
  ```
</CodeGroup>

### 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

```json
{
  "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*:

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

#### Delta de pensamento

Ao usar pensamento com streaming:

```json
{
  "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

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