---
title: Introducción al uso de la API para Claude
url: https://platform.claude.com/docs/es/claude_api_primer
description: Esta guía está diseñada para darle a Claude los fundamentos del uso de la Claude API. Ofrece explicaciones y ejemplos de los IDs de modelos/la API de mensajes básica, uso de herramientas, streaming, pensamiento, y nada más.
---

# Introducción al uso de la API para Claude

> Esta guía está diseñada para darle a Claude los fundamentos del uso de la Claude API. Ofrece explicaciones y ejemplos de los IDs de modelos/la API de mensajes básica, uso de herramientas, streaming, pensamiento, y nada más.

## Modelos

```text wrap
Recommended default for most work, including complex agentic coding: Claude Opus 5: claude-opus-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Llamar a la API

### Solicitud y respuesta básicas

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

  ```python Python
  import anthropic

  message = anthropic.Anthropic().messages.create(
      model="claude-opus-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",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}
```

### Múltiples turnos de conversación

La Messages API no tiene estado (stateless), lo que significa que siempre envías el historial completo de la conversación a la API. Puedes usar este patrón para construir una conversación a lo largo del tiempo. Los turnos de conversación anteriores no necesariamente tienen que originarse realmente de Claude. Puedes usar mensajes `assistant` sintéticos.

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

### Prellenar la respuesta de Claude

Puedes prellenar parte de la respuesta de Claude en la última posición de la lista de mensajes de entrada. Usa esta técnica para dar forma a la respuesta de Claude. El siguiente ejemplo usa `"max_tokens": 1` para obtener una única respuesta de opción múltiple de Claude.

<Note>
  Los modelos Claude 4.6 y posteriores y Claude Mythos Preview no admiten el prellenado de mensajes del asistente; las solicitudes a esos modelos deben terminar con un mensaje del usuario. Los ejemplos a continuación usan un modelo que admite el prellenado.
</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>

### Visión

Claude puede leer tanto texto como imágenes en las solicitudes. Se admiten los tipos de fuente `base64` y `url` para imágenes, junto con los tipos de medios `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"

  # Opción 1: Imagen codificada en base64 (el prefijo @ codifica automáticamente archivos binarios como base64)
  curl -sSo vision-example.jpg "$IMAGE_URL"

  ant messages create <<'YAML'
  model: claude-opus-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

  # Opción 2: Imagen referenciada por URL
  ant messages create <<YAML
  model: claude-opus-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

  # Opción 1: Imagen codificada en 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",
      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"))

  # Opción 2: Imagen referenciada por URL
  message_from_url = anthropic.Anthropic().messages.create(
      model="claude-opus-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>

## Pensamiento

El pensamiento a veces puede ayudar a Claude con tareas muy difíciles. El mecanismo actual es el ["adaptive thinking" (pensamiento adaptativo)](https://platform.claude.com/docs/es/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`): Claude decide cuándo y cuánto pensar, y tú diriges la profundidad del pensamiento con el parámetro [`effort`](https://platform.claude.com/docs/es/build-with-claude/effort) en lugar de un presupuesto de tokens. El pensamiento adaptativo es compatible con los modelos Claude 4.6 y posteriores y Claude Mythos Preview. En los modelos Claude 5 y Claude Mythos Preview, el pensamiento está activado por defecto cuando se omite el parámetro `thinking`.

La temperatura debe establecerse en 1 (o dejarse sin establecer) siempre que el pensamiento esté habilitado, en todos los modelos. En los modelos Claude 4.7 y posteriores y Claude Mythos Preview, `temperature` está obsoleto y solo se acepta su valor por defecto, incluso cuando el pensamiento está desactivado.

El pensamiento es compatible con los siguientes modelos:

* Claude Opus 5 (claude-opus-5, solo pensamiento adaptativo, activado por defecto)
* Claude Sonnet 5 (`claude-sonnet-5`, solo pensamiento adaptativo, activado por defecto)
* Claude Opus 4.8 (claude-opus-4-8, solo pensamiento adaptativo)
* Claude Opus 4.7 (`claude-opus-4-7`, solo pensamiento adaptativo)
* Claude Opus 4.6 (`claude-opus-4-6`, pensamiento adaptativo o pensamiento manual heredado)
* Claude Sonnet 4.6 (`claude-sonnet-4-6`, pensamiento adaptativo o pensamiento manual heredado)
* Claude Opus 4.5 (`claude-opus-4-5-20251101`, solo pensamiento manual heredado)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`, solo pensamiento manual heredado)
* Claude Haiku 4.5 (`claude-haiku-4-5-20251001`, solo pensamiento manual heredado)

<Note>
  En los modelos Claude 4.7 y posteriores, el "extended thinking" (pensamiento extendido) manual (`type: enabled` con un valor de `budget_tokens`) no es compatible y devuelve un error 400. Usa el [pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/thinking) (`type: adaptive`) en su lugar.
</Note>

### Cómo funciona el pensamiento

Cuando el pensamiento está activado, Claude crea bloques de contenido `thinking` donde emite su razonamiento interno. La respuesta de la API incluye bloques de contenido `thinking`, seguidos de bloques de contenido `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
  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",
      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?",
          }
      ],
  )

  # La respuesta contiene bloques de pensamiento resumidos y bloques 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}")
  ```
</CodeGroup>

El pensamiento extendido manual (`thinking: {"type": "enabled", "budget_tokens": N}`) es el mecanismo heredado. Funciona solo en los modelos Claude 4 a 4.6 que admiten pensamiento; los modelos Claude 4.7 y posteriores rechazan `type: enabled` con un error 400 y usan el [pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/thinking) en su lugar. Con el pensamiento extendido manual, `budget_tokens` establece el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno; el límite se aplica a los tokens de pensamiento completos, no a la salida resumida. A menos que estés usando [pensamiento intercalado](https://platform.claude.com/docs/es/claude_api_primer#interleaved-thinking), `budget_tokens` debe ser menor que `max_tokens` para que Claude tenga espacio para escribir su respuesta una vez completado el pensamiento.

## Pensamiento con uso de herramientas

El pensamiento puede usarse junto con el "tool use" (uso de herramientas), lo que permite a Claude razonar sobre la selección de herramientas y el procesamiento de resultados.

Limitaciones importantes:

1. **Limitación de elección de herramienta:** Solo admite `tool_choice: {"type": "auto"}` (por defecto) o `tool_choice: {"type": "none"}`.
2. **Preservar los bloques de pensamiento:** Durante el uso de herramientas, debes pasar los bloques `thinking` de vuelta a la API para el último mensaje del asistente.

### Preservar los bloques de pensamiento

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  # Primera solicitud: captura el array de contenido del asistente (bloques thinking + tool_use,
  # firmas intactas) como JSON compacto.
  ASSISTANT_CONTENT=$(ant messages create \
    --transform content --format jsonl <<'YAML'
  model: claude-opus-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 solicitud: devuelve los bloques capturados sin cambios como el mensaje
  # del asistente. El bloque thinking debe acompañar al bloque tool_use.
  ant messages create <<YAML
  model: claude-opus-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}

  # Primera solicitud: Claude responde con pensamiento y solicitud de herramienta
  response = client.messages.create(
      model="claude-opus-5",
      max_tokens=16000,
      thinking={"type": "adaptive", "display": "summarized"},
      tools=[weather_tool],
      messages=[{"role": "user", "content": "What's the weather in Paris?"}],
  )

  # Extrae el bloque de pensamiento y el bloque de uso de herramientas
  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 solicitud: incluye el bloque de pensamiento y el resultado de la herramienta
  continuation = client.messages.create(
      model="claude-opus-5",
      max_tokens=16000,
      thinking={"type": "adaptive", "display": "summarized"},
      tools=[weather_tool],
      messages=[
          {"role": "user", "content": "What's the weather in Paris?"},
          # Observa que se pasa el thinking_block además del 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>

### Pensamiento intercalado

El "interleaved thinking" (pensamiento intercalado) permite a Claude pensar entre llamadas a herramientas, razonando sobre los resultados de las herramientas antes de decidir el siguiente paso.

<Info>
  En los modelos con [pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/thinking) (`thinking: {type: "adaptive"}`), el pensamiento intercalado se habilita automáticamente. No se necesita ningún encabezado beta. Sonnet 4.6 admite tanto el encabezado beta `interleaved-thinking-2025-05-14` con pensamiento extendido manual como el pensamiento adaptativo.
</Info>

En los modelos más antiguos que usan pensamiento extendido manual (modelos Claude 4, 4.5 y Sonnet 4.6), habilita el pensamiento intercalado agregando el encabezado beta `interleaved-thinking-2025-05-14` a tu solicitud 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:
      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}")
  ```
</CodeGroup>

Con el pensamiento intercalado y SOLO con el pensamiento intercalado (no con el pensamiento extendido manual normal), `budget_tokens` puede exceder el parámetro `max_tokens`, ya que `budget_tokens` en este caso representa el presupuesto total entre todos los bloques de pensamiento dentro de un turno del asistente.

## Uso de herramientas

### Especificar herramientas de cliente

Las herramientas de cliente se especifican en el parámetro de nivel superior `tools` de la solicitud de API. Cada definición de herramienta incluye:

| Parámetro      | Descripción                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `name`         | El nombre de la herramienta. Debe coincidir con la expresión regular `^[a-zA-Z0-9_-]{1,64}$`.                  |
| `description`  | Una descripción detallada en texto plano de lo que hace la herramienta, cuándo debe usarse y cómo se comporta. |
| `input_schema` | Un objeto [JSON Schema](https://json-schema.org/) que define los parámetros esperados para la herramienta.     |

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

### Mejores prácticas para las definiciones de herramientas

**Proporciona descripciones extremadamente detalladas.** Este es, por mucho, el factor más importante en el rendimiento de las herramientas. Tus descripciones deben explicar cada detalle sobre la herramienta, incluyendo:

* Qué hace la herramienta
* Cuándo debe usarse (y cuándo no)
* Qué significa cada parámetro y cómo afecta el comportamiento de la herramienta
* Cualquier advertencia o limitación importante

**Considera usar `input_examples` para herramientas complejas.** Para herramientas con objetos anidados, parámetros opcionales o entradas sensibles al formato, puedes proporcionar ejemplos concretos usando el campo `input_examples` (beta). Esto ayuda a Claude a entender los patrones de entrada esperados. Consulta [Proporcionar ejemplos de uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) para más detalles.

Ejemplo de una buena descripción de herramienta:

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

## Controlar la salida de Claude

### Forzar el uso de herramientas

Puedes forzar a Claude a usar una herramienta específica indicando la herramienta en el campo `tool_choice`:

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

Al trabajar con el parámetro `tool_choice`, hay cuatro opciones posibles:

* `auto` permite a Claude determinar si llamar o no a alguna de las herramientas proporcionadas (por defecto).
* `any` le indica a Claude que debe usar una de las herramientas proporcionadas.
* `tool` fuerza a Claude a usar siempre una herramienta en particular.
* `none` impide que Claude use cualquier herramienta.

En Claude Fable 5.1 y Claude Mythos 5.1, `any` y `tool` devuelven un error 400. Deja `tool_choice` en `auto` y establece `"strict": true` en la definición de la herramienta para garantizar que cualquier llamada que haga Claude coincida con el `input_schema` de la herramienta. Consulta [Uso estricto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use).

### Salida JSON

Las herramientas no necesariamente tienen que ser funciones de cliente. Puedes usar herramientas siempre que quieras que el modelo devuelva una salida JSON que siga un esquema proporcionado.

### Cadena de pensamiento

Al usar herramientas, Claude a menudo muestra su "chain of thought" (cadena de pensamiento), es decir, el razonamiento paso a paso que usa para descomponer el problema y determinar qué herramientas usar.

```json
{
  "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 de herramientas en paralelo

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes deshabilitar este comportamiento estableciendo `disable_parallel_tool_use=true`.

## Manejar bloques de contenido de uso de herramientas y resultados de herramientas

### Manejar resultados de herramientas de cliente

La respuesta tiene un `stop_reason` de `tool_use` y uno o más bloques de contenido `tool_use` que incluyen:

* `id`: Un identificador único para este bloque de uso de herramienta en particular.
* `name`: El nombre de la herramienta que se está usando.
* `input`: Un objeto que contiene la entrada que se pasa a la herramienta.

Cuando recibas una respuesta de uso de herramientas, debes:

1. Extraer el `name`, `id` e `input` del bloque `tool_use`.
2. Ejecutar la herramienta real en tu base de código correspondiente a ese nombre de herramienta.
3. Continuar la conversación enviando un nuevo mensaje con un `tool_result`:

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

### Manejar el motivo de detención `max_tokens`

Si la respuesta de Claude se corta porque alcanza el límite de `max_tokens` durante el uso de herramientas, reintenta la solicitud con un valor de `max_tokens` más alto.

### Manejar el motivo de detención `pause_turn`

Al usar herramientas de servidor como la búsqueda web, la API puede devolver un motivo de detención `pause_turn`. Continúa la conversación pasando la respuesta pausada tal cual en una solicitud posterior.

## Solución de errores

### Error de ejecución de herramienta

Si la herramienta misma lanza un error durante la ejecución, devuelve el mensaje de error con `"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
    }
  ]
}
```

### Nombre de herramienta inválido

Si el intento de Claude de usar una herramienta es inválido (por ejemplo, faltan parámetros requeridos), intenta la solicitud de nuevo con valores de `description` más detallados en tus definiciones de herramientas.

## Streaming de mensajes

Al crear un Message, puedes establecer `"stream": true` para transmitir la respuesta de forma incremental mediante "server-sent events" (eventos enviados por el servidor), o SSE.

### Streaming con los SDKs

<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby">
  ```bash CLI
  ant messages create --stream --format jsonl \
    --model claude-opus-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",
  ) as stream:
      for text in stream.text_stream:
          print(text, end="", flush=True)
  ```
</CodeGroup>

### Tipos de eventos

Cada evento enviado por el servidor incluye un tipo de evento con nombre y datos JSON asociados. Cada stream usa el siguiente flujo de eventos:

1. `message_start`: contiene un objeto `Message` con `content` vacío.
2. Una serie de bloques de contenido, cada uno con `content_block_start`, uno o más eventos `content_block_delta` y `content_block_stop`.
3. Uno o más eventos `message_delta`, que indican cambios de nivel superior en el objeto `Message` final.
4. Un evento final `message_stop`.

**Advertencia:** Los conteos de tokens mostrados en el campo `usage` del evento `message_delta` son *acumulativos*.

### Tipos de delta de bloques de contenido

#### Delta de texto

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

#### Delta de JSON de entrada

Para los bloques de contenido `tool_use`, los deltas son *cadenas JSON parciales*:

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

#### Delta de pensamiento

Al usar pensamiento con streaming:

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

### Ejemplo básico de solicitud con streaming

```sse
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-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"}
```