Construir con pensamiento extendido

El pensamiento extendido proporciona a Claude capacidades mejoradas de razonamiento para tareas complejas, mientras proporciona diferentes niveles de transparencia en su proceso de pensamiento paso a paso antes de entregar su respuesta final.

Modelos compatibles

El pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) es compatible con todos los modelos Claude actuales excepto Claude Opus 4.7 y modelos posteriores, donde ya no se acepta y devuelve un error 400. Algunos modelos tienen comportamiento específico del modo:

• Claude Opus 4.7 (claude-opus-4-7) y modelos posteriores: el pensamiento extendido manual ya no es compatible. Usa pensamiento adaptativo (thinking: {type: "adaptive"}) con el parámetro de esfuerzo en su lugar.
• Claude Mythos Preview: pensamiento adaptativo es el predeterminado; thinking: {type: "enabled", budget_tokens: N} también se acepta. thinking: {type: "disabled"} no es compatible, y display tiene como valor predeterminado "omitted" en lugar de devolver contenido de pensamiento. Pasa display: "summarized" para recibir resúmenes.
• Claude Opus 4.6 (claude-opus-4-6): pensamiento adaptativo recomendado; el modo manual (type: "enabled") está deprecado pero sigue siendo funcional.
• Claude Sonnet 4.6 (claude-sonnet-4-6): pensamiento adaptativo recomendado; el modo manual (type: "enabled") con modo intercalado está deprecado pero sigue siendo funcional.

Cómo funciona el pensamiento extendido

Cuando el pensamiento extendido está activado, Claude crea bloques de contenido thinking donde genera su razonamiento interno. Claude incorpora información de este razonamiento antes de elaborar una respuesta final.

La respuesta de la API incluye bloques de contenido thinking, seguidos de bloques de contenido text.

Aquí hay un ejemplo del formato de respuesta predeterminado:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Para más información sobre el formato de respuesta del pensamiento extendido, consulta la Referencia de la API de Mensajes.

Cómo usar el pensamiento extendido

Aquí hay un ejemplo de uso del pensamiento extendido en la API de Mensajes:

Para activar el pensamiento extendido, añade un objeto thinking, con el parámetro type establecido en enabled y budget_tokens en un presupuesto de tokens especificado para el pensamiento extendido. Para Claude Opus 4.6 y Claude Sonnet 4.6, usa type: "adaptive" en su lugar. Consulta Pensamiento adaptativo para más detalles. Aunque type: "enabled" con budget_tokens sigue siendo funcional en estos modelos, está deprecado y se eliminará en una futura versión.

El parámetro budget_tokens determina el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno. En Claude 4 y modelos posteriores, este límite se aplica a los tokens de pensamiento completo, y no a la salida resumida. Los presupuestos más grandes pueden mejorar la calidad de la respuesta al permitir un análisis más exhaustivo para problemas complejos, aunque Claude puede no usar todo el presupuesto asignado, especialmente en rangos superiores a 32k.

budget_tokens debe establecerse en un valor menor que max_tokens. Sin embargo, cuando se usa pensamiento intercalado con herramientas, puedes exceder este límite ya que el límite de tokens se convierte en tu ventana de contexto completa.

Pensamiento resumido

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

Here are some important considerations for summarized thinking:

• You're charged for the full thinking tokens generated by the original request, not the summary tokens.
• The billed output token count will not match the count of tokens you see in the response.
• On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
• As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
• Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Controlando la visualización del pensamiento

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

• "summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
• "omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

• You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
• If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
• display is invalid with thinking.type: "disabled" (there is nothing to display).
• When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

Los pipelines automatizados que nunca muestran contenido de pensamiento a los usuarios finales pueden omitir la sobrecarga de recibir tokens de pensamiento por cable. Las aplicaciones sensibles a la latencia obtienen la misma calidad de razonamiento sin esperar a que el texto de pensamiento se transmita antes de que comience la respuesta final.

Cuando display: "omitted" está establecido, la respuesta contiene bloques thinking con un campo thinking vacío:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Cuando se transmite con display: "omitted", no se emiten eventos thinking_delta; consulta Pensamiento en transmisión a continuación para la secuencia de eventos.

Streaming de pensamiento extendido

Puedes hacer streaming de respuestas de pensamiento extendido usando eventos enviados por el servidor (SSE).

Cuando el streaming está habilitado para pensamiento extendido, recibes contenido de pensamiento a través de eventos thinking_delta.

Cuando se establece display: "omitted", no se emiten eventos thinking_delta. Consulta Controlando la visualización del pensamiento.

Para más documentación sobre streaming a través de la API de Messages, consulta Streaming de Messages.

Aquí te mostramos cómo manejar el streaming con pensamiento:

Ejemplo de salida de streaming:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

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

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

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

Cuando se establece display: "omitted", el bloque de pensamiento se abre, llega un único signature_delta, y el bloque se cierra sin ningún evento thinking_delta. El streaming de texto comienza inmediatamente después:

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

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

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

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

Pensamiento extendido con uso de herramientas

El pensamiento extendido se puede usar junto con uso de herramientas, permitiendo que Claude razone a través de la selección de herramientas y el procesamiento de resultados.

Cuando uses pensamiento extendido con uso de herramientas, ten en cuenta las siguientes limitaciones:

1. Limitación de elección de herramienta: El uso de herramientas con pensamiento solo admite tool_choice: {"type": "auto"} (el predeterminado) o tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} o tool_choice: {"type": "tool", "name": "..."} resultará en un error porque estas opciones fuerzan el uso de herramientas, que es incompatible con el pensamiento extendido.

2. Preservando bloques de pensamiento: Durante el uso de herramientas, debes pasar bloques de thinking de vuelta a la API para el último mensaje del asistente. Incluye el bloque completo sin modificar de vuelta a la API para mantener la continuidad del razonamiento.

Alternar modos de pensamiento en conversaciones

No puedes alternar el pensamiento en medio de un turno del asistente, incluyendo durante bucles de uso de herramientas. El turno completo del asistente debe operar en un único modo de pensamiento:

• Si el pensamiento está habilitado, el turno final del asistente debe comenzar con un bloque de pensamiento.
• Si el pensamiento está deshabilitado, el turno final del asistente no debe contener ningún bloque de pensamiento

Desde la perspectiva del modelo, los bucles de uso de herramientas son parte del turno del asistente. Un turno del asistente no se completa hasta que Claude termina su respuesta completa, que puede incluir múltiples llamadas de herramientas y resultados.

Por ejemplo, esta secuencia es toda parte de un único turno del asistente:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

Aunque hay múltiples mensajes de API, el bucle de uso de herramientas es conceptualmente parte de una respuesta continua del asistente.

Degradación elegante del pensamiento

Cuando ocurre un conflicto de pensamiento a mitad de turno (como alternar el pensamiento activado o desactivado durante un bucle de uso de herramientas), la API desactiva automáticamente el pensamiento para esa solicitud. Para preservar la calidad del modelo y mantenerse en distribución, la API puede:

• Eliminar bloques de pensamiento de la conversación cuando crearían una estructura de turno inválida
• Desactivar el pensamiento para la solicitud actual cuando el historial de conversación es incompatible con el pensamiento habilitado

Esto significa que intentar alternar el pensamiento a mitad de turno no causará un error, pero el pensamiento se desactivará silenciosamente para esa solicitud. Para confirmar si el pensamiento estuvo activo, verifica la presencia de bloques thinking en la respuesta.

Orientación práctica

Mejor práctica: Planifica tu estrategia de pensamiento al inicio de cada turno en lugar de intentar alternar a mitad de turno.

Ejemplo: Alternar pensamiento después de completar un turno

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

Al completar el turno del asistente antes de alternar el pensamiento, aseguras que el pensamiento esté realmente habilitado para la nueva solicitud.

Preservar bloques de pensamiento

Durante el uso de herramientas, debes pasar bloques thinking de vuelta a la API, y debes incluir el bloque completo sin modificar de vuelta a la API. Esto es crítico para mantener el flujo de razonamiento del modelo e integridad de la conversación.

Cuando Claude invoca herramientas, está pausando la construcción de una respuesta para esperar información externa. Cuando se devuelven resultados de herramientas, Claude continúa construyendo esa respuesta existente. Esto requiere preservar bloques de pensamiento durante el uso de herramientas, por un par de razones:

1. Continuidad del razonamiento: Los bloques de pensamiento capturan el razonamiento paso a paso de Claude que llevó a solicitudes de herramientas. Cuando publiques resultados de herramientas, incluir el pensamiento original asegura que Claude pueda continuar su razonamiento desde donde se quedó.

2. Mantenimiento del contexto: Aunque los resultados de herramientas aparecen como mensajes de usuario en la estructura de la API, son parte de un flujo de razonamiento continuo. Preservar bloques de pensamiento mantiene este flujo conceptual a través de múltiples llamadas de API. Para más información sobre gestión de contexto, consulta la guía sobre ventanas de contexto.

Importante: Cuando proporcionas bloques thinking, la secuencia completa de bloques thinking consecutivos debe coincidir con los resultados generados por el modelo durante la solicitud original; no puedes reorganizar o modificar la secuencia de estos bloques.

Pensamiento intercalado

El pensamiento extendido con uso de herramientas en modelos Claude 4 admite pensamiento intercalado, que permite a Claude pensar entre llamadas de herramientas y hacer un razonamiento más sofisticado después de recibir resultados de herramientas.

Con pensamiento intercalado, Claude puede:

• Razonar sobre los resultados de una llamada de herramienta antes de decidir qué hacer a continuación
• Encadenar múltiples llamadas de herramientas con pasos de razonamiento en medio
• Tomar decisiones más matizadas basadas en resultados intermedios

Soporte de modelo:

• Claude Mythos Preview: El pensamiento intercalado ocurre automáticamente. Cada paso de razonamiento inter-herramienta se mueve a un bloque de pensamiento en lugar de texto plano, y los bloques de pensamiento se preservan a través de turnos por defecto. No se necesita ni se admite encabezado beta.
• Claude Opus 4.7: El pensamiento intercalado se habilita automáticamente cuando se usa pensamiento adaptativo (el único modo de pensamiento admitido en Opus 4.7). No se necesita encabezado beta.
• Claude Opus 4.6: El pensamiento intercalado se habilita automáticamente cuando se usa pensamiento adaptativo. No se necesita encabezado beta. El encabezado beta interleaved-thinking-2025-05-14 está deprecado en Opus 4.6 y se ignora de forma segura si se incluye.
• Claude Sonnet 4.6: El pensamiento intercalado se habilita automáticamente cuando se usa pensamiento adaptativo (recomendado). El encabezado beta interleaved-thinking-2025-05-14 con pensamiento extendido manual (thinking: {type: "enabled"}) sigue siendo funcional pero está deprecado.
• Otros modelos Claude 4 (Opus 4.5, Opus 4.1, Opus 4 (deprecado), Sonnet 4.5, Sonnet 4 (deprecado)): Añade a tu solicitud de API para habilitar el pensamiento intercalado.

Aquí hay algunas consideraciones importantes para el pensamiento intercalado:

• Con pensamiento intercalado, el budget_tokens puede exceder el parámetro max_tokens, ya que representa el presupuesto total en todos los bloques de pensamiento dentro de un turno del asistente.
• El pensamiento intercalado solo se admite para herramientas usadas a través de la API de Mensajes.
• Las llamadas directas a la API de Claude te permiten pasar interleaved-thinking-2025-05-14 en solicitudes a cualquier modelo, sin efecto (excepto Opus 4.7 y Opus 4.6, donde está deprecado e ignorado de forma segura).
• En plataformas de terceros (por ejemplo, Amazon Bedrock y Vertex AI), si pasas interleaved-thinking-2025-05-14 a cualquier modelo aparte de Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4 (deprecado), Sonnet 4.5, o Sonnet 4 (deprecado), tu solicitud fallará.

Pensamiento extendido con almacenamiento en caché de indicaciones

El almacenamiento en caché de indicaciones con pensamiento tiene varias consideraciones importantes:

Eliminación del contexto del bloque de pensamiento

• Los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar los puntos de ruptura de caché
• Al continuar conversaciones con uso de herramientas, los bloques de pensamiento se almacenan en caché y cuentan como tokens de entrada cuando se leen desde el caché
• Esto crea una compensación: aunque los bloques de pensamiento no consumen espacio de ventana de contexto visualmente, aún cuentan hacia tu uso de tokens de entrada cuando se almacenan en caché
• Si el pensamiento se deshabilita y pasas contenido de pensamiento en el turno actual de uso de herramientas, el contenido de pensamiento se eliminará y el pensamiento permanecerá deshabilitado para esa solicitud

Patrones de invalidación de caché

• Los cambios en los parámetros de pensamiento (habilitado/deshabilitado o asignación de presupuesto) invalidan los puntos de ruptura de caché de mensajes
• El pensamiento intercalado amplifica la invalidación de caché, ya que los bloques de pensamiento pueden ocurrir entre múltiples llamadas de herramientas
• Los indicadores del sistema y las herramientas permanecen almacenados en caché a pesar de los cambios en los parámetros de pensamiento o la eliminación de bloques

Comprendiendo el comportamiento del almacenamiento en caché de bloques de pensamiento

Cuando se utiliza pensamiento extendido con uso de herramientas, los bloques de pensamiento exhiben un comportamiento de almacenamiento en caché específico que afecta el conteo de tokens:

Cómo funciona:

1. El almacenamiento en caché solo ocurre cuando realiza una solicitud posterior que incluye resultados de herramientas
2. Cuando se realiza la solicitud posterior, el historial de conversación anterior (incluidos los bloques de pensamiento) puede almacenarse en caché
3. Estos bloques de pensamiento almacenados en caché cuentan como tokens de entrada en sus métricas de uso cuando se leen desde el caché
4. Cuando se incluye un bloque de usuario sin resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran y se eliminan del contexto

Flujo de ejemplo detallado:

Solicitud 1:

User: "What's the weather in Paris?"

Respuesta 1:

[thinking_block_1] + [tool_use block 1]

Solicitud 2:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

Respuesta 2:

[thinking_block_2] + [text block 2]

La solicitud 2 escribe un caché del contenido de la solicitud (no la respuesta). El caché incluye el mensaje de usuario original, el primer bloque de pensamiento, el bloque de uso de herramienta y el resultado de la herramienta.

Solicitud 3:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

Para Claude Opus 4.5 y posteriores (incluido Claude Opus 4.6), todos los bloques de pensamiento anteriores se mantienen de forma predeterminada. Para modelos más antiguos, debido a que se incluyó un bloque de usuario sin resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran. Esta solicitud se procesará de la misma manera que:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

Puntos clave:

• Este comportamiento de almacenamiento en caché ocurre automáticamente, incluso sin marcadores explícitos de cache_control
• Este comportamiento es consistente ya sea que use pensamiento regular o pensamiento intercalado

Tokens máximos y tamaño de ventana de contexto con pensamiento extendido

En modelos Claude más antiguos (anteriores a Claude Sonnet 3.7), si la suma de tokens de prompt y max_tokens excedía la ventana de contexto del modelo, el sistema ajustaría automáticamente max_tokens para que se ajustara al límite de contexto. Esto significaba que podías establecer un valor grande de max_tokens y el sistema lo reduciría silenciosamente según fuera necesario.

Con los modelos Claude 3.7 y 4, max_tokens (que incluye tu presupuesto de pensamiento cuando el pensamiento está habilitado) se aplica como un límite estricto. El sistema ahora devolverá un error de validación si los tokens de prompt + max_tokens exceden el tamaño de la ventana de contexto.

La ventana de contexto con pensamiento extendido

Al calcular el uso de la ventana de contexto con el pensamiento habilitado, hay algunas consideraciones de las que debes ser consciente:

• Los bloques de pensamiento de turnos anteriores se eliminan y no se cuentan hacia tu ventana de contexto
• El pensamiento del turno actual cuenta hacia tu límite de max_tokens para ese turno

El diagrama a continuación demuestra la gestión especializada de tokens cuando el pensamiento extendido está habilitado:

La ventana de contexto efectiva se calcula como:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Utiliza la API de conteo de tokens para obtener conteos de tokens precisos para tu caso de uso específico, especialmente cuando trabajes con conversaciones de múltiples turnos que incluyan pensamiento.

La ventana de contexto con pensamiento extendido y uso de herramientas

Cuando se utiliza pensamiento extendido con uso de herramientas, los bloques de pensamiento deben preservarse explícitamente y devolverse con los resultados de las herramientas.

El cálculo de la ventana de contexto efectiva para pensamiento extendido con uso de herramientas se convierte en:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

El diagrama a continuación ilustra la gestión de tokens para pensamiento extendido con uso de herramientas:

Gestión de tokens con pensamiento extendido

Dado el comportamiento de la ventana de contexto y max_tokens con pensamiento extendido en los modelos Claude 3.7 y 4, es posible que necesites:

• Monitorear y gestionar más activamente tu uso de tokens
• Ajustar los valores de max_tokens a medida que cambia la longitud de tu prompt
• Potencialmente usar los puntos finales de conteo de tokens con más frecuencia
• Ser consciente de que los bloques de pensamiento anteriores no se acumulan en tu ventana de contexto

Este cambio se ha realizado para proporcionar un comportamiento más predecible y transparente, especialmente a medida que los límites de tokens máximos han aumentado significativamente.

Cifrado de pensamiento

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

Here are some important considerations on thinking encryption:

• When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
• signature values are significantly longer in Claude 4 models than in previous models.
• The signature field is an opaque field and should not be interpreted or parsed.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Bloques de pensamiento redactados

Además de los bloques thinking regulares, la API puede devolver bloques redacted_thinking. Un bloque redacted_thinking contiene contenido de pensamiento cifrado en un campo data, sin resumen legible:

{
  "type": "redacted_thinking",
  "data": "..."
}

El campo data es opaco y está cifrado. Como el campo signature en bloques de pensamiento regulares, debes pasar bloques redacted_thinking de vuelta a la API sin cambios cuando continúes una conversación de múltiples turnos con herramientas.

Diferencias en el pensamiento entre versiones de modelos

La API de Mensajes maneja el pensamiento de manera diferente entre los modelos Claude Sonnet 3.7 y Claude 4, principalmente en el comportamiento de resumen.

Consulta la tabla a continuación para una comparación condensada:

Preservación de bloques de pensamiento en Claude Opus 4.5 y posteriores

A partir de Claude Opus 4.5 (y continuando en Claude Opus 4.6), los bloques de pensamiento de turnos anteriores del asistente se preservan en el contexto del modelo por defecto. Esto difiere de los modelos anteriores, que eliminan bloques de pensamiento de turnos anteriores.

Beneficios de la preservación de bloques de pensamiento:

• Optimización de caché: Cuando se utiliza uso de herramientas, los bloques de pensamiento preservados permiten aciertos de caché ya que se devuelven con resultados de herramientas y se almacenan en caché incrementalmente en el turno del asistente, lo que resulta en ahorros de tokens en flujos de trabajo de múltiples pasos
• Sin impacto en la inteligencia: Preservar bloques de pensamiento no tiene efecto negativo en el rendimiento del modelo

Consideraciones importantes:

• Uso de contexto: Las conversaciones largas consumirán más espacio de contexto ya que los bloques de pensamiento se retienen en el contexto
• Comportamiento automático: Este es el comportamiento predeterminado para Claude Opus 4.5 y modelos posteriores (incluyendo Claude Mythos Preview y Claude Opus 4.6). No se requieren cambios de código ni encabezados beta
• Compatibilidad hacia atrás: Para aprovechar esta característica, continúa pasando bloques de pensamiento completos y sin modificar de vuelta a la API como lo harías para uso de herramientas

Precios

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

• Tokens used during thinking (output tokens)
• Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
• Standard text output tokens

When using summarized thinking:

• Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
• Output tokens (billed): The original thinking tokens that Claude generated internally
• Output tokens (visible): The summarized thinking tokens you see in the response
• No charge: Tokens used to generate the summary

When using display: "omitted":

• Input tokens: Tokens in your original request (same as summarized)
• Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
• Output tokens (visible): Zero thinking tokens (the thinking field is empty)

Mejores prácticas y consideraciones para pensamiento extendido

Trabajar con presupuestos de pensamiento

• Optimización de presupuesto: El presupuesto mínimo es de 1.024 tokens. Comienza con el mínimo e incrementa el presupuesto de pensamiento gradualmente para encontrar el rango óptimo para tu caso de uso. Los conteos de tokens más altos permiten un razonamiento más completo pero con rendimientos decrecientes dependiendo de la tarea. Aumentar el presupuesto puede mejorar la calidad de la respuesta a costa de una latencia aumentada. Para tareas críticas, prueba diferentes configuraciones para encontrar el equilibrio óptimo. Ten en cuenta que el presupuesto de pensamiento es un objetivo en lugar de un límite estricto. El uso real de tokens puede variar según la tarea.
• Puntos de partida: Comienza con presupuestos de pensamiento más grandes (16k+ tokens) para tareas complejas y ajusta según tus necesidades.
• Presupuestos grandes: Para presupuestos de pensamiento superiores a 32k, utiliza procesamiento por lotes para evitar problemas de red. Las solicitudes que empujan al modelo a pensar por encima de 32k tokens causan solicitudes de larga duración que podrían encontrarse con tiempos de espera del sistema y límites de conexión abierta.
• Seguimiento del uso de tokens: Monitorea el uso de tokens de pensamiento para optimizar costos y rendimiento.

Consideraciones de rendimiento

• Tiempos de respuesta: Prepárate para tiempos de respuesta más largos debido al procesamiento adicional. Generar bloques de pensamiento aumenta el tiempo de respuesta general.
• Requisitos de streaming: Los SDKs requieren streaming cuando max_tokens es mayor que 21.333 para evitar tiempos de espera HTTP en solicitudes de larga duración. Esta es una validación del lado del cliente, no una restricción de la API. Si no necesitas procesar eventos incrementalmente, utiliza .stream() con .get_final_message() (Python) o .finalMessage() (TypeScript) para obtener el objeto Message completo sin manejar eventos individuales. Consulta Streaming de Mensajes para obtener detalles. Cuando hagas streaming, prepárate para manejar bloques de contenido de pensamiento y texto a medida que lleguen.
• Omitir pensamiento para latencia: Si tu aplicación no muestra contenido de pensamiento, establece display: "omitted" en la configuración de pensamiento para reducir el tiempo hasta el primer token de texto. Consulta Controlando la visualización del pensamiento.

Compatibilidad de características

• El pensamiento no es compatible con modificaciones de temperature o top_k así como con uso forzado de herramientas.
• Cuando el pensamiento está habilitado, puedes establecer top_p a valores entre 1 y 0.95.
• No puedes rellenar previamente respuestas cuando el pensamiento está habilitado.
• Los cambios en el presupuesto de pensamiento invalidan los prefijos de prompt almacenados en caché que incluyen mensajes. Sin embargo, los prompts del sistema almacenados en caché y las definiciones de herramientas continuarán funcionando cuando cambien los parámetros de pensamiento.

Directrices de uso

• Selección de tareas: Utiliza pensamiento extendido para tareas particularmente complejas que se benefician del razonamiento paso a paso, como matemáticas, codificación y análisis.
• Manejo de contexto: No necesitas eliminar bloques de pensamiento anteriores tú mismo. La API de Claude ignora automáticamente bloques de pensamiento de turnos anteriores y no se incluyen al calcular el uso de contexto.
• Ingeniería de prompts: Revisa los consejos de prompting de pensamiento extendido si deseas maximizar las capacidades de pensamiento de Claude.

Próximos pasos