Pensamiento

Un modelo que responde en una sola pasada tiene que acertar todo en el primer intento: sin borradores, sin verificación, sin cambiar de rumbo a mitad de camino. Para una demostración, un bug 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 le pide, 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 apoya 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 de 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: cómo activarlo, cómo leer su salida y cómo gestionar sus interacciones con herramientas, streaming, almacenamiento en caché y la ventana de contexto.



Cómo funciona el pensamiento

Que Claude piense 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 sin procesar: 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 nuevos, devuelve bloques de pensamiento con un campo thinking vacío. En cualquier caso, el bloque se factura igual y se devuelve igual en conversaciones de múltiples turnos; consulta Controlar la visualización del pensamiento para 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 enumera 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 necesita en estos modelos es ver el texto de pensamiento, ya que display tiene como valor predeterminado "omitted" ahí. Actívalo con thinking: {"type": "adaptive", "display": "summarized"}, que es exactamente la siguiente solicitud con la cadena del modelo intercambiada.

En Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6, el pensamiento está desactivado hasta que establezcas thinking: {type: "adaptive"} en tu solicitud. Los siguientes ejemplos hacen eso, establecen display: "summarized" para que el texto de pensamiento sea visible y usan un max_tokens holgado:

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 y 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 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 El 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"} con effort high o inferior. Con 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 hace cumplir 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 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 de pensamiento relaciona cada mensaje de error con su solución.



Leer la salida de pensamiento



Controlar 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. 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 sigue llevando el pensamiento completo cifrado para la continuidad en 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 de 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 los 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 siguen cobrando los tokens de pensamiento completos. 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 la signature para reconstruir el pensamiento original para la construcción del prompt (consulta Preservar los 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 la secuencia de eventos.

En el SDK de Ruby, establece este campo como display_: (con un guion bajo al final) para evitar ocultar Kernel#display de Ruby; 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 sin procesar. El pensamiento resumido proporciona todos los beneficios de inteligencia del pensamiento mientras previene el uso indebido. Ningún valor de display devuelve la cadena de pensamiento sin procesar.

Ten en cuenta lo siguiente al trabajar con pensamiento resumido:

• Se te cobran los tokens de pensamiento completos generados por la solicitud original, no 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 de pensamiento son más detalladas, proporcionando un razonamiento detallado que es 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.
• El resumen preserva las ideas clave del proceso de pensamiento de Claude con una latencia añadida mínima, lo que permite una experiencia de usuario transmisible por streaming.
• 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 de 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)

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 saber 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 exclusivamente 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:

• Menor costo o 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 demasiada poca frecuencia o con poca profundidad: 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 los modelos que lo permiten (consulta la tabla de configuración por modelo).
• Necesitas un límite estricto de gasto: usa max_tokens. Effort es una guía flexible; max_tokens es un límite estricto.



Pensamiento con uso de herramientas

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

1. Limitación de tool choice (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 los bloques de pensamiento: cuando devuelves resultados de herramientas, debes devolver a la API los bloques de pensamiento del mensaje del asistente, completos y sin modificar. Consulta Preservar los 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 el 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 con elegancia. 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 la conversación es incompatible con que el pensamiento esté 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 y 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)

Ten en cuenta que alternar los modos de pensamiento también invalida el almacenamiento en caché de prompts; consulta Pensamiento y almacenamiento en caché de prompts.



Preservar los 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. Devuelve cada bloque thinking 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 condujo a las solicitudes de herramientas. Incluirlos permite que Claude continúe 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 podar 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 último mensaje del asistente, la secuencia de bloques thinking consecutivos debe coincidir con lo que el modelo generó en la solicitud original: no puedes reordenarlos, 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 de 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 que Claude piense 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 todos los modelos que admiten 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 los 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 cada 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

Que los bloques de pensamiento de turnos anteriores del asistente permanezcan 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 las herramientas y se almacenan en caché de forma incremental a lo largo del turno del asistente, lo que resulta en ahorro 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 del contexto: las conversaciones largas consumen más espacio de contexto en los modelos que conservan todo, ya que los bloques de pensamiento retenidos cuentan como entrada como cualquier otro historial de conversación (consulta El 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 los bloques de pensamiento. Para anular el valor predeterminado en cualquier dirección, usa la limpieza 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 siguen añadiendo 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 ruptura de caché: los puntos de ruptura a nivel de mensaje siempre fallan, y los puntos de ruptura de herramientas y de la indicación del sistema también pueden fallar, dependiendo de dónde el modelo renderice la configuración. Trata cualquier cambio de pensamiento o de effort como si reiniciara la caché. Las solicitudes consecutivas que mantienen la misma configuración preservan la caché, y establecer un parámetro explícitamente en 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 momento, 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 y el intercalado. La contrapartida: los bloques de pensamiento que nunca vuelves a ver en las respuestas siguen contribuyendo al uso de tokens de entrada cuando se leen desde la caché.

Que los bloques anteriores estén en el contexto depende del modelo. El valor predeterminado de preservación rige esto. En los modelos que conservan todo, los bloques de pensamiento de turnos anteriores permanecen en caché y en el contexto. En los modelos que solo conservan 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 ahí:

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 los modelos que conservan todo, la misma solicitud mantiene thinking_block_1 y thinking_block_2 en el 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 elegante). El pensamiento intercalado amplifica los efectos de invalidación de caché, ya que los bloques de pensamiento pueden ocurrir entre múltiples llamadas a herramientas.



El 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 los modelos Claude 4.5 y más nuevos, 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 en la ventana de contexto para el turno que lo generó.
• El pensamiento de turnos anteriores depende del valor predeterminado de preservación. En los modelos que conservan todos los turnos anteriores, los bloques de pensamiento anteriores permanecen en el contexto, cuentan para la ventana y se facturan como tokens de entrada como el resto del historial de conversación. En los modelos que solo conservan 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 los 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 limpieza de bloques de pensamiento si necesitas recuperar espacio.
• En los modelos que solo conservan 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 el contexto junto con su resultado de herramienta durante la duración del turno del asistente, y 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 los bloques de pensamiento cuando usas herramientas con pensamiento. De lo contrario, puedes omitir los bloques de pensamiento de turnos anteriores. Si los devuelves, que la API los conserve o los elimine 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 hacer streaming de 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 (las 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 de pensamiento en Claude Fable 5 y Claude Mythos 5

En Claude Fable 5 y Claude Mythos 5, la cadena de pensamiento sin procesar nunca se devuelve; los bloques que recibes son bloques thinking regulares, no redacted_thinking, y la configuración 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 los bloques cuyo contenido devuelto ha sido modificado, no los bloques que has leído. El texto colocado en un campo thinking omitido vacío se ignora en lugar de rechazarse.

Para saber qué sucede con 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 con crédito de fallback deben reproducir 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 el 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 la guía de 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 está permitido 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 Message Batches API, 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 Messages. Espera tiempos de respuesta más largos cuando el pensamiento está activo, ya que generar bloques de pensamiento agrega tiempo de procesamiento. Para cargas de trabajo que llevan el pensamiento por encima de aproximadamente 32k tokens por solicitud, usa el procesamiento por lotes para evitar problemas de red: tales 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