Pensamiento extendido

El "extended thinking" (pensamiento extendido) en modo manual te da control directo sobre cuánto piensa Claude. En cada solicitud estableces un presupuesto de tokens de pensamiento con thinking: {type: "enabled", budget_tokens: N}, y Claude piensa dentro de ese presupuesto antes de comenzar su respuesta final. El modo manual sigue siendo útil cuando tu carga de trabajo requiere una "latency" (latencia) predecible o un control preciso sobre los costos de pensamiento. Esta página explica cómo establecer y ajustar el presupuesto, cómo interactúa el modo manual con el "interleaved thinking" (pensamiento intercalado) y el "prompt caching" (almacenamiento en caché de prompts), y cómo migrar al "adaptive thinking" (pensamiento adaptativo).

Para aprender cómo funciona el pensamiento en sí, consulta la descripción general del pensamiento. Allí se explican los bloques de pensamiento y la forma de la respuesta, el parámetro display, el streaming, el pensamiento con "tool use" (uso de herramientas) y el cifrado.

Modelos compatibles

La tabla de configuración por modelo indica la disponibilidad del pensamiento extendido en cada modelo, incluidos los modelos en los que el pensamiento extendido es el único modo.

Cómo usar el pensamiento extendido

Este es un ejemplo de uso del pensamiento extendido en la Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# La respuesta contiene bloques de pensamiento resumidos y bloques de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Para activar el pensamiento extendido manual, agrega un objeto thinking con type establecido en enabled y un valor de budget_tokens.

El parámetro budget_tokens establece un objetivo de cuántos tokens puede usar Claude para su proceso de razonamiento interno. Los presupuestos más grandes pueden mejorar la calidad de la respuesta, ya que permiten un análisis más exhaustivo de los problemas complejos.

Reglas y ajuste del presupuesto

budget_tokens debe cumplir estas restricciones:

• Mínimo de 1,024 tokens. La API rechaza valores más pequeños.
• Menor que max_tokens. Los tokens de pensamiento cuentan para el límite de max_tokens del turno, así que el presupuesto debe dejar espacio para la respuesta final. La única excepción es el pensamiento intercalado, donde budget_tokens puede superar max_tokens porque el presupuesto abarca todos los bloques de pensamiento dentro de un turno del asistente.
• Sin precalentamiento de caché. Como budget_tokens debe ser menor que max_tokens, el pensamiento extendido no se puede combinar con max_tokens: 0 (precalentamiento de caché).

El presupuesto es un objetivo, no un límite estricto. El uso real de tokens varía según la tarea, y Claude puede dejar de razonar mucho antes de agotar el presupuesto. max_tokens sigue siendo el límite máximo absoluto de la salida total.

Claude Opus 4.5 es el único modelo exclusivo de pensamiento extendido que admite effort. En este modelo, effort determina la respuesta en general, mientras que budget_tokens establece la profundidad del pensamiento, así que configura ambos.

Para ajustar el presupuesto:

• Adapta el punto de partida a la tarea. Para tareas simples, comienza cerca del mínimo de 1,024 tokens y auméntalo gradualmente hasta encontrar el rango óptimo para tu caso de uso. Para tareas complejas, comienza con un presupuesto más grande, de 16,000 tokens o más, y ajústalo según tus necesidades de latencia y calidad. Los presupuestos más altos permiten un razonamiento más completo, aunque con rendimientos decrecientes que dependen de la tarea y a costa de una mayor latencia. Para tareas críticas, prueba distintas configuraciones hasta encontrar el equilibrio adecuado.
• Para presupuestos de pensamiento superiores a 32k, usa el procesamiento por lotes para evitar problemas de red. Si haces que el modelo piense más allá de 32k tokens, las solicitudes tardan mucho y pueden alcanzar los tiempos de espera del sistema y los límites de conexiones abiertas.

Para saber cuánto te cuesta realmente un presupuesto, supervisa el campo usage.output_tokens_details.thinking_tokens de la respuesta. Este campo indica cuántos de los tokens de salida facturados correspondieron a razonamiento interno. Con streaming, este desglose solo aparece en el evento final message_delta.

Cuando estés listo para dejar los presupuestos manuales, consulta Migrar al pensamiento adaptativo.

Pensamiento intercalado en modo manual

El pensamiento intercalado permite que Claude piense entre llamadas a herramientas dentro de un mismo turno del asistente y razone sobre cada resultado de herramienta antes de decidir qué hacer a continuación. Para conocer el concepto, la estructura del turno y su comportamiento en los modelos con pensamiento adaptativo, consulta pensamiento intercalado en la descripción general del pensamiento. Esta sección explica cómo habilitarlo cuando usas el pensamiento manual type: "enabled".

En Claude Opus 4.5, Claude Sonnet 4.5 y los modelos Claude 4 anteriores, agrega el encabezado beta interleaved-thinking-2025-05-14 a tu solicitud de API.

En la generación 4.6, el modo manual se comporta de forma distinta según el modelo:

• Claude Sonnet 4.6: el encabezado beta con type: "enabled" manual todavía funciona, pero está obsoleto. Es preferible usar el pensamiento adaptativo, que intercala automáticamente sin necesidad del encabezado.
• Claude Opus 4.6: el modo manual no admite pensamiento intercalado. Solo su modo adaptativo intercala, así que cambia a thinking: {type: "adaptive"} si necesitas razonamiento entre llamadas a herramientas en este modelo.

Claude Haiku 4.5 no admite pensamiento intercalado. En la Claude API, el encabezado beta se acepta, pero se ignora.

Ten en cuenta dos consideraciones más sobre el pensamiento intercalado en modo manual:

• Aquí budget_tokens puede superar max_tokens. Las reglas del presupuesto explican esta excepción.
• El pensamiento intercalado solo es compatible con las herramientas usadas a través de la Messages API.

Cada plataforma trata el encabezado beta de forma distinta. La Claude API y Claude Platform on AWS aceptan interleaved-thinking-2025-05-14 en cualquier modelo y lo ignoran donde no es compatible. Que se acepte no significa que tenga efecto. En los modelos que rechazan type: "enabled" (4.7 y posteriores) o que no intercalan en modo manual (Claude Opus 4.6), el encabezado no tiene efecto en modo manual. En esos modelos, el pensamiento adaptativo intercala automáticamente.

Las plataformas operadas por socios (Amazon Bedrock y Google Cloud) también aceptan el encabezado en cualquier modelo sin devolver un error, y lo ignoran en los modelos que no admiten pensamiento intercalado.

Estructura del turno en modo manual

Las reglas generales de estructura del turno se encuentran en Pensamiento con uso de herramientas. Allí se explican el bucle de uso de herramientas en un solo turno, el manejo de conflictos a mitad del turno y la activación o desactivación del pensamiento entre turnos.

El modo manual agrega un requisito: el turno final del asistente en una solicitud con pensamiento habilitado debe comenzar con un bloque de pensamiento (el pensamiento adaptativo elimina ese requisito). Además, cambiar la configuración del pensamiento entre turnos invalida el almacenamiento en caché de prompts, como se explica en la siguiente sección.

Almacenamiento en caché de prompts en modo manual

El modo manual agrega una regla al comportamiento de almacenamiento en caché común a ambos modos, descrito en pensamiento y almacenamiento en caché de prompts. Cambiar budget_tokens entre solicitudes invalida los puntos de interrupción de caché, igual que cambiar de modo de pensamiento, porque el valor del presupuesto se incluye en el prompt. Los puntos de interrupción a nivel de mensaje siempre fallan después de un cambio de presupuesto. Que también fallen los puntos de interrupción de herramientas y de la indicación del sistema depende de dónde incluya el modelo la configuración.

En la práctica, elige un presupuesto y mantenlo estable durante toda la conversación almacenada en caché. Por ejemplo, en una conversación de varios turnos con almacenamiento en caché a nivel de mensaje en Claude Sonnet 4.6, cambiar el presupuesto de 4,000 a 8,000 tokens en la tercera solicitud muestra la invalidación directamente:

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

La tercera solicitud vuelve a crear la caché (cache_creation_input_tokens=1370, cache_read_input_tokens=0) porque el presupuesto cambió entre solicitudes. En el modo adaptativo, el nivel de effort cumple en la caché el papel que aquí cumple budget_tokens. Para ver una versión ejecutable del mismo experimento en ese modo, consulta Almacenamiento en caché de prompts en la página sobre cómo dirigir el pensamiento.

Mecánicas compartidas

La mayor parte del comportamiento del pensamiento es común a ambos modos y se documenta una sola vez en la página de Pensamiento. Todo lo que se describe allí también se aplica al modo manual:

• Controlar la visualización del pensamiento
• Streaming del pensamiento
• Pensamiento con uso de herramientas, incluida la preservación de bloques de pensamiento
• Pensamiento y almacenamiento en caché de prompts
• Pensamiento y la ventana de contexto
• Cifrado del pensamiento
• Precios (en la página Dirigir el pensamiento)

Migrar al pensamiento adaptativo

Algunos modelos solo admiten pensamiento extendido: Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 y los modelos Claude 4 anteriores. Si usas uno de ellos, no necesitas hacer nada por ahora. El pensamiento adaptativo no está disponible en esos modelos, y type: "adaptive" devuelve un error 400. Mantén budget_tokens hasta que pases a un modelo que admita pensamiento adaptativo y, entonces, aplica la correspondencia que se indica a continuación.

Necesitas dejar de usar type: "enabled" si:

• Usas Claude Opus 4.6 o Claude Sonnet 4.6, donde budget_tokens está obsoleto.
• Usas Claude 4.7 o un modelo posterior, como Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5 o Claude Fable 5.1, donde type: "enabled" devuelve un error 400.

La correspondencia es sencilla: elimina budget_tokens, establece thinking: {type: "adaptive"} y controla la profundidad del razonamiento con output_config: {effort: ...} en lugar de un presupuesto de tokens.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

se convierte en:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high" coincide con el valor predeterminado de la API. Aparece aquí solo para mostrar dónde se controla ahora la profundidad, y omitirlo produce exactamente el mismo comportamiento.

Espera una diferencia de comportamiento, no solo un cambio de sintaxis. Con un presupuesto fijo, Claude piensa en cada solicitud. Con el pensamiento adaptativo, Claude decide si piensa y cuánto en cada solicitud, y con niveles de effort más bajos puede omitir el pensamiento por completo en entradas sencillas. También puedes eliminar el encabezado beta interleaved-thinking-2025-05-14 después de migrar: el pensamiento adaptativo intercala automáticamente, y la Claude API ignora el encabezado en estos modelos. La preservación de bloques de pensamiento también cambia: Claude Opus 4.5 y los modelos numerados 4.6 y superiores mantienen en el contexto los bloques de pensamiento de turnos anteriores y los facturan como entrada, mientras que Claude Sonnet 4.5, Claude Haiku 4.5 y los modelos anteriores los eliminaban; consulta preservación de bloques de pensamiento por modelo.

Cambiar de modo es un cambio en la configuración del pensamiento. Por eso, la primera solicitud después del cambio invalida los puntos de interrupción de caché, como se describe en Almacenamiento en caché de prompts en modo manual.

Para obtener orientación completa, consulta pensamiento adaptativo, effort y la guía de migración de modelos.

Próximos pasos