Desarrollo con pensamiento extendido

El "extended thinking" (pensamiento extendido) le otorga a Claude capacidades de razonamiento mejoradas para tareas complejas, al tiempo que proporciona distintos niveles de transparencia sobre 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 actuales de Claude excepto Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 y Claude Opus 4.7, donde no se acepta y devuelve un error 400. Algunos modelos tienen un comportamiento específico según el modo:

• Claude Fable 5 (claude-fable-5) y Claude Mythos 5 (claude-mythos-5): el pensamiento extendido manual no es compatible y devuelve un error 400. El pensamiento adaptativo siempre está activado; usa el parámetro effort para controlar la profundidad del pensamiento.
• Claude Opus 4.8 (claude-opus-4-8): el pensamiento extendido manual no es compatible y devuelve un error 400. Usa pensamiento adaptativo (thinking: {type: "adaptive"}) con el parámetro effort en su lugar. El modelo determina si usar pensamiento extendido y en qué medida en función de cada solicitud.
• Claude Opus 4.7 (claude-opus-4-7): el pensamiento extendido manual ya no es compatible. Usa pensamiento adaptativo (thinking: {type: "adaptive"}) con el parámetro effort en su lugar.
• Claude Mythos Preview: el pensamiento adaptativo es el valor 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): se recomienda el pensamiento adaptativo; el modo manual (type: "enabled") está obsoleto pero sigue siendo funcional.
• Claude Sonnet 4.6 (claude-sonnet-4-6): se recomienda el pensamiento adaptativo; el modo manual (type: "enabled") con modo intercalado está obsoleto 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 las conclusiones 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í tienes 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 obtener más información sobre el formato de respuesta del pensamiento extendido, consulta la Referencia de la API de Messages.

Cómo usar el pensamiento extendido

Aquí tienes un ejemplo de cómo usar el pensamiento extendido en la API de Messages:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    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}")

Para activar el pensamiento extendido, agrega un objeto thinking, con el parámetro type establecido en enabled y budget_tokens con 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 obtener más detalles. Aunque type: "enabled" con budget_tokens sigue siendo funcional en estos modelos, está obsoleto y se eliminará en una versión futura.

El parámetro budget_tokens determina el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno. Este límite se aplica a los tokens de pensamiento completos, 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 es posible que Claude no use todo el presupuesto asignado, especialmente en rangos superiores a 32k.

budget_tokens debe establecerse en un valor menor que max_tokens. Sin embargo, cuando usas pensamiento intercalado con herramientas, puedes exceder este límite ya que el límite de tokens se convierte en toda tu ventana de contexto. Dado que budget_tokens debe ser menor que max_tokens, el pensamiento extendido no se puede combinar con max_tokens: 0 (precalentamiento de caché).

Pensamiento resumido

Con el pensamiento extendido habilitado, la API de Messages para los modelos Claude 4 devuelve un resumen del proceso de pensamiento completo de Claude. El pensamiento resumido proporciona todos los beneficios de inteligencia del pensamiento extendido, al tiempo que previene el uso indebido. Este es el comportamiento predeterminado en los modelos Claude 4 cuando el campo display en la configuración de pensamiento no está definido o está establecido en "summarized". En Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 y Claude Mythos Preview, display tiene como valor predeterminado "omitted", por lo que debes establecer display: "summarized" explícitamente para recibir el pensamiento resumido.

Estas son algunas consideraciones importantes sobre el pensamiento resumido:

• Se te cobra por los tokens de pensamiento completos generados por la solicitud original, no por los tokens del resumen.
• El recuento de tokens de salida facturados no coincidirá con el recuento de tokens que ves en la respuesta.
• En los modelos Claude 4, las primeras líneas de la salida de pensamiento son más detalladas y proporcionan un razonamiento exhaustivo que resulta particularmente útil para fines de ingeniería de prompts. Claude Mythos Preview resume desde el primer token, por lo que sus bloques de pensamiento no muestran este preámbulo detallado.
• A medida que Anthropic busca mejorar la función de pensamiento extendido, el comportamiento de resumen está sujeto a cambios.
• El resumen preserva las ideas clave del proceso de pensamiento de Claude con una latencia adicional mínima, lo que permite una experiencia de usuario compatible con streaming.
• El resumen es procesado por un modelo diferente al que especificas en tus solicitudes. El modelo de pensamiento no ve la salida resumida.

Control de la visualización del pensamiento

El campo display en la configuración de pensamiento controla cómo se devuelve el contenido de pensamiento en las respuestas de la API. Acepta dos valores:

• "summarized": Los bloques de pensamiento contienen texto de pensamiento resumido. Consulta Pensamiento resumido para más detalles. Este es el valor predeterminado en Claude Opus 4.6, Claude Sonnet 4.6 y modelos anteriores de Claude 4.
• "omitted": Los bloques de pensamiento se devuelven con un campo thinking vacío. El campo signature sigue conteniendo el pensamiento completo cifrado para mantener la continuidad en conversaciones de múltiples turnos (consulta Cifrado del pensamiento). Este es el valor predeterminado en Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 4.7 y Claude Mythos Preview.

Configurar display: "omitted" es útil cuando tu aplicación no muestra el contenido de pensamiento a los usuarios. El beneficio principal es un tiempo más rápido hasta el primer token de texto al usar streaming: el servidor omite por completo el streaming de los tokens de pensamiento y entrega únicamente la firma, por lo que la respuesta de texto final comienza a transmitirse antes.

Estas son algunas consideraciones importantes sobre el pensamiento omitido:

• Se te sigue cobrando por la totalidad de los tokens de pensamiento. Omitirlos reduce la latencia, no el costo.
• Si devuelves bloques de pensamiento en conversaciones de múltiples turnos, pásalos sin modificar. El servidor descifra el campo signature para reconstruir el pensamiento original al construir el prompt (consulta Preservar los bloques de pensamiento). Cualquier texto que coloques en el campo thinking de un bloque omitido que se envía de vuelta será ignorado.
• display no es válido con thinking.type: "disabled" (no hay nada que mostrar).
• Cuando se usa thinking.type: "adaptive" y el modelo omite el pensamiento para una solicitud simple, no se produce ningún bloque de pensamiento independientemente del valor de display.

Los pipelines automatizados que nunca muestran contenido de pensamiento a los usuarios finales pueden evitar la sobrecarga de recibir tokens de pensamiento por la red. 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.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

Cuando se establece display: "omitted", 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."
    }
  ]
}

Al hacer streaming con display: "omitted", no se emiten eventos thinking_delta; consulta Streaming de pensamiento a continuación para ver la secuencia de eventos.

Streaming de pensamiento

Puedes hacer streaming de respuestas de pensamiento extendido usando server-sent events (SSE).

Cuando el streaming está habilitado para el 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 Control de la visualización del pensamiento.

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

Aquí se muestra cómo manejar el streaming con pensamiento:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # Restablecer indicadores para cada nuevo bloque
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

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 el uso de herramientas, lo que permite a Claude razonar sobre la selección de herramientas y el procesamiento de resultados.

Al usar el 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 valor 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, lo cual es incompatible con el pensamiento extendido.

2. Preservación de bloques de pensamiento: Durante el uso de herramientas, debes pasar los bloques 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, incluso durante bucles de uso de herramientas. Todo el turno 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 a 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 la API, el bucle de uso de herramientas es conceptualmente parte de una respuesta continua del asistente.

Degradación controlada del pensamiento

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

• Eliminar bloques de pensamiento de la conversación cuando crearían una estructura de turno inválida
• Deshabilitar 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 deshabilitará silenciosamente para esa solicitud. Para confirmar si el pensamiento estuvo activo, verifica la presencia de bloques thinking en la respuesta.

Orientación práctica

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

Ejemplo: Alternar el 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, te aseguras de que el pensamiento esté realmente habilitado para la nueva solicitud.

Preservación de bloques de pensamiento

Durante el uso de herramientas, debes pasar los bloques thinking de vuelta a la API, y debes incluir el bloque completo sin modificar de vuelta a la API. Esto es fundamental para mantener el flujo de razonamiento del modelo y la 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 los resultados de las herramientas, Claude continúa construyendo esa respuesta existente. Esto hace necesario preservar los 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 condujo a las solicitudes de herramientas. Cuando publicas los resultados de las herramientas, incluir el pensamiento original garantiza que Claude pueda continuar su razonamiento desde donde lo dejó.

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

Importante: Al proporcionar bloques thinking, toda la secuencia de bloques thinking consecutivos debe coincidir con las salidas generadas por el modelo durante la solicitud original; no puedes reorganizar ni modificar la secuencia de estos bloques.

Pensamiento intercalado

El pensamiento extendido con uso de herramientas en los modelos Claude 4 admite "interleaved thinking" (pensamiento intercalado), que permite a Claude pensar entre llamadas a herramientas y realizar un razonamiento más sofisticado después de recibir los resultados de las herramientas.

Con el pensamiento intercalado, Claude puede:

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

Compatibilidad de modelos:

• Claude Opus 4.8: El pensamiento intercalado se habilita automáticamente al usar pensamiento adaptativo (el único modo de pensamiento compatible en Claude Opus 4.8). No se necesita ningún encabezado beta.
• Claude Mythos Preview: El pensamiento intercalado ocurre automáticamente. Cada paso de razonamiento entre herramientas se traslada a un bloque de pensamiento en lugar de texto plano, y los bloques de pensamiento se preservan entre turnos de forma predeterminada. No se necesita ni se admite ningún encabezado beta.
• Claude Opus 4.7: El pensamiento intercalado se habilita automáticamente al usar pensamiento adaptativo (el único modo de pensamiento compatible en Opus 4.7). No se necesita ningún encabezado beta.
• Claude Opus 4.6: El pensamiento intercalado se habilita automáticamente al usar pensamiento adaptativo. No se necesita ningún encabezado beta. El encabezado beta interleaved-thinking-2025-05-14 está obsoleto en Opus 4.6 y se ignora de forma segura si se incluye.
• Claude Sonnet 4.6: El pensamiento intercalado se habilita automáticamente al usar pensamiento adaptativo (recomendado). El encabezado beta interleaved-thinking-2025-05-14 con pensamiento extendido manual (thinking: {type: "enabled"}) sigue siendo funcional pero está obsoleto.
• Otros modelos Claude 4 (Opus 4.5, Opus 4.1 (obsoleto), Opus 4 (obsoleto), Sonnet 4.5, Sonnet 4 (obsoleto)): Agrega el encabezado beta interleaved-thinking-2025-05-14 a tu solicitud de API para habilitar el pensamiento intercalado.

Aquí hay algunas consideraciones importantes para el pensamiento intercalado:

• Con el pensamiento intercalado, budget_tokens puede exceder el parámetro max_tokens, ya que representa el presupuesto total de todos los bloques de pensamiento dentro de un turno del asistente.
• El pensamiento intercalado solo es compatible con herramientas usadas a través de la API de Messages.
• La API de Claude y Claude Platform en AWS aceptan interleaved-thinking-2025-05-14 en solicitudes a cualquier modelo sin devolver un error. En modelos que no admiten pensamiento intercalado, el encabezado se ignora. En Claude Opus 4.8, Claude Opus 4.7 y Claude Opus 4.6, está obsoleto y se ignora de forma segura. En Claude Mythos Preview, no es necesario y se ignora de forma segura.
• En plataformas operadas por socios (por ejemplo, Amazon Bedrock y Vertex AI), si pasas interleaved-thinking-2025-05-14 a cualquier modelo que no sea Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1 (obsoleto), Opus 4 (obsoleto), Sonnet 4.5 o Sonnet 4 (obsoleto), tu solicitud fallará.

Pensamiento extendido con almacenamiento en caché de prompts

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

Eliminación de bloques de pensamiento del contexto

• En modelos Opus/Sonnet anteriores y todos los modelos Haiku, los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar los puntos de interrupción de caché. En Opus 4.5+ y Sonnet 4.6+, se conservan de forma predeterminada.
• 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 la caché
• Esto crea una compensación: aunque los bloques de pensamiento no consumen espacio de la ventana de contexto visualmente, siguen contando para 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 interrupción 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 a herramientas
• Las indicaciones del sistema y las herramientas permanecen en caché a pesar de los cambios en los parámetros de pensamiento o la eliminación de bloques

Comprensión del comportamiento de caché de bloques de pensamiento

Al usar pensamiento extendido con uso de herramientas, los bloques de pensamiento exhiben un comportamiento de caché específico que afecta el conteo de tokens:

Cómo funciona:

1. El almacenamiento en caché solo ocurre cuando realizas 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) se puede almacenar en caché
3. Estos bloques de pensamiento almacenados en caché cuentan como tokens de entrada en tus métricas de uso cuando se leen desde la caché
4. Cuando se incluye un bloque de usuario que no es un resultado de herramienta: en Opus 4.5+ y Sonnet 4.6+, los bloques de pensamiento anteriores se conservan; en modelos Opus/Sonnet anteriores y todos los modelos Haiku, 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 una caché del contenido de la solicitud (no de la respuesta). La 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 Opus 4.5+ y Sonnet 4.6+, todos los bloques de pensamiento anteriores se conservan de forma predeterminada. Para modelos Opus/Sonnet anteriores y todos los modelos Haiku, dado que se incluyó un bloque de usuario que no es un resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran y se eliminan del contexto. 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 caché ocurre automáticamente, incluso sin marcadores cache_control explícitos
• Este comportamiento es consistente ya sea que uses pensamiento regular o pensamiento intercalado

Max tokens y tamaño de la ventana de contexto con pensamiento extendido

max_tokens (que incluye tu presupuesto de pensamiento cuando el pensamiento está habilitado) se aplica como un límite estricto. En los modelos Claude 4.5 y posteriores, si los tokens de entrada más max_tokens exceden el tamaño de la ventana de contexto, la API acepta la solicitud. Si la generación luego alcanza el límite de la ventana de contexto, se detiene con stop_reason: "model_context_window_exceeded". En modelos anteriores, la API devuelve un error de validación en su lugar. Consulta Manejo de stop reasons.

La ventana de contexto con pensamiento extendido

Al calcular el uso de la ventana de contexto con el pensamiento habilitado, hay algunas consideraciones a tener en cuenta:

• En Opus 4.5+ y Sonnet 4.6+, los bloques de pensamiento de turnos anteriores se conservan y cuentan para tu ventana de contexto; en modelos Opus/Sonnet anteriores y todos los modelos Haiku, se eliminan y no se cuentan
• El pensamiento del turno actual cuenta para tu límite de max_tokens para ese turno

El siguiente diagrama 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)

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

La ventana de contexto con pensamiento extendido y uso de herramientas

Al usar 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 siguiente diagrama 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, 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 endpoints de conteo de tokens con más frecuencia
• Tener en cuenta que los bloques de pensamiento anteriores no se acumulan en tu ventana de contexto

Cifrado del pensamiento

El contenido completo del pensamiento se cifra y se devuelve en el campo signature. Este campo se utiliza para verificar que los bloques de pensamiento fueron generados por Claude cuando se envían de vuelta a la API.

Aquí hay algunas consideraciones importantes sobre el cifrado del pensamiento:

• Cuando se usan respuestas en streaming, la firma se agrega mediante un signature_delta dentro de un evento content_block_delta justo antes del evento content_block_stop.
• Los valores de signature son significativamente más largos en los modelos Claude 4 que en modelos anteriores.
• El campo signature es un campo opaco y no debe interpretarse ni analizarse.
• Los valores de signature son compatibles entre plataformas (las API de Claude, Amazon Bedrock y Vertex AI). Los valores generados en una plataforma serán compatibles con otra.

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. Al igual que el campo signature en los bloques de pensamiento regulares, debes pasar los bloques redacted_thinking de vuelta a la API sin cambios al continuar una conversación de múltiples turnos con herramientas.

Diferencias en el pensamiento entre versiones de modelos

La API de Messages maneja el pensamiento de manera diferente entre las versiones de los modelos de Claude. La siguiente tabla ofrece una comparación resumida:

Preservación de bloques de pensamiento por modelo

Si los bloques de pensamiento de turnos anteriores del asistente se preservan en el contexto de forma predeterminada depende de la clase de modelo. Opus: Claude Opus 4.5 y los modelos Opus posteriores conservan todos los bloques de pensamiento anteriores; Claude Opus 4.1 (obsoleto) y los modelos Opus anteriores conservan solo el pensamiento del último turno del asistente. Sonnet: Claude Sonnet 4.6 y los modelos Sonnet posteriores conservan todos; Claude Sonnet 4.5 y los modelos Sonnet anteriores conservan solo el último turno. Haiku: todos los modelos Haiku hasta Claude Haiku 4.5 conservan solo el último turno. Claude Mythos Preview también conserva todos los bloques de pensamiento anteriores.

Beneficios de la preservación de bloques de pensamiento:

• Optimización de caché: Al usar uso de herramientas, los bloques de pensamiento preservados permiten aciertos de caché ya que se pasan de vuelta con los resultados de las herramientas y se almacenan en caché de forma incremental a lo largo del turno del asistente, lo que resulta en ahorros de tokens en flujos de trabajo de múltiples pasos
• Sin impacto en la inteligencia: Preservar los bloques de pensamiento no tiene ningún 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 valor predeterminado para cada modelo según se indica arriba. No se requieren cambios de código ni encabezados beta
• Compatibilidad con versiones anteriores: 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 el uso de herramientas

Precios

Para obtener información completa sobre precios, incluidas las tarifas base, escrituras en caché, aciertos de caché y tokens de salida, consulta la página de precios.

El proceso de pensamiento genera cargos por:

• Tokens utilizados durante el pensamiento (tokens de salida)
• Bloques de pensamiento de turnos anteriores del asistente que se mantienen en el contexto: solo el último turno en modelos Opus/Sonnet anteriores y en todos los modelos Haiku; todos los turnos de forma predeterminada en Opus 4.5+ y Sonnet 4.6+ (tokens de entrada)
• Tokens de salida de texto estándar

Al usar pensamiento resumido:

• Tokens de entrada: Tokens en tu solicitud original (excluye los tokens de pensamiento de turnos anteriores)
• Tokens de salida (facturados): Los tokens de pensamiento originales que Claude generó internamente
• Tokens de salida (visibles): Los tokens de pensamiento resumidos que ves en la respuesta
• Sin cargo: Tokens utilizados para generar el resumen

Al usar display: "omitted":

• Tokens de entrada: Tokens en tu solicitud original (igual que con el resumido)
• Tokens de salida (facturados): Los tokens de pensamiento originales que Claude generó internamente (igual que con el resumido)
• Tokens de salida (visibles): Cero tokens de pensamiento (el campo thinking está vacío)

Para ver cuántos tokens de salida facturados se gastaron en el razonamiento interno, lee usage.output_tokens_details.thinking_tokens en la respuesta. Este valor refleja el razonamiento sin procesar que generó el modelo (no el texto resumido devuelto en el cuerpo) y siempre es menor o igual que output_tokens. Réstalo de output_tokens para aproximar la parte de la salida que no corresponde al razonamiento.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens sigue siendo el total inclusivo y autoritativo utilizado para la facturación. output_tokens_details es un desglose de solo lectura para fines de observabilidad.

Prácticas recomendadas y consideraciones para el pensamiento extendido

Trabajar con presupuestos de pensamiento

• Optimización del presupuesto: El presupuesto mínimo es de 1.024 tokens. Comienza con el mínimo y aumenta el presupuesto de pensamiento de forma incremental para encontrar el rango óptimo para tu caso de uso. Un mayor número de tokens permite un razonamiento más completo, pero con rendimientos decrecientes según la tarea. Aumentar el presupuesto puede mejorar la calidad de la respuesta a cambio de una mayor latencia. Para tareas críticas, prueba diferentes configuraciones para encontrar el equilibrio óptimo. Ten en cuenta que el presupuesto de pensamiento es un objetivo y no 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 (más de 16k tokens) para tareas complejas y ajústalos según tus necesidades.
• Presupuestos grandes: Para presupuestos de pensamiento superiores a 32k, usa el procesamiento por lotes para evitar problemas de red. Las solicitudes que llevan al modelo a pensar por encima de 32k tokens generan solicitudes de larga duración que podrían toparse con tiempos de espera del sistema y límites de conexiones abiertas.
• Seguimiento del uso de tokens: Monitorea el uso de tokens de pensamiento para optimizar costos y rendimiento. El campo usage.output_tokens_details.thinking_tokens en la respuesta informa cuántos de los tokens de salida facturados corresponden a razonamiento interno. Cuando se usa streaming, este desglose aparece únicamente en el evento final message_delta.

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 total de respuesta.
• Requisitos de streaming: Los SDK requieren streaming cuando max_tokens es mayor que 21.333 para evitar tiempos de espera de 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 de forma incremental, usa .stream() con .get_final_message() (Python) o .finalMessage() (TypeScript) para obtener el objeto Message completo sin manejar eventos individuales. Consulta Streaming de mensajes para más detalles. Cuando uses streaming, prepárate para manejar tanto los bloques de contenido de pensamiento como los de texto a medida que llegan.
• Omitir el pensamiento para reducir la latencia: Si tu aplicación no muestra el contenido de pensamiento, establece display: "omitted" en la configuración de pensamiento para reducir el tiempo hasta el primer token de texto. Consulta Controlar la visualización del pensamiento.

Compatibilidad de funciones

• El pensamiento no es compatible con modificaciones de temperature o top_k, ni con el uso forzado de herramientas.
• Cuando el pensamiento está habilitado, puedes establecer top_p en valores entre 1 y 0,95.
• No puedes prellenar respuestas cuando el pensamiento está habilitado.
• Los cambios en el presupuesto de pensamiento invalidan los prefijos de prompts almacenados en caché que incluyen mensajes. Sin embargo, las indicaciones del sistema y las definiciones de herramientas almacenadas en caché seguirán funcionando cuando cambien los parámetros de pensamiento.

Pautas de uso

• Selección de tareas: Usa el pensamiento extendido para tareas particularmente complejas que se beneficien del razonamiento paso a paso, como matemáticas, programación y análisis.
• Manejo del contexto: No necesitas eliminar tú mismo los bloques de pensamiento anteriores. En Opus 4.5+ y Sonnet 4.6+, la API de Claude conserva los bloques de pensamiento de turnos anteriores de forma predeterminada; en modelos Opus/Sonnet anteriores y en todos los modelos Haiku, los ignora automáticamente y no se incluyen al calcular el uso del contexto.
• Ingeniería de prompts: Revisa los consejos de prompting para pensamiento extendido si quieres maximizar las capacidades de pensamiento de Claude.

Próximos pasos