Pensamiento adaptativo

El pensamiento adaptativo es la forma recomendada de usar el pensamiento extendido con Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6. En Claude Fable 5 y Claude Mythos 5, el pensamiento siempre está habilitado y no se puede deshabilitar; el pensamiento adaptativo es el único modo de pensamiento. En Claude Mythos Preview, el pensamiento adaptativo es el modo predeterminado y se aplica automáticamente siempre que thinking no esté configurado. En lugar de establecer manualmente un presupuesto de tokens de pensamiento, el pensamiento adaptativo permite que Claude determine dinámicamente cuándo y cuánto usar el pensamiento extendido según la complejidad de cada solicitud. En Claude Opus 4.8 y Claude Opus 4.7, el pensamiento adaptativo es el único modo de pensamiento admitido; el modo manual thinking: {type: "enabled", budget_tokens: N} ya no se acepta.



Modelos compatibles

El pensamiento adaptativo es compatible con los siguientes modelos:

• Claude Fable 5 (claude-fable-5) y Claude Mythos 5 (claude-mythos-5), el pensamiento adaptativo siempre está activado; thinking: {type: "disabled"} no es compatible
• Claude Mythos Preview (claude-mythos-preview), el pensamiento adaptativo es el predeterminado; thinking: {type: "disabled"} no es compatible
• Claude Opus 4.8 (claude-opus-4-8), el pensamiento adaptativo es el único modo de pensamiento admitido. El pensamiento está desactivado a menos que establezcas explícitamente thinking: {type: "adaptive"} en tu solicitud; el modo manual thinking: {type: "enabled"} se rechaza con un error 400.
• Claude Opus 4.7 (claude-opus-4-7), el pensamiento adaptativo es el único modo de pensamiento admitido. El pensamiento está desactivado a menos que establezcas explícitamente thinking: {type: "adaptive"} en tu solicitud; el modo manual thinking: {type: "enabled"} se rechaza con un error 400.
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 4.6 (claude-sonnet-4-6)



Cómo funciona el pensamiento adaptativo

En el modo adaptativo, el pensamiento es opcional para el modelo. Claude evalúa la complejidad de cada solicitud y determina si usar el pensamiento extendido y en qué medida. En el nivel de esfuerzo predeterminado (high), Claude casi siempre piensa. En niveles de esfuerzo más bajos, Claude puede omitir el pensamiento para problemas más simples.

El pensamiento adaptativo también habilita automáticamente el pensamiento intercalado. Esto significa que Claude puede pensar entre llamadas a herramientas, lo que lo hace especialmente efectivo para flujos de trabajo agénticos.



Cómo usar el pensamiento adaptativo

Establece thinking.type en "adaptive" en tu solicitud de API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

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



Pensamiento adaptativo con el parámetro effort

Puedes combinar el pensamiento adaptativo con el parámetro effort para guiar cuánto pensamiento realiza Claude. El nivel de esfuerzo actúa como una guía flexible para la asignación de pensamiento de Claude:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)



Streaming con pensamiento adaptativo

El pensamiento adaptativo funciona sin problemas con streaming. Los bloques de pensamiento se transmiten mediante eventos thinking_delta al igual que en el modo de pensamiento manual:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    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)



Pensamiento adaptativo vs. manual vs. deshabilitado



Consideraciones importantes



Cambios en la validación

Al usar el pensamiento adaptativo, los turnos anteriores del asistente no necesitan comenzar con bloques de pensamiento. Esto es más flexible que el modo manual, donde la API exige que los turnos con pensamiento habilitado comiencen con un bloque de pensamiento.



Almacenamiento en caché de prompts

Las solicitudes consecutivas que usan pensamiento adaptive preservan los puntos de interrupción del almacenamiento en caché de prompts. Sin embargo, cambiar entre los modos de pensamiento adaptive y enabled/disabled rompe los puntos de interrupción de caché para los mensajes. Las indicaciones del sistema y las definiciones de herramientas permanecen en caché independientemente de los cambios de modo.



Ajustar el comportamiento del pensamiento

El comportamiento de activación del pensamiento adaptativo se puede guiar mediante prompts. Si Claude está pensando con más o menos frecuencia de lo que te gustaría, puedes agregar orientación a tu indicación del sistema:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality — typically for problems
that require multi-step reasoning. When in doubt, respond directly.

Para fomentar el pensamiento en su lugar, usa una frase como:

This task involves multi-step reasoning. Think carefully before responding.

La efectividad de la orientación puede ser sensible a la redacción exacta: si una formulación no produce el comportamiento que deseas, prueba una variante más directa.

También puedes orientar el pensamiento por mensaje desde el turno del usuario. Agregar "Please think hard before responding." a un mensaje de usuario anima a Claude a pensar en ese turno; "Answer directly without deliberating." lo suprime. Esto funciona independientemente de la indicación del sistema y es útil cuando solo algunas solicitudes en una conversación justifican un razonamiento extendido.



Control de costos

Usa max_tokens como límite estricto en la salida total (pensamiento + texto de respuesta). El parámetro effort proporciona orientación flexible adicional sobre cuánto pensamiento asigna Claude. Juntos, estos te dan un control efectivo sobre el costo.

En los niveles de esfuerzo high y max, Claude puede pensar más extensamente y es más probable que agote el presupuesto de max_tokens. Si observas stop_reason: "max_tokens" en las respuestas, considera aumentar max_tokens para darle al modelo más margen, o reducir el nivel de esfuerzo.



Trabajar con bloques de pensamiento

Los siguientes conceptos se aplican a todos los modelos que admiten pensamiento extendido, independientemente de si usas el modo adaptativo o manual.



Pensamiento resumido

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

Estas son algunas consideraciones importantes sobre el pensamiento resumido:

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



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. Acepta dos valores:

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

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

Estas son algunas consideraciones importantes sobre el pensamiento omitido:

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

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Para ejemplos de código y comportamiento de streaming con display: "omitted", consulta Controlar la visualización del pensamiento en la página de pensamiento extendido. Los ejemplos allí usan type: "enabled"; con pensamiento adaptativo, usa:

thinking = {"type": "adaptive", "display": "omitted"}



Cifrado del pensamiento

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

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

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



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 de pensamiento que recibes son bloques thinking regulares, no redacted_thinking, y thinking.display funciona igual que en otros modelos: "summarized" devuelve un resumen legible del razonamiento, y con "omitted" (el valor predeterminado en estos modelos), las respuestas siguen incluyendo bloques thinking, pero el campo thinking es una cadena vacía. Para la estructura de respuesta de los bloques de pensamiento, consulta la referencia de la API de Messages.

Al continuar una conversación en el mismo modelo, pasa cada bloque de pensamiento de vuelta 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 ha sido modificado, no los bloques que has leído.

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 sumando tokens de entrada, así que cuando cambies de modelo, por ejemplo después de un fallback por rechazo del clasificador, elimina los bloques thinking y redacted_thinking de los turnos anteriores del asistente. Las excepciones, cubiertas en Crédito de fallback, son los reintentos con crédito de fallback (que deben repetir el cuerpo de la solicitud rechazada sin cambios) y los bloques fallback de un fallback a mitad de salida (que permanecen donde aparecieron).

En Claude Fable 5, una solicitud que intenta obtener el razonamiento interno del modelo como parte del texto de respuesta puede ser rechazada con stop_details.category: "reasoning_extraction". Las aplicaciones que necesitan visibilidad del razonamiento deben leer los bloques thinking descritos en esta sección en lugar de solicitar el razonamiento en la respuesta. Consulta Categorías de rechazo para la referencia de campos y orientación de manejo.



Precios

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

El proceso de pensamiento genera cargos por:

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

Al usar pensamiento resumido:

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

Al usar display: "omitted":

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

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

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

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



Temas adicionales

La página de pensamiento extendido cubre varios temas con más detalle con ejemplos de código específicos por modo:

• Uso de herramientas con pensamiento: Las mismas reglas se aplican para el pensamiento adaptativo: preserva los bloques de pensamiento entre llamadas a herramientas y ten en cuenta las limitaciones de tool_choice cuando el pensamiento está activo.
• Almacenamiento en caché de prompts: Con el pensamiento adaptativo, las solicitudes consecutivas que usan el mismo modo de pensamiento preservan los puntos de interrupción de caché. Cambiar entre los modos adaptive y enabled/disabled rompe los puntos de interrupción de caché para los mensajes (las indicaciones del sistema y las definiciones de herramientas permanecen en caché).
• Ventanas de contexto: Cómo interactúan los tokens de pensamiento con max_tokens y los límites de la ventana de contexto.



Próximos pasos