Extended Thinking: razonamiento profundo

Módulo: 9. Funciones avanzadas | Tiempo: ~25 min de teoría + 30 min de práctica

Lo esencial

Antes de una jugada difícil, un ajedrecista piensa 5 minutos: repasa variantes, calcula consecuencias, descarta los malos caminos. Extended Thinking (pensamiento extendido, el modo de análisis profundo de Claude) es lo mismo para Claude: "piensa en voz alta" antes de responder, en lugar de soltar lo primero que se le ocurre. Para tareas sencillas sobra. Para decisiones de arquitectura y análisis complejos, la diferencia de calidad es de fondo.

Términos de la lección: extended thinking (pensamiento extendido, el modo de análisis profundo de Claude), API (interfaz de programación), token (una unidad de texto para la IA), prompt (la solicitud a la IA), prompt caching (caché de prompts: guardar un prompt para reutilizarlo sin volver a pagarlo completo).

Conceptos clave

• Extended Thinking: un modo de la API en el que Claude genera un monólogo interno antes de la respuesta final
• Thinking tokens: los tokens del razonamiento interno; van en un bloque aparte thinking
• budget_tokens: el parámetro que limita el máximo de tokens para razonar (modo manual, solo para modelos antiguos: en 4.6 está obsoleto, en 4.7 y posteriores devuelve un error 400)
• Adaptive Thinking: el modo automático ("type": "adaptive"): el modelo decide por sí mismo si piensa y qué tan a fondo. La profundidad se fija con el parámetro effort dentro de output_config. Es la forma principal para todos los modelos actuales (a octubre de 2026: Opus 5.5, Sonnet 5.5, Fable 5.1)
• display: el parámetro de visualización: "summarized" (un resumen del razonamiento) u "omitted" (solo la firma, sin texto). En Opus 5.5, Sonnet 5.5 y Fable 5.1 el valor por defecto es "omitted"
• Interleaved Thinking: razonamiento entre cada llamada a una herramienta (tool call), no solo al principio
• Thinking block: un bloque aparte en la respuesta de la API con los campos type: "thinking", thinking: "..." y signature: "..."
• Costo: los thinking tokens se cobran como output tokens (más caros que los de input). Se cobran los thinking tokens completos, aunque display = "summarized"

Teoría

Cómo funciona por dentro

🎨 Imagínalo así: sin Extended Thinking, Claude responde como un concursante de un programa de preguntas: aprieta el botón antes de que termine la pregunta y suelta la primera respuesta. Con Extended Thinking, como un ajedrecista: mira el tablero, calcula variantes, descarta las malas jugadas y luego mueve la pieza.

Sin Extended Thinking, Claude recibe la solicitud y genera la respuesta de inmediato. Es rápido, pero el pensamiento es "plano": el modelo no alcanza a revisar alternativas.

Con Extended Thinking, la solicitud pasa por dos etapas:

Solicitud → [Thinking phase: Claude repasa variantes] → Respuesta final

La thinking phase es invisible por defecto: solo ves la respuesta final. Por la API puedes obtener un resumen del monólogo interno (el razonamiento en bruto no se entrega con ninguna configuración).

Qué hay de nuevo a octubre de 2026: en los modelos actuales (Opus 5.5, Sonnet 5.5, Fable 5.1) el razonamiento ya viene activado por defecto, y la forma estándar de apagarlo (thinking: {"type": "disabled"}) devuelve un error 400. Por eso la tarea del desarrollador cambió: ya no es "activar el thinking", sino "elegir la profundidad" (effort) y decidir si se muestra el texto del razonamiento. El viejo modo manual con budget_tokens solo hace falta para modelos obsoletos.

Dos modos: Manual vs. Adaptive

La API tiene dos formas de controlar el razonamiento:

1. Manual (presupuesto a mano): tú fijas el límite de tokens. Solo funciona en modelos obsoletos:

thinking={"type": "enabled", "budget_tokens": 10000}

2. Adaptive (automático): el modelo decide cuánto pensar, y la profundidad la fijas con el parámetro effort, aparte de thinking:

thinking={"type": "adaptive"},
output_config={"effort": "medium"}  # low / medium / high y más, según el modelo

🎨 Imagínalo así: Manual es decirle al ajedrecista "piensa exactamente 5 minutos". Adaptive es decirle "piénsalo con calma media" y él decide cuánto necesita para esa posición concreta.

Qué modelos admiten qué

Los modelos más antiguos se van retirando de la API poco a poco; la lista vigente está en Lo vigente.

Tendencia: Anthropic se movió hacia Adaptive. Para proyectos nuevos usa "adaptive" y effort.

Solicitud a la API con Extended Thinking (Manual, para modelos obsoletos)

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-haiku-4-5",  # modo manual: solo para modelos obsoletos; en Haiku 4.5 es el único modo
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000  # hasta 10000 tokens para razonar
    },
    messages=[{
        "role": "user",
        "content": """Diseña la arquitectura de un sistema para este caso:
        - Plataforma SaaS para pequeños negocios
        - 1000 usuarios activos
        - Necesita multi-tenancy (varios clientes en la misma plataforma)
        - Presupuesto: $200/mes de infraestructura
        - Equipo: 1 desarrollador
        
        Evalúa al menos 3 enfoques con sus pros y contras reales."""
    }]
)

# Revisamos los bloques de la respuesta
for block in response.content:
    if block.type == "thinking":
        print("=== RAZONAMIENTO INTERNO ===")
        print(block.thinking)
        print()
    elif block.type == "text":
        print("=== RESPUESTA FINAL ===")
        print(block.text)

Solicitud a la API con Adaptive Thinking (recomendado para modelos nuevos)

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "display": "summarized"  # para ver el resumen del razonamiento
    },
    output_config={"effort": "high"},  # profundidad del trabajo: low, medium, high y más (según el modelo)
    messages=[{
        "role": "user",
        "content": "Diseña la arquitectura de una plataforma SaaS con multi-tenancy..."
    }]
)

Con Adaptive no tienes que adivinar el budget_tokens: el modelo decide la profundidad del razonamiento y tú solo mueves el effort. Recuerda: con un effort bajo, el modelo puede saltarse el razonamiento por completo en una solicitud sencilla. Si el SDK se queja de output_config, actualiza la biblioteca: pip install -U anthropic.

Qué se ve en el bloque thinking

Un ejemplo de monólogo interno real (abreviado):

Mmm, hay que diseñar la arquitectura de un SaaS con presupuesto limitado...

Opción 1: Shared database schema
- Pros: sencillo, barato, una sola base
- Contras: difícil aislar los datos de los clientes, riesgos al crecer
- Para 1000 usuarios va bien, ¿pero y si crece a 10000?

Opción 2: Database per tenant
- Pros: aislamiento total, fácil revertir a un solo cliente
- Contras: $200/mes no alcanzan si 1000 clientes = 1000 bases
- La descarto con este presupuesto

Opción 3: Schema per tenant (Postgres schemas)
- Punto medio: aislamiento sin que se disparen las bases
- Row Level Security añade otra capa
- Cloudflare Workers + PlanetScale serverless = cabe en $200/mes

Recomendaré la Opción 3 como principal, explicando cuándo pasar a la Opción 2...

No es un escaparate para lucirse: es el proceso real de repasar opciones.

🎨 Imagínalo así: budget_tokens es como el límite de tiempo de una junta. 1000 tokens, una lluvia de ideas rápida; 10 000, un análisis estratégico completo. Más tiempo = análisis más profundo, pero también más caro. En el modo adaptive, el papel de ese límite lo juega effort.

El parámetro budget_tokens (modo Manual)

Cálculo: tokens de razonamiento × precio del token de output. El ejemplo usa un precio de $5 por 1 millón de tokens de output (a octubre de 2026, lo que cuesta Haiku 4.5: en ella el modo manual todavía funciona, y podría retirarse de la API no antes del 15.10.2026); los thinking tokens se cuentan como output. Cada modelo tiene su precio: precios y versiones vigentes: Lo vigente. El gasto real lo ves en el campo usage.output_tokens_details.thinking_tokens de la respuesta.

Limitaciones: budget_tokens no puede ser menor a 1024 y debe ser menor que max_tokens (salvo con interleaved thinking, donde puede ser mayor). El presupuesto es una referencia, no un techo estricto: el modelo puede detenerse antes; el techo estricto lo pone max_tokens. Para presupuestos de más de 32 000 tokens, la documentación recomienda la Batch API: esas solicitudes tardan mucho y chocan con los tiempos de espera.

El parámetro display: qué ve el usuario

Controla qué se devuelve en el bloque thinking de la respuesta:

El nombre del campo es el mismo en ambos modos. El texto del bloque siempre es un resumen, no el razonamiento en bruto.

# Modo para producción: más rápido, sin datos de más
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "display": "omitted"  # ← solo la firma, sin el texto del razonamiento
    },
    messages=[{"role": "user", "content": "..."}]
)

Importante: con "omitted" de todos modos pagas todos los thinking tokens. El ahorro no es de dinero, sino del tiempo en que llega la respuesta. Cuando devuelvas los bloques thinking en una conversación de varios turnos (con herramientas es obligatorio), devuélvelos sin cambios: con el campo signature el servidor recupera el contexto completo del razonamiento.

Streaming de thinking tokens

Para razonamientos largos conviene hacer streaming: así ves el avance:

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "display": "summarized"
    },
    messages=[{"role": "user", "content": "...tu solicitud compleja..."}]
) as stream:
    for event in stream:
        if event.type == 'content_block_start':
            if event.content_block.type == 'thinking':
                print("[Empiezo a pensar...]")
        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)
        elif event.type == 'content_block_stop':
            print("\n[Bloque terminado]")

En el streaming llegan tres tipos de eventos delta (con display: "omitted", thinking_delta llega con una cadena vacía, sin texto del razonamiento):

• thinking_delta: el texto del razonamiento (en pedazos)
• signature_delta: la firma criptográfica (para varios turnos)
• text_delta: la respuesta final

Cuándo hace falta Extended Thinking

Úsalo para:

• Decisiones de arquitectura (elegir tecnologías, la estructura del sistema)
• Problemas matemáticos de varios pasos
• Analizar compensaciones complejas con varias variables
• Depurar bugs difíciles cuya causa no es obvia
• Escribir algoritmos críticos

No lo uses para:

• Escribir un texto sencillo o un resumen breve
• Llamadas comunes a la API y código sencillo
• Tareas donde la primera respuesta ya es correcta
• Cuando necesitas velocidad y el precio importa

🎨 Imagínalo así: el ajedrez "bullet" contra el "clásico". En bullet juegas en 1 minuto: rápido, superficial. En el clásico piensas 20 minutos por jugada. Extended Thinking es el clásico. Para una partida rápida no hace falta.

Interleaved Thinking: razonar entre tool calls

🎨 Imagínalo así: Interleaved Thinking es como un cocinero que prueba el platillo después de cada paso. Le puso sal, probó, decidió qué sigue. Le puso especias, probó otra vez. No cocina todo a ciegas hasta el final.

Cuando Claude usa herramientas (tools), puede pensar después de cada llamada a una herramienta, no solo al principio. Eso se llama Interleaved Thinking.

Solicitud → [Thinking] → tool_use: get_weather("Bogotá")
       → tool_result: "14°C"
       → [Thinking: "Ok, en Bogotá hace fresco, hay que tomarlo en cuenta..."]  ← piensa ENTRE llamadas
       → tool_use: get_weather("Cartagena")
       → tool_result: "+31°C"
       → [Thinking: "Cartagena está más caliente, comparo..."]
       → Respuesta final

Soporte por modelo (a octubre de 2026):

• Opus 5.5, Sonnet 5.5, Fable 5.1, y también Opus 4.8 y 4.7: interleaved automático en modo adaptive, sin encabezado
• Opus 4.6: solo en modo adaptive (en manual no existe)
• Sonnet 4.6: automático en modo adaptive; en manual todavía funciona con el encabezado beta interleaved-thinking-2025-05-14, pero está deprecated
• Opus 4.5, Sonnet 4.5 y otros Claude 4: con el encabezado beta interleaved-thinking-2025-05-14
• Haiku 4.5: no lo admite

Importante al trabajar con tools: cuando devuelvas el tool_result, siempre manda todos los bloques thinking de la respuesta anterior del assistant: no los modifiques ni los quites.

Ejemplo: con thinking vs. sin él

🎨 Imagínalo así: sin Extended Thinking, es el consejo de alguien que pasa por la calle: "usa PostgreSQL, todos lo usan". Con Extended Thinking, es la consulta con un arquitecto que pasó una hora estudiando tu carga, tu presupuesto y tu equipo.

Sin Extended Thinking, la solicitud: "Elige una base de datos para mi SaaS"

La respuesta llega en 2-3 segundos. Lo más probable es que recomiende PostgreSQL o MongoDB con argumentos de cajón.

Con Extended Thinking (adaptive, effort high; en el viejo modo manual, budget_tokens: 8000):

Claude dedicará bastante más tiempo al análisis (del orden de decenas de segundos, según el modelo y la carga). En el bloque thinking se verá cómo revisa tus parámetros concretos, compara el costo de distintas bases de datos en la nube con una carga de 1000 usuarios, toma en cuenta que tienes un solo desarrollador y sopesa PlanetScale vs. Supabase vs. Neon con criterios reales.

La calidad de la respuesta es claramente mayor: no porque el modelo sea "más listo", sino porque tuvo tiempo de pensar.

Limitaciones de Extended Thinking

No todas las funciones de la API son compatibles con Extended Thinking:

Varios turnos: devuelve los bloques thinking

🎨 Imagínalo así: los bloques thinking en una conversación de varios turnos son como pasarle al ajedrecista su libreta de notas para la siguiente jugada. Sin notas, olvidaría qué variantes ya descartó y por qué. Con ellas, sigue desde donde se quedó.

En las conversaciones de varios turnos, devuelve sin cambios todos los bloques thinking de las respuestas anteriores del assistant: dentro de un ciclo con herramientas es obligatorio, y en una conversación normal es lo recomendado. Si no, el modelo puede perder el contexto de su razonamiento:

# Turno 1
response1 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "¿Primera pregunta?"}],
)

# Turno 2: devuelve response1.content completo (con los bloques thinking), sin cambios
response2 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {"role": "user", "content": "¿Primera pregunta?"},
        {"role": "assistant", "content": response1.content},  # ← TODOS los bloques
        {"role": "user", "content": "¿Pregunta de seguimiento?"},
    ],
)

Práctica

Tarea: una decisión de arquitectura con Extended Thinking

1. Elige una tarea de arquitectura real de tu proyecto (o toma una didáctica: "¿Cómo guardo los datos de usuarios de un SaaS con 500 clientes?")

2. Primero pide la respuesta sin Extended Thinking y guárdala:

   response_basic = client.messages.create(
       model="claude-haiku-4-5",  # para comparar: un modelo que por defecto no razona
       max_tokens=2000,
       messages=[{"role": "user", "content": TU_SOLICITUD}]
   )

3. Luego la misma solicitud con Extended Thinking (Manual: en Haiku 4.5 es el único modo de razonamiento):

   response_thinking = client.messages.create(
       model="claude-haiku-4-5",
       max_tokens=8000,
       thinking={"type": "enabled", "budget_tokens": 6000},
       messages=[{"role": "user", "content": TU_SOLICITUD}]
   )

4. Y la misma solicitud con Adaptive Thinking (un modelo actual, por ejemplo Opus 5.5):

   response_adaptive = client.messages.create(
       model="claude-opus-5-5",
       max_tokens=8000,
       thinking={"type": "adaptive", "display": "summarized"},
       output_config={"effort": "high"},
       messages=[{"role": "user", "content": TU_SOLICITUD}]
   )

5. Imprime todas las respuestas finales y los bloques thinking

6. Compara: ¿dónde hay un análisis más profundo? ¿Qué se le escapó a la respuesta "rápida"?

7. Calcula el costo de todas las opciones con response.usage

Meta: sentir la diferencia de calidad y entender en qué tareas se justifica pagar de más.

Herramientas y recursos

• Documentación de la API de Anthropic: Extended Thinking y Thinking
• Python SDK: pip install -U anthropic (usa una versión reciente: los parámetros output_config y display llegaron hace poco)
• En Claude Code: el nivel de esfuerzo se fija con el comando /effort (o la opción --effort), el razonamiento se muestra con Ctrl+O (modo detallado), y la palabra ultrathink en la solicitud le pide pensar más a fondo durante un turno; en Claude Code, con Opus 5.5, Sonnet 5.5 y Fable 5.1, el interruptor del razonamiento no se puede apagar. Más detalles: documentación de modelos
• Modelos: Opus 5.5, Sonnet 5.5, Fable 5.1: solo adaptive; Opus 4.6 y Sonnet 4.6: adaptive (el manual está obsoleto); Opus 4.5, Sonnet 4.5, Haiku 4.5: solo manual
• Precios: Lo vigente, claude.com/pricing

Conclusiones clave

Extended Thinking no es magia, es tiempo para repasar opciones. La calidad sube, y el costo también. Los thinking tokens se cobran como output: para no pagar de más, baja el effort (en modo manual, el budget_tokens) y pon un techo estricto con max_tokens. Con todos los modelos actuales usa Adaptive Thinking ("type": "adaptive") y effort en output_config: el modelo decide cuánto pensar. El budget_tokens manual da error 400 en los modelos nuevos. El parámetro display: "omitted" acelera la respuesta en producción, pero no ahorra dinero: se cobran los thinking tokens completos. Úsalo para decisiones de arquitectura y análisis complejos. Para tareas sencillas es un costo extra innecesario.

Qué sigue

→ Computer Use: controlar la pantalla