Tutorial de Extended Thinking en la API de Claude 2026: cuándo los budget tokens cambian todo

El extended thinking es una de esas funciones de la API de Claude que suena a marketing hasta que la usas en un problema realmente difícil. Según la documentación de Anthropic, al activarlo, Claude recibe un presupuesto interno de tokens para razonar paso a paso antes de producir su respuesta final. Ese razonamiento no aparece en tu output — es un borrador privado que mejora lo que sí recibes. El extended thinking fue introducido con Claude 3.7 Sonnet a principios de 2025 y está disponible en los modelos actuales de Claude.

Como desarrollador .NET/Angular que usa Claude Code para su trabajo de desarrollo, el extended thinking es lo que usaría en los problemas donde los prompts estándar producen respuestas que suenan seguras pero que se desmoronan ante el escrutinio: análisis de decisiones arquitectónicas, resolución de conflictos de dependencias, razonamiento sobre contexto de código extenso. Aquí te muestro exactamente cómo funciona la API, cómo cambia la estructura de la respuesta, cómo lo usaría en un pipeline real de backend y — igual de importante — cuándo omitirlo por completo.

Esta guía asume que ya tienes una configuración funcional de la API de Claude. Si necesitas una introducción sobre tool calling o structured outputs, revisa mis guías anteriores sobre Claude API tool use (en inglés) y structured outputs (en inglés) primero.

Qué hace realmente el extended thinking

Las llamadas estándar a la API de Claude son directas: prompt de entrada, completion de salida. El extended thinking añade una capa intermedia. Antes de generar la respuesta visible, Claude trabaja el problema internamente usando el presupuesto de tokens que tú asignas. Según la documentación de Anthropic, ese contenido de razonamiento es visible en la respuesta de la API como un bloque de contenido separado — puedes registrarlo, analizarlo o ignorarlo — pero no aparece en la respuesta de texto final a menos que lo muestres explícitamente en tu UI.

Esto importa por dos razones concretas. Primero, cambia lo que Claude puede hacer de forma confiable en problemas difíciles. Las cadenas lógicas de múltiples pasos, las opciones arquitectónicas en competencia, el análisis de contexto largo — todo esto tiende a fallar cuando un modelo intenta producirlo en un solo forward pass junto con el texto de respuesta. Darle a Claude espacio para trabajar el problema primero significa que la respuesta final está informada por ese razonamiento, no producida simultáneamente con él. Segundo, obtienes observabilidad que de otra forma requeriría prompts adicionales: los trazos de razonamiento te muestran por qué Claude hizo una recomendación particular, lo cual es valioso al depurar pipelines agénticos donde una inferencia intermedia incorrecta puede derivar en un output final peor varios pasos después.

Un punto crítico de entrada: los tokens de razonamiento se facturan como tokens de output, que cuestan más que los tokens de input. Según el pricing de Anthropic, si estableces budget_tokens: 8000 y Claude usa 6.400 tokens de razonamiento antes de producir una respuesta de 500 tokens, pagas aproximadamente 6.900 tokens de output. Vale la pena modelar esto antes de activar el extended thinking en un endpoint de alto volumen. La buena noticia es que Claude no consume el presupuesto que no necesita — el presupuesto no utilizado no se cobra — por lo que establecer un límite generoso no tiene costo adicional si el problema es más simple de lo esperado.

Tu primera request con extended thinking

El cambio en la API es mínimo — un único parámetro thinking adicional en el endpoint estándar de messages. Usaré el SDK de Python a lo largo del tutorial por ser la opción más común para integraciones de backend, pero la estructura JSON es idéntica para cualquier cliente HTTP.

pip install anthropic

Aquí está la llamada más simple posible con extended thinking:

import anthropic

client = anthropic.Anthropic(api_key="tu-api-key")

response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=16000,  # debe cubrir tokens de razonamiento + output combinados
    thinking={
        "type": "enabled",
        "budget_tokens": 8000
    },
    messages=[{
        "role": "user",
        "content": (
            "Estoy construyendo una API en .NET 9 que debe procesar 50.000 eventos "
            "webhook por hora. Los eventos vienen de tres fuentes con esquemas distintos. "
            "Considero: (a) un handler genérico con schema registry, "
            "(b) tres clases handler tipadas separadas, "
            "(c) un enfoque de message bus con consumers por tipo de evento. "
            "Analiza los trade-offs de mantenibilidad y rendimiento en runtime."
        )
    }]
)

for block in response.content:
    if block.type == "thinking":
        print("=== RAZONAMIENTO ===")
        print(block.thinking)
    elif block.type == "text":
        print("=== RESPUESTA ===")
        print(block.text)

Dos restricciones que debes conocer antes de desplegar esto. Primero, max_tokens debe ser suficientemente grande para cubrir tanto los tokens de razonamiento como los tokens de output final. Según la documentación de Anthropic, si budget_tokens es 8.000, tu max_tokens debe ser al menos 8.001 más lo que esperes para la respuesta final — de lo contrario, la llamada falla con un error de validación. Segundo, no puedes establecer temperature a ningún valor diferente de 1 cuando el extended thinking está activado. La API lo exige. Si tu código cliente ya establece temperature dinámicamente, deberás omitirlo condicionalmente al activar el thinking.

Una restricción adicional según la documentación de Anthropic: el extended thinking no es compatible con el prompt caching aplicado al mismo message turn que contiene el parámetro thinking. Puedes seguir cacheando un system prompt extenso con cache_control en el mismo request — y ese cache aplica normalmente — pero el turn de thinking en sí no se cachea por separado. Ten esto en cuenta si combinas extended thinking con los patrones de prompt caching (en inglés).

Leyendo la respuesta: bloques de razonamiento explicados

Al activar el extended thinking, response.content se convierte en una lista ordenada de bloques de contenido en lugar de un objeto de texto simple. Según la documentación de Anthropic, el orden es siempre: bloques de razonamiento primero, luego bloques de texto. En la práctica recibirás un bloque de razonamiento seguido de un bloque de texto para la mayoría de las requests. Así se maneja esto limpiamente en un método de servicio:

from anthropic.types import ThinkingBlock, TextBlock
import logging

logger = logging.getLogger(__name__)

def extract_thinking_response(response, request_id: str) -> tuple[str, str]:
    """Retorna (trazo_razonamiento, respuesta_final)."""
    thinking_parts = []
    text_parts = []

    for block in response.content:
        if isinstance(block, ThinkingBlock):
            thinking_parts.append(block.thinking)
        elif isinstance(block, TextBlock):
            text_parts.append(block.text)

    thinking = "\n\n".join(thinking_parts)
    answer = "\n\n".join(text_parts)

    # Registrar razonamiento internamente — nunca exponer a usuarios finales
    logger.debug("Razonamiento Claude (request_id=%s): %s", request_id, thinking[:800])

    return thinking, answer

thinking, answer = extract_thinking_response(response, request_id="req-001")
return {"answer": answer}

El objeto response.usage desglose los tokens que necesitas para controlar costos. response.usage.input_tokens cuenta el prompt; response.usage.output_tokens es la suma combinada de tokens de razonamiento y tokens de respuesta final. Registra esto por tipo de request y rápidamente desarrollarás intuición sobre cuánto del presupuesto consume realmente cada categoría de tarea. En muchos casos Claude usa significativamente menos del presupuesto asignado — eso es una señal de que puedes reducir el presupuesto sin ninguna regresión de calidad.

En un backend de producción, correlacionaría los trazos de razonamiento con un request ID y los almacenaría en un log estructurado separado de la respuesta orientada al usuario. Cuando una recomendación de Claude resulta ser incorrecta o desenfocada, el bloque de razonamiento es generalmente donde vive la suposición errónea. Es esencialmente logging de diagnóstico gratuito que de otra manera tendrías que extraer de Claude mediante un prompt de depuración separado.

Cuándo el extended thinking realmente ayuda

No todo problema se beneficia del extended thinking. Según la documentación de Anthropic, los casos de uso previstos son problemas que requieren razonamiento sostenido de múltiples pasos: derivaciones matemáticas, cadenas lógicas complejas, análisis exhaustivo de opciones de diseño en competencia, decisiones detalladas de arquitectura de código. El hilo común es que el problema tiene una respuesta no obvia que depende de mantener múltiples restricciones en mente simultáneamente.

Para las tareas de desarrollo donde lo usaría — revisar el grafo de dependencias de un proyecto .NET, evaluar opciones arquitectónicas en un diseño de API, razonar sobre un plan de migración de base de datos extenso — el extended thinking notablemente mejora el output. Sin él, Claude a veces omite los pasos intermedios y entrega una recomendación segura que ignora una restricción enterrada en el prompt. Con un presupuesto de 5.000–8.000 tokens, trabaja esas restricciones antes de comprometerse con una respuesta, y la recomendación es más defendible.

El extended thinking añade latencia y costo sin beneficio para tareas simples: escribir un resumen, generar boilerplate, reformatear JSON, escribir docstrings, responder una pregunta factual directa. Si estás construyendo un endpoint de alto rendimiento donde la mayoría de las requests son transformaciones simples, la arquitectura correcta es dejar el extended thinking desactivado por defecto y activarlo solo para un subconjunto de requests complejas que identificas mediante lógica de enrutamiento. La sección de estrategia de presupuesto cubre cómo implementar ese enrutamiento consciente del costo.

Un caso de uso real: análisis de decisiones arquitectónicas en .NET

Aquí hay un patrón que implementaría en un servicio de backend .NET: un asesor de arquitectura impulsado por Claude que toma un diseño de sistema propuesto y una lista de restricciones y devuelve una recomendación estructurada en JSON. El extended thinking encaja bien aquí porque el modelo necesita mantener múltiples restricciones en mente simultáneamente — latencia, requisitos de consistencia, nivel de habilidad del equipo, complejidad de despliegue — antes de comprometerse con una recomendación.

import anthropic
import json

client = anthropic.Anthropic(api_key="tu-api-key")

SYSTEM_PROMPT = (
    "Eres un arquitecto de software senior revisando propuestas de diseño de sistemas. "
    "Analiza el diseño contra las restricciones indicadas y devuelve una recomendación JSON. "
    "Sé específico sobre los trade-offs. No recomiendes patrones con los que el equipo "
    "no haya demostrado familiaridad. Devuelve solo JSON válido, sin markdown."
)

def analyze_architecture(design: str, constraints: list[str]) -> dict:
    constraints_text = "\n".join(f"- {c}" for c in constraints)

    response = client.messages.create(
        model="claude-3-7-sonnet-20250219",
        max_tokens=12000,
        thinking={"type": "enabled", "budget_tokens": 7000},
        system=SYSTEM_PROMPT,
        messages=[{
            "role": "user",
            "content": (
                f"Propuesta de diseño:\n{design}\n\n"
                f"Restricciones:\n{constraints_text}\n\n"
                "Devuelve JSON con claves: recommendation, rationale, "
                "trade_offs (lista), risks (lista), alternative_considered."
            )
        }]
    )

    answer = next(b.text for b in response.content if b.type == "text")
    return json.loads(answer.strip())

result = analyze_architecture(
    design=(
        "Servicio de gestión de pedidos con event sourcing usando PostgreSQL + outbox pattern, "
        ".NET 9, desplegado en Azure Container Apps."
    ),
    constraints=[
        "Equipo de 3 personas con experiencia sólida en SQL, poca experiencia en event sourcing",
        "Objetivo de latencia P99 en escrituras: 200ms",
        "10.000 pedidos por día al lanzamiento, objetivo de crecimiento 10x en 12 meses",
        "Sin infraestructura dedicada de event streaming — sin presupuesto para Kafka"
    ]
)

print(json.dumps(result, indent=2))

El extended thinking y los structured outputs funcionan juntos de forma limpia. Pasas las instrucciones JSON en el prompt como siempre, y el bloque de razonamiento trabaja las restricciones de contenido antes de comprometerse con la estructura. Esta combinación es especialmente confiable para outputs de análisis complejo donde necesitas tanto razonamiento riguroso como un resultado parseable. Para más sobre el lado de structured outputs, revisa mi guía sobre Claude API structured outputs (en inglés).

Si quieres profundizar en los patrones arquitectónicos detrás de los sistemas LLM en producción — incluyendo cómo diseñar pipelines de razonamiento confiables y evaluar la calidad del output — AI Engineering de Chip Huyen (~$50) es uno de los tratamientos más rigurosos disponibles y aplica bien a las decisiones que enfrentarás al integrar el extended thinking en un servicio real.

Estrategia de presupuesto de tokens

El dimensionamiento del presupuesto es la decisión práctica más importante al adoptar el extended thinking. Según la documentación de Anthropic, el mínimo es 1.024 tokens y el máximo varía según el modelo. El presupuesto no utilizado no se cobra — Claude deja de razonar cuando tiene suficiente contexto para producir una buena respuesta. Entonces, establecer un límite superior mayor de lo necesario es seguro en términos de costo, pero impone un piso en cuánto tiempo podría tardar Claude en comenzar a hacer streaming de la respuesta de texto en requests genuinamente complejas.

El enfoque de calibración que usaría: empezar con un presupuesto moderado (4.000–6.000 tokens), registrar el uso real de tokens de razonamiento desde response.usage en una muestra de requests reales, y ajustar a partir de ahí. Si Claude consistentemente alcanza el límite — uso real cercano a budget_tokens — aumenta el presupuesto. Si el uso es consistentemente menor al 50% de la asignación, o estás sobreasignando o la categoría de tarea no se beneficia suficientemente del extended thinking para justificar el costo.

Para aplicaciones sensibles al costo, un router de dos niveles es el patrón correcto. Haz una llamada de clasificación rápida y económica — sin extended thinking — para determinar si la request entrante es lo suficientemente compleja como para justificarlo. Enruta las requests complejas a un endpoint con extended thinking y las simples a un endpoint estándar. Esto añade una pequeña llamada a la API por request pero puede reducir a la mitad el gasto en tokens de razonamiento en cargas de trabajo de tráfico mixto. Combínalo con prompt caching (en inglés) en tu system prompt — un system prompt de 2.000 tokens cacheado al nivel cache_control: ephemeral cuesta el 10% del precio normal de tokens de input en llamadas posteriores, según la documentación de caching de Anthropic, lo que compensa parte del overhead del extended thinking.

Streaming de extended thinking en producción

El extended thinking es completamente compatible con el streaming. Según la documentación de Anthropic, al hacer streaming de una respuesta con thinking activado, recibes eventos content_block_start tanto para el bloque de razonamiento como para el bloque de texto, con eventos content_block_delta que llevan contenido incremental para cada uno. Esto importa para las aplicaciones orientadas al usuario: puedes empezar a hacer streaming de la respuesta final al usuario tan pronto como la fase de razonamiento se complete, sin esperar a que toda la respuesta se genere.

thinking_buffer = ""
current_block = None

with client.messages.stream(
    model="claude-3-7-sonnet-20250219",
    max_tokens=12000,
    thinking={"type": "enabled", "budget_tokens": 6000},
    messages=[{"role": "user", "content": user_prompt}]
) as stream:
    for event in stream:
        if not hasattr(event, "type"):
            continue
        if event.type == "content_block_start":
            current_block = event.content_block.type
        elif event.type == "content_block_delta":
            if current_block == "thinking" and hasattr(event.delta, "thinking"):
                thinking_buffer += event.delta.thinking
            elif current_block == "text" and hasattr(event.delta, "text"):
                yield event.delta.text  # enviar al usuario via SSE

logger.info("Trazo de razonamiento: %s", thinking_buffer[:500])

En un endpoint de FastAPI con StreamingResponse, harías yield de esos tokens de texto como server-sent events. La fase de razonamiento hace streaming en segundo plano y nunca llega al cliente — la almacenas en buffer para logging. El usuario ve un buen tiempo-hasta-el-primer-token porque el bloque de texto comienza a hacer streaming inmediatamente cuando Claude transiciona fuera de la fase de razonamiento. Para tareas de alta latencia donde asignas 8.000 tokens o más de razonamiento, el streaming hace la UX notablemente más tolerable que esperar la respuesta completa antes de renderizar algo.

Un punto a tener en cuenta en los tipos de eventos del stream: la forma exacta de event.delta difiere entre deltas de razonamiento y deltas de texto — el razonamiento usa un atributo thinking, el texto usa un atributo text. El código anterior maneja esto correctamente con verificaciones hasattr. Siempre protege contra el acceso a atributos en el tipo de delta incorrecto o tendrás excepciones intermitentes de AttributeError en producción.

Patrones prácticos para producción

Algunos patrones que aplicaría al integrar el extended thinking en un servicio real. Primero, construye un fallback elegante. Si la llamada con extended thinking excede el tiempo de espera o la respuesta falla una validación posterior, recae en una llamada estándar sin thinking y marca la respuesta para revisión. El extended thinking es una mejora, no una dependencia crítica. Tu app debe seguir produciendo una respuesta útil cuando no esté disponible.

Segundo, versiona tu configuración de presupuesto. Almacena budget_tokens en la configuración de la aplicación en lugar de hardcodearlo. A medida que los modelos mejoran, el presupuesto efectivo necesario para un tipo de tarea dado puede disminuir. Poder ajustar el presupuesto sin un deploy de código es útil, especialmente en las primeras semanas después de la adopción cuando todavía estás calibrando los patrones de uso entre diferentes tipos de requests.

Tercero, piensa cuidadosamente en si mostrar los trazos de razonamiento en tu UI. Para herramientas internas de desarrolladores o aplicaciones orientadas a analistas donde el output de Claude informa decisiones significativas, un panel colapsable de "razonamiento" que muestra el trazo genera confianza medible — los usuarios pueden verificar la lógica en lugar de solo aceptar la conclusión. Para productos orientados al consumidor, generalmente es la decisión incorrecta ya que el razonamiento crudo suele ser verboso y técnico. Una referencia práctica para este tipo de decisiones de integración de LLM es Hands-On Large Language Models (~$45) — sus capítulos sobre construcción de funciones de LLM orientadas al usuario aplican directamente a estas decisiones de UX.

Finalmente, el extended thinking se combina naturalmente con tool use en workflows agénticos. Si estás construyendo un pipeline donde Claude llama herramientas, procesa resultados y produce una síntesis final — un agente de análisis de código de múltiples pasos, un pipeline de investigación de documentos — activar el extended thinking específicamente en el paso de síntesis ofrece el mayor valor por el costo. Los pasos intermedios de llamadas a herramientas generalmente no lo necesitan; el paso final de síntesis, donde Claude reconcilia todo lo que ha recopilado, frecuentemente sí. Revisa mi guía sobre Claude API tool use (en inglés) para ver cómo estructurar ese tipo de loop agéntico de múltiples turnos.