Pensamiento extendido

El "extended thinking" (pensamiento extendido) en modo manual te da control directo sobre cuánto piensa Claude. Estableces un presupuesto de tokens de pensamiento en cada solicitud 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 latencia predecible o un control preciso sobre los costos de pensamiento. Esta página cubre cómo establecer y ajustar el presupuesto, cómo interactúa el modo manual con el pensamiento intercalado y el "prompt caching" (almacenamiento en caché de prompts), y cómo migrar al pensamiento adaptativo.

Para aprender cómo funciona el pensamiento en sí, incluidos 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, consulta la descripción general del pensamiento.

Modelos compatibles

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

Cómo usar el pensamiento extendido

Aquí hay 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 al permitir un análisis más exhaustivo para problemas complejos.

Reglas y ajuste del presupuesto

budget_tokens debe cumplir estas restricciones:

• Mínimo de 1,024 tokens. La API rechaza valores menores.
• Menor que max_tokens. Los tokens de pensamiento cuentan para el límite de max_tokens del turno, por lo que el presupuesto debe dejar espacio para la respuesta final. La única excepción es el pensamiento intercalado, donde budget_tokens puede exceder max_tokens porque el presupuesto abarca todos los bloques de pensamiento dentro de un turno del asistente.
• Sin precalentamiento de caché. Dado que budget_tokens debe ser menor que max_tokens, el pensamiento extendido no puede combinarse con max_tokens: 0 (precalentamiento de la caché).

El presupuesto es un objetivo más que 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 techo estricto de la salida total.

En Claude Opus 4.5, el único modelo exclusivo de pensamiento extendido que admite effort, effort da forma a la respuesta general mientras que budget_tokens establece la profundidad del pensamiento; establece 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 aumenta de forma incremental para encontrar el rango óptimo para tu caso de uso. Para tareas complejas, comienza con un presupuesto mayor 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, con rendimientos decrecientes que dependen de la tarea, y a costa de una mayor latencia. Para tareas críticas, prueba diferentes configuraciones para encontrar el equilibrio adecuado.
• Para presupuestos de pensamiento superiores a 32k, usa el procesamiento por lotes para evitar problemas de red. Forzar al modelo a pensar más allá de 32k tokens produce solicitudes de larga duración que pueden alcanzar los tiempos de espera del sistema y los límites de conexiones abiertas.

Para hacer seguimiento de lo que realmente te cuesta un presupuesto, monitorea el campo usage.output_tokens_details.thinking_tokens en la respuesta, que informa cuántos de los tokens de salida facturados fueron razonamiento interno. Al usar streaming, este desglose aparece solo en el evento final message_delta.

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

Pensamiento intercalado en modo manual

El "interleaved thinking" (pensamiento intercalado) permite a Claude pensar entre llamadas a herramientas dentro de un solo turno del asistente, razonando sobre cada resultado de herramienta antes de decidir qué hacer a continuación. Para el concepto, la estructura de turnos y cómo se comporta en modelos de pensamiento adaptativo, consulta pensamiento intercalado en la descripción general del pensamiento. Esta sección cubre cómo habilitarlo cuando usas el pensamiento manual type: "enabled".

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

La generación 4.6 se divide en modo manual:

• Claude Sonnet 4.6: el encabezado beta con type: "enabled" manual sigue siendo funcional pero está obsoleto. Prefiere el pensamiento adaptativo, que intercala automáticamente sin encabezado.
• Claude Opus 4.6: el modo manual no tiene pensamiento intercalado en absoluto. 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.

Dos consideraciones más para el pensamiento intercalado en modo manual:

• budget_tokens puede exceder max_tokens aquí; las reglas del presupuesto explican esta excepción.
• El pensamiento intercalado solo se admite para herramientas usadas a través de la Messages API.

La forma en que las plataformas tratan el encabezado beta difiere. La Claude API y Claude Platform en AWS aceptan interleaved-thinking-2025-05-14 en cualquier modelo y lo ignoran donde no se admite. La aceptación no es lo mismo que el efecto: en modelos que rechazan type: "enabled" (4.7 y posteriores) o que carecen de intercalado en modo manual (Claude Opus 4.6), el encabezado no tiene efecto en modo manual; allí el pensamiento adaptativo intercala automáticamente.

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

Estructura de turnos en modo manual

Las reglas generales de estructura de turnos, incluido el bucle de uso de herramientas de un solo turno, el manejo de conflictos a mitad de turno y la alternancia del pensamiento entre turnos, están en Pensamiento con uso de herramientas.

El modo manual agrega un requisito: el turno final del asistente de una solicitud con pensamiento habilitado debe comenzar con un bloque de pensamiento (el pensamiento adaptativo elimina ese requisito). Cambiar la configuración de pensamiento entre turnos también invalida el almacenamiento en caché de prompts; consulta la siguiente sección.

Almacenamiento en caché de prompts en modo manual

El modo manual agrega una regla además del comportamiento de caché neutral al modo 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 representa dentro del prompt. Los puntos de interrupción a nivel de mensaje siempre fallan después de un cambio de presupuesto; si los puntos de interrupción de herramientas y de la indicación del sistema también fallan depende de dónde el modelo representa la configuración.

En la práctica, elige un presupuesto y mantenlo estable durante la vida de una conversación en caché. Ejecutar una conversación de varios turnos con caché a nivel de mensaje en Claude Sonnet 4.6 y cambiar el presupuesto en la tercera solicitud de 4,000 a 8,000 tokens 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. Para una versión ejecutable del mismo experimento en modo adaptativo, donde el nivel de effort desempeña el papel de caché que budget_tokens desempeña aquí, consulta Almacenamiento en caché de prompts en la página de dirección del pensamiento.

Mecánicas compartidas

La mayor parte del comportamiento del pensamiento es neutral al modo y está documentada una sola vez en la página Pensamiento. Todo lo que hay allí también aplica en modo manual:

• Control de 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 Dirección del pensamiento)

Migración al pensamiento adaptativo

Si tu modelo solo admite pensamiento extendido (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 y modelos Claude 4 anteriores), no se necesita ninguna acción ahora: el pensamiento adaptativo no está disponible allí, y type: "adaptive" devuelve un error 400. Mantén budget_tokens hasta que pases a un modelo que admita pensamiento adaptativo, y luego aplica la correspondencia que sigue.

Necesitas migrar fuera de type: "enabled" si:

• Usas Claude Opus 4.6 o Claude Sonnet 4.6, donde budget_tokens está obsoleto.
• Estás pasando a Claude Opus 4.7, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 o Claude Mythos 5, donde type: "enabled" devuelve un error 400.

La correspondencia es pequeña: 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 vive ahora el control de profundidad, y omitirlo produce un comportamiento idéntico.

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 pensar y cuánto en cada solicitud, y en configuraciones de effort más bajas puede omitir el pensamiento por completo en entradas fáciles. 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 los bloques de pensamiento de turnos anteriores en el contexto y los facturan como entrada, mientras que Claude Sonnet 4.5, Claude Haiku 4.5 y modelos anteriores los eliminaban; consulta preservación de bloques de pensamiento por modelo.

Cambiar de modo es un cambio de configuración de pensamiento, por lo que 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 una guía completa, consulta pensamiento adaptativo, effort y la guía de migración de modelos.

Próximos pasos