Pensamiento

Un modelo que responde en una sola pasada tiene que acertar todo al primer intento: sin trabajo preliminar, sin verificación, sin cambiar de rumbo a mitad del camino. Para una demostración matemática, un error complicado o una tarea agéntica larga, el primer enfoque a menudo no es el mejor.

El pensamiento elimina esa restricción. Cuando el pensamiento está activo, Claude trabaja el problema con sus propias palabras antes de responder: reformula lo que se está preguntando, prueba enfoques, verifica resultados intermedios y abandona caminos que no se sostienen. Ese razonamiento llega en bloques de contenido thinking antes de la respuesta, y Claude se basa en él para producir la respuesta final. Por eso el pensamiento mejora el rendimiento en tareas complejas como matemáticas, programación, análisis y trabajo agéntico de larga duración, donde la calidad de la respuesta depende de trabajo intermedio que de otro modo se comprimiría en la propia respuesta o se omitiría.

El pensamiento tiene un costo: los tokens que Claude gasta razonando se facturan como tokens de salida, incluso cuando el texto del pensamiento no se te devuelve, y cuentan para max_tokens junto con el texto de la respuesta. Esta página cubre cómo se comporta el pensamiento en toda la superficie de la API: activarlo, leer su salida y gestionar sus interacciones con herramientas, streaming, almacenamiento en caché y la ventana de contexto.



Cómo funciona el pensamiento

Si Claude piensa en una solicitud dada, y con qué profundidad, depende de tu configuración de pensamiento y de la complejidad de la solicitud.

Así es como se ve el pensamiento en una respuesta: uno o más bloques de contenido thinking llegan antes de los bloques text. El bloque de pensamiento sigue siendo contenido generado, como el bloque text que le sigue, pero está separado de la respuesta canónica. Cada bloque de pensamiento también lleva un campo signature, una copia cifrada del razonamiento completo que devuelves sin cambios en conversaciones de múltiples turnos y de uso de herramientas (consulta Cifrado del pensamiento):

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

No siempre ves este texto, y lo que ves nunca es la cadena de pensamiento en bruto: el texto en un bloque de pensamiento es un resumen del razonamiento de Claude. El campo display en la configuración de pensamiento controla si ese resumen se devuelve o no: "summarized" lo devuelve, mientras que "omitted", el valor predeterminado en los modelos más recientes, devuelve bloques de pensamiento con un campo thinking vacío. De cualquier manera, el bloque se factura igual y se devuelve igual en conversaciones de múltiples turnos. Consulta Controlar la visualización del pensamiento para ver los valores predeterminados por modelo y los detalles.

Si Claude usa herramientas, el pensamiento también puede aparecer entre llamadas a herramientas. Consulta Pensamiento con uso de herramientas. Para el formato completo de la respuesta, consulta la referencia de la API de Messages.



Configurar el pensamiento

En los modelos actuales, el pensamiento está activado de forma predeterminada o a un parámetro de distancia. Qué configuración acepta cada modelo, y cuál es su valor predeterminado, se indica en la tabla de configuración por modelo en la página de Solución de problemas.

En Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview, el pensamiento ya está activado: no se necesita configuración. Lo primero que la mayoría de los desarrolladores necesitan en estos modelos es ver el texto del pensamiento, porque display tiene como valor predeterminado "omitted" allí. Actívalo con thinking: {"type": "adaptive", "display": "summarized"}, que es exactamente la siguiente solicitud con la cadena del modelo cambiada.

En Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6, el pensamiento está desactivado hasta que estableces thinking: {type: "adaptive"}, lo que permite a Claude decidir cuándo y con qué profundidad pensar según la solicitud. Los siguientes ejemplos hacen eso, establecen display: "summarized" para que el texto del pensamiento sea visible, y usan un max_tokens amplio:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Ejecutar el ejemplo imprime el pensamiento resumido, luego la respuesta:

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

Los tokens de pensamiento cuentan para max_tokens, así que establécelo lo suficientemente alto como para dejar espacio tanto para el pensamiento como para el texto de la respuesta. Consulta Control de costos en la página de dirección y Pensamiento y la ventana de contexto.



Desactivar el pensamiento

En Claude Sonnet 5, donde el pensamiento está activado de forma predeterminada, puedes desactivarlo:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

Claude Opus 5 también tiene el pensamiento activado de forma predeterminada y acepta thinking: {type: "disabled"} en effort high o inferior. En effort xhigh o max, el pensamiento no se puede desactivar: las solicitudes que combinan thinking: {type: "disabled"} con esos niveles de effort devuelven un error 400. Esta restricción se aplica a Claude Opus 5 y modelos posteriores y se aplica en cada solicitud. Con el pensamiento desactivado, Claude Opus 5 puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible. Consulta Ejecutar con el pensamiento desactivado para ver mitigaciones mediante prompts.

Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview rechazan thinking: {type: "disabled"}: el pensamiento no se puede desactivar en estos modelos.

Si tu modelo solo admite pensamiento extendido (consulta la tabla de configuración por modelo), configúralo con type: "enabled" y un valor de budget_tokens en su lugar. La página de Pensamiento extendido cubre esa configuración. Y si alguna configuración de pensamiento devuelve un error 400, Solución de problemas del pensamiento relaciona cada mensaje de error con su solución.



Leer la salida del pensamiento



Controlar la visualización del pensamiento

El campo display en la configuración de pensamiento controla cómo se devuelve el contenido del pensamiento en las respuestas de la API. display funciona en ambos modos: establécelo junto con type: "adaptive" o type: "enabled". Acepta dos valores:

• "summarized": los bloques de pensamiento contienen texto de pensamiento resumido, un resumen legible del razonamiento de Claude. Este es el valor predeterminado en Claude Opus 4.6, Claude Sonnet 4.6 y modelos anteriores.
• "omitted": los bloques de pensamiento se devuelven con un campo thinking vacío. El campo signature aún lleva el pensamiento completo cifrado para la continuidad de múltiples turnos (consulta Cifrado del pensamiento). Este es el valor predeterminado en Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7 y Claude Mythos Preview.

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

Con 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."
    }
  ]
}

Ten en cuenta lo siguiente al trabajar con pensamiento omitido:

• Se te sigue cobrando por los tokens completos de pensamiento. Omitir reduce la latencia, no el costo.
• Si devuelves bloques de pensamiento en conversaciones de múltiples turnos, devuélvelos sin cambios. El servidor descifra el signature para reconstruir el pensamiento original para la construcción del prompt (consulta Preservar bloques de pensamiento). Cualquier texto que coloques en el campo thinking de un bloque omitido que se devuelve se ignora.
• display no es válido con thinking.type: "disabled" (no hay nada que mostrar).
• Al usar thinking.type: "adaptive" y el modelo omite el pensamiento para una solicitud simple, no se produce ningún bloque de pensamiento independientemente de display.
• Al hacer streaming con display: "omitted", no se emiten eventos thinking_delta. Consulta Streaming del pensamiento para ver la secuencia de eventos.

En el SDK de Ruby, los hashes simples toman display: como muestran los ejemplos. La clase tipada ThinkingConfigAdaptive nombra el parámetro display_ (con guion bajo al final, para evitar ocultar Kernel#display de Ruby). De cualquier manera, el campo en el protocolo sigue siendo display.



Pensamiento resumido

Cuando display es "summarized", el texto de pensamiento que recibes es un resumen del proceso de pensamiento completo de Claude en lugar de la cadena de pensamiento en bruto. El pensamiento resumido proporciona todos los beneficios de inteligencia del pensamiento mientras previene el uso indebido. Ninguna configuración de display devuelve la cadena de pensamiento en bruto.

Ten en cuenta lo siguiente al trabajar con pensamiento resumido:

• Se te cobra por los tokens completos de pensamiento generados por la solicitud original, no por los tokens del resumen. El recuento de tokens de salida facturados no coincide con el recuento de tokens que ves en la respuesta.
• En Claude Opus 4.6, Claude Sonnet 4.6 y modelos anteriores, las primeras líneas de la salida del pensamiento son más detalladas, proporcionando razonamiento detallado que es particularmente útil para propósitos 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.
• El resumen preserva las ideas clave del proceso de pensamiento de Claude con una latencia añadida mínima, por lo que los resúmenes pueden transmitirse a medida que llegan.
• El resumen es procesado por un modelo diferente al que apuntas en tus solicitudes. El modelo de pensamiento no ve la salida resumida.
• A medida que Anthropic busca mejorar la función de pensamiento, el comportamiento del resumen está sujeto a cambios.



Streaming del pensamiento

El pensamiento funciona con streaming. Los bloques de pensamiento se transmiten como eventos thinking_delta dentro de eventos content_block_delta, seguidos de un único evento signature_delta justo antes del content_block_stop del bloque. Los bloques de texto se transmiten después como de costumbre.

Los siguientes ejemplos transmiten una respuesta con pensamiento adaptativo, imprimiendo los deltas de pensamiento y texto a medida que llegan:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Para reensamblar bloques de pensamiento completos con sus firmas después del streaming, usa el helper de acumulación de mensajes de tu SDK donde exista uno (por ejemplo, stream.get_final_message() en Python o stream.finalMessage() en TypeScript) en lugar de concatenar los deltas tú mismo.

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":""}}

Para la mecánica general del streaming, consulta Streaming de Messages.



Pensamiento y effort

El parámetro thinking controla si Claude piensa en bloques de pensamiento antes de responder; el parámetro effort controla cuánto trabajo dedica Claude a toda la respuesta, lo que en el modo adaptativo incluye con qué frecuencia y con qué profundidad piensa. No pases adaptive como valor de effort: adaptive es un modo de pensamiento, no un nivel de esfuerzo.

Para ver qué hace cada nivel de effort con el comportamiento del pensamiento, consulta la tabla de comportamiento del pensamiento por nivel en la página Dirigir el pensamiento. La página de Effort documenta el parámetro en sí, incluyendo qué niveles admite cada modelo. En Claude Opus 4.5, el único modelo exclusivo de pensamiento extendido que admite effort, effort se compone con budget_tokens. Consulta Reglas y ajuste del presupuesto.

Con los dos controles separados de esta manera, elige el que coincida con tu objetivo:

• Reducir el costo o la latencia en una carga de trabajo con pensamiento habilitado: reduce effort primero. Escala toda la respuesta hacia abajo, incluido el pensamiento.
• Claude está pensando con muy poca frecuencia o muy superficialmente: aumenta effort, o consulta Dirigir con qué frecuencia piensa Claude en la página de dirección.
• Necesitas el pensamiento completamente desactivado: usa thinking: {type: "disabled"} en modelos que lo permitan (consulta la tabla de configuración por modelo).
• Necesitas un límite estricto de gasto: usa max_tokens. Effort es una guía suave. max_tokens es un límite estricto.



Pensamiento con uso de herramientas

El pensamiento funciona junto con el uso de herramientas, permitiendo a Claude razonar sobre la selección de herramientas y procesar los resultados de las herramientas. Se aplican dos restricciones:

1. Limitación de elección de herramienta (modo manual): el uso de herramientas con pensamiento extendido manual (thinking: {type: "enabled"}) 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": "..."} resulta en un error porque estas opciones fuerzan el uso de herramientas, lo cual es incompatible con el pensamiento extendido manual. El pensamiento adaptativo, incluso en modelos donde el pensamiento está activado de forma predeterminada, admite el uso forzado de herramientas.
2. Preservar bloques de pensamiento: cuando devuelves resultados de herramientas, debes pasar los bloques de pensamiento del mensaje del asistente de vuelta a la API, completos y sin modificar. Consulta Preservar bloques de pensamiento.

Un bucle de uso de herramientas es un turno del asistente. Desde la perspectiva del modelo, un turno del asistente no se completa hasta que Claude termina su respuesta completa, que puede incluir múltiples llamadas a herramientas y resultados. Toda esta secuencia es 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"]

Todo el turno se ejecuta en un único modo de pensamiento: no puedes alternar el pensamiento en medio de un turno, incluso durante el bucle de uso de herramientas. En modo extendido (manual), la API además exige que el turno final del asistente de una solicitud con pensamiento habilitado comience con un bloque de pensamiento. El modo adaptativo relaja esto: ningún turno del asistente necesita comenzar con uno.

Los conflictos a mitad de turno se degradan de forma controlada. Si alternas el pensamiento a mitad de turno (por ejemplo, entre enviar una llamada a herramienta y devolver su resultado), la API no genera un error. En su lugar, desactiva silenciosamente el pensamiento para esa solicitud. Para preservar la calidad del modelo, la API puede eliminar bloques de pensamiento que crearían una estructura de turno inválida, o desactivar el pensamiento cuando el historial de conversación es incompatible con el pensamiento habilitado. Para confirmar si el pensamiento estuvo activo, verifica la presencia de bloques thinking en la respuesta.

Alterna entre turnos, no dentro de ellos. Planifica tu estrategia de pensamiento al inicio de cada turno. Completa el turno del asistente, luego cambia la configuración de pensamiento para el siguiente:

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)

Alternar los modos de pensamiento también invalida el almacenamiento en caché de prompts. Consulta Pensamiento y almacenamiento en caché de prompts.



Preservar bloques de pensamiento

Cuando Claude invoca una herramienta, pausa la construcción de su respuesta para esperar información externa. Cuando devuelves el resultado de la herramienta, Claude continúa construyendo esa misma respuesta, por lo que su razonamiento anterior debe seguir presente. Pasa cada bloque thinking de vuelta a la API completo y sin modificar, junto con el bloque tool_use que lo acompañaba. Esto importa por dos razones:

1. Continuidad del razonamiento: los bloques de pensamiento capturan el razonamiento paso a paso que llevó a las solicitudes de herramientas. Incluirlos permite a Claude continuar razonando desde donde lo dejó.
2. Mantenimiento del contexto: los resultados de herramientas aparecen como mensajes de usuario en la estructura de la API, pero son parte de un flujo de razonamiento continuo. Preservar los bloques de pensamiento mantiene ese flujo a través de las llamadas a la API.

En resumen:

• Obligatorio: dentro de un turno de uso de herramientas, devuelve los bloques de pensamiento.
• Recomendado: entre turnos, devuelve todo.
• Permitido: fuera del uso de herramientas, omite el pensamiento de turnos anteriores.

No necesitas eliminar el pensamiento antiguo tú mismo. Devuelve todos los bloques de pensamiento en conversaciones de múltiples turnos, y la API los filtra automáticamente, conserva los bloques necesarios para preservar el razonamiento del modelo, y factura tokens de entrada solo por los bloques que realmente se muestran a Claude. Qué bloques de turnos anteriores se conservan depende del modelo. Consulta Preservación de bloques de pensamiento por modelo. Para anular el valor predeterminado, usa la estrategia de edición de contexto clear_thinking_20251015.

Dentro del mensaje del asistente más reciente, la secuencia de bloques thinking consecutivos debe coincidir con lo que el modelo generó en la solicitud original: no puedes reorganizarlos, editarlos ni eliminarlos parcialmente. Esto incluye los bloques redacted_thinking.

Para un recorrido completo de dos turnos con código en cada SDK, consulta Pensamiento en flujos de trabajo de herramientas y múltiples turnos. Define una herramienta, recibe una respuesta de pensamiento más uso de herramientas, y devuelve el turno del asistente con el resultado de la herramienta.



Pensamiento intercalado

El pensamiento intercalado permite a Claude pensar entre llamadas a herramientas, razonando sobre cada resultado de herramienta antes de actuar sobre él. 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 entre ellas
• Tomar decisiones más matizadas basadas en resultados intermedios

Con el pensamiento adaptativo, el pensamiento intercalado es automático en cada modelo que admite pensamiento adaptativo. No se necesita ningún encabezado beta. En Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8 y Claude Opus 4.7, el razonamiento entre llamadas a herramientas siempre aparece en bloques de pensamiento. Claude Haiku 4.5 no admite pensamiento intercalado. En modelos que usan pensamiento extendido manual, el intercalado requiere un encabezado beta y cambia cómo se cuenta el presupuesto de pensamiento. Pensamiento intercalado en modo manual cubre las reglas por modelo y el comportamiento del encabezado específico de la plataforma.

Con el pensamiento intercalado, la asignación de pensamiento puede abarcar todo el turno del asistente en lugar de una sola respuesta. El pensamiento intercalado solo se admite para herramientas usadas a través de la API de Messages.

Para una comparación práctica que muestra qué cambia el pensamiento intercalado en un flujo de trabajo de dos herramientas, consulta Cómo el pensamiento intercalado cambia el flujo.



Preservación de bloques de pensamiento por modelo

Si los bloques de pensamiento de turnos anteriores del asistente permanecen en el contexto de forma predeterminada depende del modelo:

• Conservar todos los turnos anteriores: Claude Opus 4.5 y modelos Opus posteriores, Claude Sonnet 4.6 y modelos Sonnet posteriores, Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview.
• Conservar solo el último turno: modelos Opus y Sonnet anteriores, y todos los modelos Haiku hasta Claude Haiku 4.5. Cuando devuelves bloques de pensamiento más antiguos, la API los elimina automáticamente. No necesitas eliminarlos tú mismo.

La preservación aporta dos beneficios:

• Optimización de caché: los bloques de pensamiento preservados permiten aciertos de caché durante el uso de herramientas, ya que se devuelven con los resultados de 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.

La contrapartida es el uso de contexto: las conversaciones largas consumen más espacio de contexto en modelos que conservan todo, porque los bloques de pensamiento retenidos cuentan como entrada al igual que cualquier otro historial de conversación (consulta Pensamiento y la ventana de contexto). El comportamiento es automático en ambos regímenes. No se requieren cambios de código ni encabezados beta, y debes seguir devolviendo bloques de pensamiento completos y sin modificar como se describe en Preservar bloques de pensamiento. Para anular el valor predeterminado en cualquier dirección, usa la eliminación de bloques de pensamiento.

Cambiar de modelo a mitad de conversación. Cuando cambias entre dos modelos cualesquiera, por ejemplo después de un fallback por rechazo del clasificador, elimina los bloques thinking y redacted_thinking de los turnos anteriores del asistente. Los bloques de pensamiento están vinculados al modelo que los produjo. Otros modelos los ignoran silenciosamente en lugar de rechazar la solicitud, pero los bloques ignorados aún añaden tokens de entrada.



Pensamiento y almacenamiento en caché de prompts

El almacenamiento en caché de prompts interactúa con el pensamiento de algunas maneras específicas. Las siguientes reglas se aplican en ambos modos de pensamiento.

Los cambios de configuración invalidan el almacenamiento en caché. La configuración de pensamiento y el nivel de effort resuelto se renderizan en el propio prompt, por lo que cambiar cualquiera de ellos inicia un nuevo prefijo de caché. Cambiar entre adaptive, enabled y disabled, cambiar budget_tokens y cambiar el valor de effort invalidan los puntos de interrupción de caché: los puntos de interrupción a nivel de mensaje siempre fallan, y los puntos de interrupción de herramientas e indicación del sistema también pueden fallar, dependiendo de dónde renderice el modelo la configuración. Trata cualquier cambio de pensamiento o effort como un reinicio de la caché. Las solicitudes consecutivas que mantienen la misma configuración preservan la caché, y establecer un parámetro explícitamente a su valor predeterminado es equivalente a omitirlo. Una demostración práctica con salida de uso está en la página Dirigir el pensamiento.

Los bloques de pensamiento se almacenan en caché con los resultados de herramientas. Durante un bucle de uso de herramientas, el almacenamiento en caché ocurre cuando haces una solicitud de seguimiento que incluye resultados de herramientas. En ese punto, el historial de conversación anterior, incluidos sus bloques de pensamiento, puede almacenarse en caché, y esos bloques de pensamiento en caché cuentan como tokens de entrada en tus métricas de uso cuando se leen desde la caché. Esto ocurre automáticamente, incluso sin marcadores cache_control explícitos, y se comporta igual para el pensamiento regular e intercalado. La contrapartida: los bloques de pensamiento que nunca vuelves a ver en las respuestas aún contribuyen al uso de tokens de entrada cuando se leen desde la caché.

Si los bloques anteriores están en el contexto depende del modelo. El valor predeterminado de preservación gobierna esto. En modelos que conservan todo, los bloques de pensamiento de turnos anteriores permanecen en caché y en contexto. En modelos que conservan solo el último turno, una vez que envías un mensaje de usuario que no es un resultado de herramienta, todos los bloques de pensamiento anteriores se eliminan del contexto. En esos modelos, una conversación como esta:

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]

se procesa como si los bloques de pensamiento nunca hubieran estado allí:

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]

En modelos que conservan todo, la misma solicitud mantiene thinking_block_1 y thinking_block_2 en contexto y en la caché.

La degradación elimina el pensamiento del historial almacenable en caché. Si el pensamiento se desactiva a mitad de turno y pasas contenido de pensamiento en el turno actual de uso de herramientas, el contenido de pensamiento se elimina y el pensamiento permanece desactivado para esa solicitud (consulta degradación controlada). El pensamiento intercalado amplifica los efectos de invalidación de caché, porque los bloques de pensamiento pueden ocurrir entre múltiples llamadas a herramientas.



Pensamiento y la ventana de contexto

max_tokens, que incluye todo el pensamiento que Claude genera en el turno actual, se aplica como un límite estricto. En modelos Claude 4.5 y más recientes, 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 lugar de devolver un error. En modelos anteriores, la API devuelve un error de validación en su lugar. Consulta Manejo de razones de detención.

Cómo cuenta el pensamiento contra la ventana depende de cuándo se generó:

• El pensamiento del turno actual siempre cuenta para max_tokens, se factura como tokens de salida y ocupa espacio de la ventana de contexto para el turno que lo generó.
• El pensamiento de turnos anteriores depende del valor predeterminado de preservación. En modelos que conservan todos los turnos anteriores, los bloques de pensamiento anteriores permanecen en contexto, cuentan para la ventana y se facturan como tokens de entrada al igual que el resto del historial de conversación. En modelos que conservan solo el último turno, la API elimina automáticamente los bloques de pensamiento más antiguos cuando los devuelves, por lo que no consumen espacio de ventana ni tokens de entrada.

En la práctica:

• En modelos que conservan todo, presupuesta tu ventana de contexto como si el pensamiento fuera historial de conversación ordinario, porque lo es. Las sesiones agénticas largas acumulan pensamiento en el contexto. Usa la eliminación de bloques de pensamiento si necesitas recuperar espacio.
• En modelos que conservan solo el último turno, el pensamiento es solo un costo por turno: el pensamiento de cada turno cuenta contra el max_tokens de ese turno y luego sale de la ventana.

Los siguientes diagramas ilustran el régimen de solo último turno (eliminación). El primero muestra una conversación de múltiples turnos: el bloque de pensamiento de cada turno se genera en la salida pero no se traslada a la entrada de turnos posteriores.

El segundo muestra el mismo régimen con uso de herramientas: el pensamiento permanece en contexto junto con su resultado de herramienta durante la duración del turno del asistente, luego sale en el siguiente turno del usuario.

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



Cifrado del pensamiento

El contenido completo del pensamiento está cifrado y se devuelve en el campo signature de cada bloque de pensamiento. La API usa la firma para verificar que los bloques de pensamiento fueron generados por Claude cuando los devuelves.

Ten en cuenta lo siguiente al trabajar con firmas:

• Solo es estrictamente necesario devolver bloques de pensamiento cuando usas herramientas con pensamiento. De lo contrario, puedes omitir los bloques de pensamiento de turnos anteriores. Si los devuelves, si la API los conserva o los elimina depende del modelo (consulta Preservación de bloques de pensamiento por modelo). Usa la edición de contexto para configurar esto.
• Al devolver bloques de pensamiento, devuelve todo exactamente como lo recibiste, por consistencia y para evitar posibles problemas.
• Al transmitir respuestas, la firma llega como 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 Claude 4 y modelos posteriores que en modelos anteriores.
• El campo signature es opaco: no lo interpretes ni lo analices.
• Los valores de signature son compatibles entre plataformas (la API de Claude, Amazon Bedrock y Google Cloud). Los valores generados en una plataforma funcionan en otra.



Bloques de pensamiento redactados

Además de los bloques thinking regulares, la API puede devolver bloques redacted_thinking cuando partes del razonamiento de Claude se redactan por seguridad. Un bloque redacted_thinking contiene contenido de pensamiento cifrado en un campo data, sin texto 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, devuelve los bloques redacted_thinking a la API sin cambios al continuar una conversación de múltiples turnos con herramientas.



Salida del pensamiento en Claude Fable 5 y Claude Mythos 5

En Claude Fable 5 y Claude Mythos 5, la cadena de pensamiento en bruto nunca se devuelve. Los bloques que recibes son bloques thinking regulares, no redacted_thinking, y la configuración de display funciona igual que en otros modelos (texto resumido, o un campo thinking vacío cuando se omite, el valor predeterminado aquí). Para la forma de respuesta de los bloques de pensamiento, consulta la referencia de la API de Messages.

Al continuar una conversación en el mismo modelo, devuelve cada bloque de pensamiento a la API exactamente como lo recibiste, incluidos los bloques cuyo campo thinking está vacío. No los edites ni los reconstruyas. Leer el texto del resumen para mostrarlo está bien: la API rechaza bloques cuyo contenido devuelto ha sido modificado, no bloques que has leído. El texto colocado en un campo thinking vacío omitido se ignora en lugar de rechazarse.

Para ver cómo se manejan los bloques de pensamiento cuando cambias de modelo a mitad de conversación, consulta Preservación de bloques de pensamiento por modelo.

Dos excepciones, cubiertas en Crédito de fallback:

• Los reintentos de crédito de fallback deben devolver el cuerpo de la solicitud rechazada sin cambios.
• Los bloques fallback de un fallback a mitad de salida permanecen donde aparecieron.

Para obtener visibilidad del razonamiento del modelo, lee los bloques thinking descritos en esta página en lugar de solicitar razonamiento en el texto de la respuesta. En Claude Fable 5, una solicitud que intenta obtener el razonamiento interno del modelo como parte del texto de la respuesta puede ser rechazada con stop_details.category: "reasoning_extraction". Consulta Categorías de rechazo para la referencia del campo y orientación sobre el manejo.



Límites y compatibilidad de funciones

Parámetros de muestreo. En Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7 y Claude Sonnet 5, los valores no predeterminados de temperature, top_p o top_k devuelven un error 400 en cada solicitud, independientemente de si se usa el pensamiento. En modelos más antiguos, la restricción se aplica solo mientras el pensamiento está activado: temperature y top_k son incompatibles con el pensamiento, y top_p se permite con valores entre 0.95 y 1.

Prellenado de respuesta y uso forzado de herramientas. No puedes prellenar la respuesta del asistente mientras el pensamiento está activado. El uso forzado de herramientas (tool_choice: {"type": "any"} o {"type": "tool", ...}) es incompatible con el pensamiento extendido manual, pero funciona con el pensamiento adaptativo. Consulta Pensamiento con uso de herramientas.

Límites de salida. Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 y Claude Sonnet 4.6 admiten hasta 128k tokens de salida por solicitud. Claude Haiku 4.5, Claude Sonnet 4.5 y Claude Opus 4.5 admiten hasta 64k. En la API de Message Batches, el encabezado beta output-300k-2026-03-24 eleva el límite a 300k para Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5, Claude Opus 4.6 y Claude Sonnet 4.6. Consulta la descripción general de modelos para conocer los límites de los modelos heredados.

Solicitudes largas. Los SDK 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 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. Espera tiempos de respuesta más largos cuando el pensamiento está activo, porque generar bloques de pensamiento añade tiempo de procesamiento. Para cargas de trabajo que elevan el pensamiento por encima de aproximadamente 32k tokens por solicitud, usa el procesamiento por lotes para evitar problemas de red: dichas solicitudes pueden ejecutarse el tiempo suficiente como para alcanzar los tiempos de espera del sistema y los límites de conexiones abiertas.



Próximos pasos