Llamas a la API de Claude — la interfaz de Anthropic para enviar prompts y obtener respuestas de forma programática — y las tareas simples salen perfectas. Extracción, resumen, clasificación: Claude las clava. Entonces le lanzas algo difícil. Revisar un pull request de 2,000 líneas. Planificar una migración de base de datos. Depurar una condición de carrera. La respuesta llega rápida, segura de sí misma, y sutilmente incorrecta. Como un estudiante que le echó un ojo al libro y está improvisando en el examen.

El problema no es el modelo. El problema es que no le estás dando papel borrador.

Por qué "Solo lee la documentación" no alcanza

Claude tiene una funcionalidad llamada extended thinking — la capacidad de razonar paso a paso internamente antes de responder, como mostrar tu procedimiento en un examen de matemáticas excepto que el procedimiento queda oculto. Anthropic la presentó el 24 de febrero de 2025 con Claude 3.7 Sonnet, y ha evolucionado drásticamente desde entonces.

La documentación es completa. También son 4,000 palabras de tablas de parámetros, avisos de deprecación y guías de migración repartidas en tres páginas separadas. La mayoría de los desarrolladores hacen una de tres cosas: ignoran thinking completamente, copian y pegan una configuración de un blog post dirigido a un modelo anterior, o lo habilitan sin controles de costo y se llevan la sorpresa de una cuenta de $50.

El 16 de abril de 2026, Anthropic lanzó Claude Opus 4.7 y rompió los tres enfoques. ¿El parámetro manual budget_tokens que antes controlaba el costo del razonamiento? Ahora devuelve un error 400. Un nuevo tokenizador infla los conteos de tokens hasta un 35%. Y el thinking es invisible por defecto — mientras te cobra a la tarifa completa de $25 por millón de tokens.

Así es como se configura correctamente, al 27 de abril de 2026.

Paso 1: Habilitar Adaptive Thinking

En Opus 4.7, usas adaptive thinking — el modelo decide cuánto pensar según la dificultad del problema. Sin presupuestos manuales de tokens. Controlas la intensidad con un parámetro effort (una etiqueta simple como "low", "high" o "max") en lugar de adivinar un número.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{
        "role": "user",
        "content": "Review this SQL migration for correctness and edge cases: ..."
    }],
)

Tres líneas añadidas: thinking, output_config, y un max_tokens más grande — el tope de cuántos tokens (pedazos de palabras que la IA procesa, aproximadamente ¾ de una palabra en inglés) puede contener la respuesta. Los tokens de thinking cuentan contra este tope, así que ponlo en al menos 16,000. Anthropic recomienda 32,000+ para tareas complejas. Si el thinking solo excediera tu máximo, la petición falla — sin respuesta parcial, solo un error.

/faion es la herramienta de prompts de Nero para generar código funcional a partir de una especificación — pega el bloque de abajo y obtén un punto de partida listo para producción.

/faion
Generate a Python function `call_with_thinking(prompt: str, effort: str = "high") -> str` that calls Claude Opus 4.7 with adaptive thinking using the anthropic Python SDK. Accept an effort parameter ("low", "medium", "high", "xhigh", "max"). Set max_tokens to 16000. Return the text response. Include error handling for API errors and a docstring explaining the effort levels.

Paso 2: Elegir el nivel de esfuerzo correcto

No todos los prompts merecen un doctorado en filosofía. Aquí va la guía rápida, basada en las recomendaciones de Anthropic y datos de producción de las pruebas de Resolve AI:

Effort Qué hace Cuándo usarlo
low Salta el thinking para tareas triviales Clasificación, extracción, pipelines de alto volumen
medium Razonamiento moderado, puede saltarlo Balance costo/calidad, la mayoría de flujos agénticos
high Casi siempre razona profundamente Code review, análisis, planificación
xhigh Exploración extendida (solo Opus 4.7) Codificación multi-archivo, cadenas agénticas largas
max Sin restricciones de pensamiento Problemas de frontera, investigación, presupuestos ilimitados

El hallazgo clave de Resolve AI: Sonnet 4.6 en medium iguala aproximadamente la calidad de Opus 4.6 a una fracción del costo. No vayas directo al modelo más grande — ve al nivel de esfuerzo correcto en uno más barato. La optimización más inteligente muchas veces es no pagar por Opus.

Paso 3: Streaming del thinking para UX en tiempo real

Sin streaming, una petición con thinking pesado significa que tu usuario se queda mirando una pantalla muerta por más de 30 segundos. Con streaming, ven el razonamiento del modelo desplegarse en vivo — progreso visible en lugar de la duda existencial de si la app se colgó.

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "Analyze this codebase architecture..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(f"[thinking] {event.delta.thinking}", end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Fíjate en "display": "summarized". En Opus 4.7, el valor por defecto es "omitted" — el modelo piensa, pagas por los tokens, pero el texto del razonamiento regresa vacío. Tienes que configurar display explícitamente si quieres ver qué razonó el modelo. Depurar razonamiento invisible es exactamente tan divertido como suena.

/faion
Generate a Python function `stream_thinking_response(prompt: str, effort: str = "high")` that calls Claude Opus 4.7 with adaptive thinking and streaming enabled via the anthropic Python SDK. Set display to "summarized". Print thinking deltas prefixed with "[thinking]" and text deltas without prefix. Set max_tokens to 32000. Handle stream cleanup properly with a context manager.

Paso 4: Manejar tool use sin romper la cadena

Si tu integración usa tools — funciones que el modelo puede llamar, como consultar una base de datos o hacer un request a una API externa — necesitas preservar los bloques de thinking al continuar la conversación. Si los eliminas, Claude pierde su contexto de razonamiento a medio flujo.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[your_tool],
    messages=[
        {"role": "user", "content": "What's the production error rate?"},
        {"role": "assistant", "content": [
            thinking_block,   # NO TOCAR — quitarlo mata el contexto
            tool_use_block
        ]},
        {"role": "user", "content": [tool_result]},
    ],
)

Una restricción que va a morder a las arquitecturas agénticas: con thinking habilitado, tool_choice — que controla si Claude debe usar una herramienta específica — solo soporta "auto" o "none". Forzar una herramienta específica devuelve un error.

Paso 5: Monitorear lo que realmente estás pagando

Cada respuesta incluye un objeto usage. Después de habilitar thinking, esta se convierte en la línea más importante de tu código:

cost_per_mtok = 25  # Precio de output de Opus 4.7
output_cost = (response.usage.output_tokens / 1_000_000) * cost_per_mtok
print(f"Output tokens: {response.usage.output_tokens} (${output_cost:.4f})")

El conteo de tokens de output incluye TODOS los tokens de thinking — incluso los invisibles bajo display: "omitted". Si tu respuesta visible es de 500 tokens pero output_tokens dice 8,000, acabas de pagar 7,500 tokens de razonamiento que nadie vio. Según la página de precios de Anthropic, los tokens de thinking se cobran a la tarifa completa de output: $25/MTok para Opus, $15/MTok para Sonnet.

/faion
Generate a Python helper function `log_thinking_cost(response, model: str = "claude-opus-4-7")` that takes an Anthropic Messages API response object and prints a cost breakdown: input tokens, output tokens (including thinking), cache read tokens, and total estimated cost in USD. Use a dict of per-model pricing (Opus 4.7: $15 input / $25 output, Sonnet 4.6: $3 input / $15 output). Warn if output_tokens exceeds 5000 with a note about possible high thinking usage.

Trampas que te van a morder

El impuesto del tokenizador. El nuevo tokenizador de Opus 4.7 genera hasta 35% más tokens por el mismo texto comparado con Opus 4.6. Tus costos suben sin cambiar una sola línea de código al actualizar de modelo. Un proceso de thinking que costaba $0.25 en Opus 4.6 podría costar $0.34 en 4.7 — mismo razonamiento, cuenta más alta. Monitorea usage antes y después de cambiar de modelo.

Los tokens de thinking no se pueden cachear. Prompt caching — la funcionalidad de Anthropic que descuenta tokens de input repetidos — no aplica al contenido de thinking. En loops agénticos con muchas llamadas a tools, Claude relee los bloques de thinking de turnos anteriores como input. Esto genera costos compuestos que no vas a ver a menos que rastrees cache_read_input_tokens por separado.

La trampa legacy. ¿Sigues en Claude Sonnet 4.6 u Opus 4.6? budget_tokens todavía funciona. Actualizas a Opus 4.7, y devuelve un error 400 sin aviso de deprecación en runtime — solo un fallo seco. Prueba antes de desplegar.

El tope de max_tokens. Los tokens de thinking y los tokens de respuesta comparten el mismo tope de max_tokens. Pones max_tokens: 4000, y si el modelo piensa por 3,800 tokens, te quedan 200 tokens de respuesta. Siempre ponlo más alto de lo que crees necesitar.

Qué puedes hacer ahora

Tienes dos velocidades. Para el 80% rutinario — extracción, formateo, Q&A simple — usa effort: "low" o salta el thinking completamente. Para el 20% difícil — code review, planificación de arquitectura, análisis complejo — usa "high" o "xhigh" con streaming y monitoreo de costos. Corre 100 llamadas, revisa los números de usage, y después ajusta.

Hace un año, cada llamada a la API de Claude corría a la misma profundidad — rápida, superficial, una sola marcha. Ahora tú controlas el dial. El modelo que razona 30 segundos sobre un bug difícil es el mismo que salta el thinking completamente en una tarea de clasificación. Mismo endpoint, mismo código, tres líneas de configuración de diferencia. Gíralo.