Pensamiento

Un modelo que responde en una sola pasada tiene que acertar en todo al primer intento: sin borradores, sin verificaciones y sin cambiar de rumbo a mitad de camino. En una demostración, un error complicado o una tarea agéntica larga, el primer enfoque a menudo no es el mejor.

El "thinking" (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 los caminos que no se sostienen. Ese pensamiento inicial 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. En esas tareas, la calidad de la respuesta depende de un 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 explica 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 las herramientas, el streaming, el almacenamiento en caché y la "context window" (ventana de contexto).

Cómo funciona el pensamiento

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

Así se ve el pensamiento inicial 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 lo sigue, pero está separado de la respuesta canónica. Cada bloque de pensamiento también incluye un campo signature, una copia cifrada del razonamiento completo que devuelves sin cambios en conversaciones de varios 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 de un bloque de pensamiento es un resumen del razonamiento de Claude. El campo display de la configuración de pensamiento controla si ese resumen se devuelve o no: "summarized" lo devuelve, mientras que "omitted", el valor predeterminado en muchos modelos, 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 varios turnos. Consulta Controlar la visualización del pensamiento para conocer los valores predeterminados por modelo y más 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 la mayoría de los modelos, el pensamiento está activado de forma predeterminada o a un parámetro de distancia. La siguiente tabla muestra qué hace cada modelo con cada valor de thinking que puede enviar una solicitud. Un error 400 significa que la API rechaza la solicitud, y Solución de problemas del pensamiento incluye cada error y su solución.

En la tabla, "con esfuerzo high o inferior" significa que la solicitud funciona con esfuerzo low, medium y high, y devuelve un error 400 con xhigh o max.

En Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview y Claude Haiku 5.5, el pensamiento ya está activado y no necesita configuración. display tiene como valor predeterminado "omitted" en estos modelos, por lo que el texto del pensamiento permanece oculto hasta que lo habilites. Habilítalo con thinking: {"type": "adaptive", "display": "summarized"}, como hacen los siguientes ejemplos.

En Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6, el pensamiento está desactivado hasta que configures thinking: {type: "adaptive"}, lo que permite a Claude determinar cuándo y con qué profundidad pensar según la solicitud. La misma solicitud, cambiando la cadena del modelo, lo activa allí. Los siguientes ejemplos configuran display: "summarized" para que el texto del pensamiento sea visible y usan un max_tokens holgado:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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:
    match block.type:
        case "thinking":
            print(f"\nThinking: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Al ejecutar el ejemplo se 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 configúralo 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 control del pensamiento 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 un "effort" (esfuerzo) high o inferior. Con esfuerzo xhigh o max, el pensamiento no se puede desactivar: las solicitudes que combinan thinking: {type: "disabled"} con esos niveles de esfuerzo devuelven un error 400. Esta restricción 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 conocer mitigaciones mediante prompts.

Claude Sonnet 5.5 también tiene el pensamiento activado de forma predeterminada y rechaza thinking: {type: "disabled"} con un error 400. Para desactivar el pensamiento inicial, envía thinking: {type: "between_tools"} en su lugar. Es la configuración de pensamiento más baja en Claude Sonnet 5.5 y se acepta con esfuerzo high o inferior. El modelo sigue devolviendo sus actualizaciones de progreso entre llamadas a herramientas. Sin herramientas, la respuesta contiene solo texto, como con disabled en Claude Sonnet 5. Consulta Ejecución sin pensamiento previo para obtener orientación sobre prompts.

Claude Haiku 5.5 también tiene el pensamiento activado de forma predeterminada y acepta thinking: {type: "disabled"} con un esfuerzo high o inferior. Con esfuerzo xhigh o max, esa combinación devuelve un error 400. Para obtener menos pensamiento, reduce primero el nivel de esfuerzo. Con el pensamiento desactivado, el modelo puede omitir una llamada a herramienta que necesita cuando también solicitas salida JSON. Un output_config.effort por mensaje que difiera del nivel vigente también devuelve un error 400 mientras el pensamiento está desactivado. Consulta Usa el esfuerzo para controlar el pensamiento y Usa el pensamiento adaptativo con salida JSON y tus propias herramientas.

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

Para comprobar si un modelo acepta "disabled" antes de enviar una solicitud, lee su valor capabilities.thinking.types.disabled.supported desde la API de Models. Uso de la API de Models describe el campo.

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 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 de 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: configúralo junto con type: "adaptive" o type: "enabled". Acepta estos 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 conteniendo el pensamiento completo cifrado para la continuidad entre varios turnos (consulta Cifrado del pensamiento). Este es el valor predeterminado en Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Mythos Preview y Claude Haiku 5.5.
• "updates" (beta): los bloques de razonamiento se devuelven con un campo thinking vacío, como con "omitted", y las breves actualizaciones de progreso que algunos modelos escriben entre llamadas a herramientas se devuelven como texto legible. Requiere el encabezado beta thinking-display-updates-2026-08-18.

Configura display: "omitted" cuando tu aplicación no muestre el contenido del pensamiento a los usuarios. El principal beneficio es un menor tiempo 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 todos los tokens de pensamiento. Omitirlo reduce la latencia, no el costo.
• Si devuelves bloques de pensamiento en conversaciones de varios 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 devuelvas se ignora.
• display no es válido con thinking.type: "disabled" (no hay nada que mostrar) ni con thinking.type: "between_tools" (solo Claude Sonnet 5.5), que no acepta ningún otro campo. Con between_tools, las actualizaciones de progreso siguen devolviéndose con texto de resumen, como ocurre con display: "updates" (consulta Actualizaciones de progreso).
• 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 transmite texto de pensamiento. Cada bloque de pensamiento transmite un thinking_delta con una cadena thinking vacía y luego su signature_delta. Con display: "updates", solo los bloques de actualización de progreso transmiten eventos thinking_delta que contienen texto. Consulta Streaming del pensamiento para ver la secuencia de eventos.

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 ofrece todos los beneficios de inteligencia del pensamiento y, al mismo tiempo, evita el uso indebido. Ninguna configuración de display devuelve la cadena de pensamiento sin procesar.

Ten en cuenta lo siguiente al trabajar con pensamiento resumido:

• Se te cobran todos los tokens de pensamiento 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 del pensamiento son más detalladas y proporcionan un razonamiento minucioso que resulta especialmente ú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 conserva las ideas clave del proceso de pensamiento de Claude con una latencia adicional mínima, por lo que los resúmenes pueden transmitirse a medida que llegan.
• El resumen lo genera un modelo diferente del que usas en tus solicitudes. El modelo que piensa no ve la salida resumida.
• A medida que Anthropic busca mejorar la función de pensamiento, el comportamiento del resumen está sujeto a cambios.

Para ver el razonamiento del modelo, lee los bloques thinking en lugar de pedir el razonamiento en el texto de la respuesta. En Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 y Claude Fable 5, una solicitud que intente obtener el razonamiento interno del modelo como parte del texto de la respuesta puede rechazarse con stop_details.category: "reasoning_extraction". Consulta Categorías de rechazo para la referencia del campo y Mantén el razonamiento en bloques de pensamiento para saber qué pedir en su lugar.

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 e imprimen los deltas de pensamiento y de texto a medida que llegan:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    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:
        match event.type:
            case "content_block_start":
                print(f"\nStarting {event.content_block.type} block...")
            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "thinking_delta":
                        print(delta.thinking, end="", flush=True)
                    case "text_delta":
                        print(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, stream.get_final_message(), en lugar de concatenar los deltas tú mismo.

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}}

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 configura display: "omitted", el bloque de pensamiento se abre, llega un thinking_delta con una cadena thinking vacía, le sigue un único signature_delta y el bloque se cierra. 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":"thinking_delta","thinking":""}}

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

Con display: "updates" (beta), los bloques de razonamiento se transmiten igual que con "omitted". Cada bloque de actualización de progreso transmite su texto como eventos thinking_delta antes del bloque tool_use que introduce. Es normal una pausa de varios segundos antes de que se abra el bloque de actualización de progreso:

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

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}}

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

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}}

Con "updates", trata un bloque como una actualización de progreso en cuanto uno de sus eventos thinking_delta contenga texto no vacío.

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

Pensamiento y esfuerzo

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 la respuesta completa, lo que en 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 esfuerzo en el comportamiento del pensamiento, consulta la tabla de comportamiento del pensamiento por nivel en la página Dirigir el pensamiento. La página Esfuerzo documenta el parámetro en sí, incluidos los niveles que admite cada modelo. En Claude Opus 4.5, el único modelo exclusivo de pensamiento extendido que admite esfuerzo, el esfuerzo se combina con budget_tokens. Consulta Reglas y ajuste del presupuesto.

Con los dos controles separados de esta manera, elige el que se ajuste a tu objetivo:

• Menor costo o latencia en una carga de trabajo con pensamiento habilitado: reduce primero effort. Reduce toda la respuesta, incluido el pensamiento.
• Claude piensa con muy poca frecuencia o con poca profundidad: aumenta effort, o consulta Dirigir con qué frecuencia piensa Claude en la página de control del pensamiento.
• Necesitas el pensamiento completamente desactivado: usa thinking: {type: "disabled"} en los modelos que lo permiten (consulta la tabla de configuración por modelo). Claude Sonnet 5.5 rechaza "disabled". Su configuración más baja es thinking: {type: "between_tools"}, que desactiva el pensamiento inicial.
• Necesitas un límite estricto de gasto: usa max_tokens. El esfuerzo es una orientación flexible. max_tokens es un límite estricto.

Pensamiento con uso de herramientas

El pensamiento funciona junto con el "tool use" (uso de herramientas), lo que permite a Claude razonar sobre la selección de herramientas y procesar los resultados de las herramientas. Se aplican dos restricciones:

1. Limitación de la elección de herramientas (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": "..."} produce 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, excepto en Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1 (consulta Prellenado de respuestas y uso forzado de herramientas). Donde se acepta el uso forzado de herramientas, la respuesta comienza con la llamada a la herramienta y no tiene bloque thinking.
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 solo 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 varias llamadas a herramientas y sus 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 a mitad 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 flexibiliza 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 un turno (por ejemplo, entre enviar una llamada a herramienta y devolver su resultado), la API no devuelve 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 no válida, o desactivar el pensamiento cuando el historial de la conversación es incompatible con tener el pensamiento habilitado. Para confirmar si el pensamiento estuvo activo, comprueba 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)

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 sigue construyendo esa misma respuesta, por lo que su razonamiento anterior debe seguir presente. Devuelve a la API cada bloque thinking completo y sin modificar, junto con el bloque tool_use al que acompañaba. Esto es importante por dos razones:

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

En resumen:

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

No necesitas eliminar tú mismo el pensamiento antiguo. Devuelve todos los bloques de pensamiento en las conversaciones de varios turnos: la API los filtra automáticamente, conserva los bloques necesarios para preservar el razonamiento del modelo y solo factura como tokens de entrada los bloques que realmente se muestran a Claude. Los bloques de turnos anteriores que se conservan dependen del modelo. Consulta Preservación de bloques de pensamiento por modelo. Para cambiar el comportamiento 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 eliminar solo algunos. Esto incluye los bloques redacted_thinking.

Para ver un ejemplo completo de dos turnos con código en cada SDK, consulta Pensamiento en flujos de trabajo con herramientas y de varios turnos. El ejemplo define una herramienta, recibe una respuesta con pensamiento y uso de herramientas, y devuelve el turno del asistente junto con el resultado de la herramienta.

Pensamiento intercalado

El "interleaved thinking" (pensamiento intercalado) permite a Claude pensar entre llamadas a herramientas, razonando sobre cada resultado de herramienta antes de actuar en consecuencia. Con el pensamiento intercalado, Claude puede:

• Razonar sobre los resultados de una llamada a herramienta antes de determinar qué hacer a continuación
• Encadenar varias 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.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.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 contabiliza 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 ver una comparación práctica que muestra qué cambia el pensamiento intercalado en un flujo de trabajo con dos herramientas, consulta Cómo el pensamiento intercalado cambia el flujo.

Actualizaciones de progreso entre llamadas a herramientas

En Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Fable 5, el modelo puede escribir una actualización de progreso entre llamadas a herramientas. Una actualización de progreso es una nota sobre lo que el modelo acaba de encontrar y lo que va a hacer a continuación, escrita para la persona que observa al agente y no como razonamiento. Cada una se devuelve como su propio bloque thinking con su propia signature, separado de cualquier bloque de razonamiento en el mismo punto. Se ubica inmediatamente antes del bloque tool_use o server_tool_use que introduce. Como máximo, una actualización de progreso precede a cada llamada a herramienta, y el modelo puede omitir cualquiera de ellas. Las actualizaciones de progreso no son pensamiento intercalado: aparecen tanto si aparecen bloques de razonamiento entre llamadas a herramientas como si no, y una respuesta puede contener ambos.

Lo que contiene un bloque de actualización de progreso depende de display:

En Claude Sonnet 5.5, la configuración de pensamiento más baja es thinking: {type: "between_tools"}. Desactiva el pensamiento inicial, y cada actualización de progreso se devuelve con su texto de resumen, como ocurriría con display: "updates". between_tools solo se acepta con esfuerzo high o inferior. Con xhigh o max, una solicitud que lo incluya devuelve un error 400. between_tools no admite ningún otro campo: display, budget_tokens o block_binding enviados con él devuelven un error 400. La configuración no necesita encabezado beta y funciona en todas las plataformas que ofrecen Claude Sonnet 5.5. Devuelve los bloques sin cambios: un bloque de actualización de progreso que devuelves le da al modelo la nota completa que escribió, no el resumen.

Usa display: "updates" para una interfaz de agente que mantiene oculto el razonamiento y muestra al usuario una línea de estado en cada paso. Con este valor, cualquier bloque thinking con texto no vacío es una actualización de progreso, así que muestra esos y nada más. Está en beta y requiere el encabezado beta thinking-display-updates-2026-08-18 (para enviarlo en Amazon Bedrock, Google Cloud o Microsoft Foundry, consulta Funciones beta en otras plataformas). Sin él, el valor se rechaza con el mismo error 400 invalid_request_error que un valor de display desconocido.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": [
    {
      "name": "edit_file",
      "description": "Replace the contents of a file in the repository.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "The login test fails after an hour of uptime. Find out why and fix it."
    }
  ]
}

Con "updates", el inicio de la respuesta que sigue a un tool_result se ve así. El primer bloque es razonamiento y permanece vacío, como ocurriría con "omitted". El segundo contiene texto, por lo que es una actualización de progreso. Con "summarized" ambos bloques contienen texto, y con "omitted" ambos están vacíos.

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EqMBCkYICxIM..."
    },
    {
      "type": "thinking",
      "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.",
      "signature": "Es8CCkYICxIM..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "edit_file",
      "input": { "path": "auth.py", "content": "..." }
    }
  ]
}

Ten en cuenta lo siguiente al trabajar con actualizaciones de progreso:

• Devuelve los bloques de actualización de progreso sin cambios junto con el resto del turno del asistente, como cualquier otro bloque thinking.
• El texto que recibes es un resumen de la actualización de progreso, normalmente una o dos oraciones. No dependas de su longitud. La actualización de progreso cuenta para usage.output_tokens con su longitud completa, no con la del resumen.
• Un bloque de actualización de progreso puede devolverse con un campo thinking vacío con cualquier valor de display. No muestres nada para un bloque vacío. Con "updates" se ve igual que un bloque de razonamiento vacío y no necesita un manejo aparte.
• Cuando una respuesta se detiene por max_tokens, model_context_window_exceeded o stop_sequence poco después de una llamada a herramienta o de un resultado de herramienta, su último bloque puede ser un bloque de actualización de progreso que sustituye al trabajo que el modelo no había terminado. Con "updates" y "summarized" su texto es exactamente This part of the response was interrupted before it finished. y puedes mostrarlo como cualquier otra actualización. Con "omitted" está vacío. Para continuar, devuelve el turno del asistente sin cambios y agrega un nuevo mensaje user (con un tool_result para cada bloque tool_use de ese turno).
• Al hacer streaming, espera una pausa de varios segundos antes de que se abra un bloque de actualización de progreso. Consulta la traza de "updates" en Streaming del pensamiento.
• Estos modelos escriben menos actualizaciones de progreso con un esfuerzo más alto y en cadenas largas de herramientas. Si tu interfaz depende de ellas, consulta Pide actualizaciones de progreso para el usuario o, para Claude Opus 5.5, Actualizaciones de progreso para el usuario. Para Claude Sonnet 5.5, consulta Actualizaciones de progreso para el usuario.

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 Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, 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 "tool use" (uso de herramientas), ya que se devuelven junto con los resultados de herramientas y se almacenan en caché de forma incremental a lo largo del turno del asistente, lo que genera ahorro de tokens en flujos de trabajo de varios 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, porque los bloques de pensamiento retenidos cuentan como entrada igual que 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 los 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 eliminación de bloques de pensamiento.

Cambiar de modelo a mitad de la conversación. Sigue devolviendo los bloques de pensamiento sin cambios cuando cambies de modelo, por ejemplo después de un fallback por rechazo del clasificador. Un bloque de pensamiento solo puede leerlo el modelo que lo produjo y ciertos otros modelos, y la API ignora o descarta los bloques que el modelo de destino no puede leer. En Claude Fable 5.1 y Claude Mythos 5.1 la dirección importa: leen los bloques de pensamiento de modelos anteriores, y solo ellos dos leen los del otro, por lo que cambiar a ellos conserva el razonamiento de la conversación y cambiar de ellos a cualquier otro modelo lo descarta (consulta cómo se facturan y reportan los bloques descartados). Claude Opus 5.5 lee los bloques de pensamiento de Claude Opus 5 y los de modelos Opus, Sonnet y Haiku anteriores, y, en la Claude API y Google Cloud, los de Claude Haiku 5.5, pero no los de los modelos Claude Fable y Claude Mythos; en la Claude API, Claude Fable 5.1 y Claude Mythos 5.1 leen los bloques de Claude Opus 5.5. Un cambio de Claude Opus 5.5 a Claude Fable 5.1 en la Claude API conserva el razonamiento de los turnos anteriores; un cambio de Claude Fable 5.1 a Claude Opus 5.5 lo descarta. Claude Sonnet 5.5 lee bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores, y, en la Claude API y Google Cloud, de Claude Haiku 5.5, pero no de Claude Opus 5, Claude Opus 5.5 ni de ningún modelo Claude Fable o Claude Mythos. En la Claude API y Google Cloud, Claude Opus 5.5 lee los bloques de Claude Sonnet 5.5 y ningún otro modelo lo hace: un cambio de Claude Sonnet 5.5 a Claude Opus 5.5 en la Claude API y Google Cloud conserva el razonamiento de los turnos anteriores, y cualquier otro cambio desde Claude Sonnet 5.5 lo descarta. Claude Haiku 5.5 lee bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores, pero no de Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ni de ningún modelo Claude Fable o Claude Mythos. En la Claude API y Google Cloud, Claude Opus 5.5 y Claude Sonnet 5.5 leen los bloques de Claude Haiku 5.5 y ningún otro modelo lo hace. Elimina tú mismo los bloques thinking y redacted_thinking anteriores solo para ahorrar tokens de entrada en modelos que los ignoran en lugar de descartarlos, y nunca al canjear un crédito de respaldo, que requiere el cuerpo sin cambios.

Pensamiento preservado

El pensamiento preservado determina si el modelo puede usar un bloque de pensamiento que devuelves de un turno anterior. A partir de Claude Fable 5.1, la API verifica la signature de cada bloque thinking o redacted_thinking en una solicitud para comprobar dos cosas:

• El modelo que lo produjo. Cada modelo lee sus propios bloques de pensamiento y los de un conjunto fijo de otros modelos. Claude Fable 5.1 lee bloques de Claude Opus 5 y, en la Claude API, de Claude Opus 5.5; ni Claude Opus 5 ni Claude Opus 5.5 leen bloques de Claude Fable 5.1. La API descarta un bloque que el modelo actual no puede leer, sin error y sin facturarlo. Consulta Cambiar de modelo a mitad de la conversación.
• Todo lo enviado antes de él. Un bloque sigue siendo válido solo mientras la indicación system de nivel superior, las tools y los mensajes anteriores a él no cambien. Si alguno de ellos cambia, ese bloque y todos los bloques de pensamiento posteriores dejan de ser válidos, y la API rechaza la solicitud con un error 400 o descarta los bloques no válidos, según lo que elijas. Consulta Mantener el prefijo sin cambios.

Los bloques de pensamiento de Claude Sonnet 5.5 y Claude Haiku 5.5 también están vinculados a la cuenta que los produjo. Consulta Los bloques de pensamiento permanecen con la cuenta que los produjo para saber dónde aplica esto la API.

La verificación del modelo se aplica a todas las cuentas. La API aplica la verificación del prefijo de forma predeterminada para las cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC. En cuentas más antiguas, aplica la verificación solo en solicitudes que establecen thinking.block_binding.prefix_mismatch_behavior. Haz que tu integración solo agregue contenido al final, independientemente de la antigüedad de tu cuenta, para que el mismo código funcione en todas las cuentas, incluidas las cuentas más nuevas en las que se aplica de forma predeterminada.

Para mantener válido el pensamiento, devuelve cada turno del asistente exactamente como lo recibiste y agrega mensajes nuevos solo al final de messages. Si tu código construye el arreglo messages por sí mismo, la página de Pensamiento preservado cubre:

• Qué cuenta como una edición, y cómo comprobar si tu código realiza una.
• La función de la API que reemplaza cada edición común: mensajes del sistema a mitad de la conversación para nuevas instrucciones y recordatorios por turno, bloques tool_addition y tool_removal para cambios de herramientas, output_config por mensaje para cambios de esfuerzo, y compactación del lado del servidor y edición de contexto para recortar.
• Compactación del lado del cliente: qué patrones mantienen válido el pensamiento y cuáles no.
• El encabezado beta thinking-binding-controls-2026-08-01. Agrega un campo block_binding.prefix_mismatch_behavior ("error" o "drop_block") a la configuración de pensamiento y un arreglo input_transformations a cada respuesta. El arreglo enumera cada bloque de pensamiento que la API descartó, o que no superó la verificación del prefijo y se dejó pasar.

Pensamiento y almacenamiento en caché de prompts

El "prompt caching" (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 la caché. La configuración de pensamiento y el nivel de effort resuelto se representan dentro del 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 esfuerzo 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 y de la "system prompt" (indicación del sistema) también pueden fallar, según dónde represente el modelo la configuración. Trata cualquier cambio de pensamiento o de esfuerzo de nivel superior como un reinicio de la caché. En los modelos que admiten esfuerzo por mensaje, un cambio de esfuerzo incluido en un mensaje role: "system" dentro de messages deja intacto el prefijo en caché. Las solicitudes consecutivas que mantienen la misma configuración preservan la caché, y establecer un parámetro explícitamente en su valor predeterminado equivale a omitirlo. Un bloque de pensamiento que la API descarta bajo cualquier condición de pensamiento preservado cambia el prefijo en caché desde la posición de ese bloque en adelante. Los bloques devueltos sin cambios mantienen intacta la caché. Hay una demostración práctica con la salida de uso 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 o no 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 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 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 del 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 la caché, porque los bloques de pensamiento pueden aparecer 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 recientes, si los tokens de entrada más max_tokens superan el tamaño de la "context window" (ventana de contexto), la API acepta la solicitud. Si luego la generación 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 en su lugar un error de validación. Consulta Manejo de los motivos 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 durante 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 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 la ventana ni tokens de entrada.

En la práctica:

• En los modelos que conservan todo, planifica 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 los 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 el último turno (eliminación). El primero muestra una conversación de varios turnos: el bloque de pensamiento de cada turno se genera en la salida, pero no se traslada a la entrada de los 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 el turno del asistente y luego sale en el siguiente turno del usuario.

Usa la API de conteo de tokens para obtener conteos precisos para tu caso de uso específico, especialmente en conversaciones de varios turnos que incluyen pensamiento.

Cifrado del pensamiento

El contenido completo del pensamiento se cifra y se devuelve en el campo signature de cada bloque de pensamiento. Cuando devuelves los bloques de pensamiento, la API usa la firma para verificar que Claude los generó.

Ten en cuenta lo siguiente al trabajar con firmas:

• Solo es estrictamente necesario devolver los bloques de pensamiento cuando usas herramientas con pensamiento. En los demás casos, 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 coherencia 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 considerablemente más largos en Claude 4 y modelos posteriores que en los modelos anteriores.
• El campo signature es opaco, así que no lo interpretes ni lo analices.
• Los valores de signature son compatibles entre plataformas (la Claude API, Amazon Bedrock y Google Cloud). Los valores generados en una plataforma funcionan en otra, excepto que los bloques de pensamiento de Claude Sonnet 5.5 y Claude Haiku 5.5 solo funcionan en la cuenta que los produjo o en una cuenta vinculada a ella. Consulta Los bloques de pensamiento permanecen con la cuenta que los produjo.

Bloques de pensamiento censurados

Además de los bloques thinking regulares, la API puede devolver bloques redacted_thinking cuando partes del razonamiento de Claude se censuran por motivos de 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 de los bloques de pensamiento regulares, devuelve los bloques redacted_thinking a la API sin cambios cuando continúes una conversación de varios turnos con herramientas.

Límites y compatibilidad de funciones

Parámetros de muestreo

En Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 y Claude Haiku 5.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 estos modelos, el valor predeterminado de top_p es 0.99, por lo que un top_p de 1 devuelve un error 400, al igual que una solicitud que incluye tanto temperature como top_p, incluso con sus valores predeterminados. Consulta Elimina los parámetros de muestreo. 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 respuestas y uso forzado de herramientas

Los modelos Claude 4.6 y posteriores y Claude Mythos Preview rechazan un turno final del asistente prellenado con un error 400, esté o no activado el pensamiento (consulta Prefill no admitido). En modelos anteriores, 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. Las excepciones son Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1, que rechazan el uso forzado de herramientas en cada solicitud con un error 400. En esos modelos, usa en su lugar tool_choice: {"type": "auto"} con uso estricto de herramientas o salidas estructuradas. Donde se acepta el uso forzado de herramientas, la respuesta comienza con la llamada a la herramienta y no tiene bloque thinking. Para permitir que el modelo piense antes de llamar a una herramienta, usa tool_choice: {"type": "auto"} e indica en el prompt cuándo usar la herramienta. Consulta Pensamiento con uso de herramientas.

Límites de salida

Cada modelo acepta max_tokens hasta el límite indicado aquí. En la API de Message Batches, el encabezado beta output-300k-2026-03-24 eleva ese límite para los modelos que tienen un límite de lotes indicado.

Consulta la descripción general de los modelos para conocer los límites de los modelos heredados.

Solicitudes largas

El SDK requiere "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 los eventos de forma incremental, usa .stream() con .get_final_message() para obtener el objeto Message completo sin tener que ensamblarlo tú mismo a partir de eventos individuales. Consulta Streaming de mensajes. Espera tiempos de respuesta más largos cuando el pensamiento está activo, porque 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: esas solicitudes pueden durar lo suficiente como para alcanzar los tiempos de espera del sistema y los límites de conexiones abiertas.

Próximos pasos