Razonamiento y esfuerzo

El razonamiento permite que el modelo genere un razonamiento interno antes de la respuesta, devuelto en bloques thinking. En los modelos actuales se activa en modo adaptativo: el propio modelo decide si necesita pensar y cuánto, según la dificultad de la petición. Tú orientas ese gasto con el esfuerzo (effort) y lo limitas con max_tokens.

Es la versión integrada en el modelo de la idea de la cadena de pensamiento (Wei et al., 2022, Chain-of-Thought Prompting Elicits Reasoning in LLMs): dar al modelo espacio para trabajar el problema antes de comprometerse con una respuesta.

Parámetros

El presupuesto manual con budget_tokens es el modo antiguo. Si lo encuentras en código existente, funciona en los modelos que lo admiten, pero en código nuevo usa el modo adaptativo.

Elegir el nivel de esfuerzo

No hay un nivel correcto en abstracto. Mide: ejecuta tu conjunto de evaluación con dos niveles y compara calidad, tokens de salida y latencia. Consulta qué niveles acepta cada modelo y cuál es su valor por defecto en la documentación oficial.

Ejemplo completo

import anthropic

MODEL = "claude-sonnet-5-5"
client = anthropic.Anthropic()

resp = client.messages.create(
    model=MODEL,
    max_tokens=16000,  # razonamiento + respuesta; deja margen
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{
        "role": "user",
        "content": "Un tren sale a las 9:40 y tarda 2 h 35 min con una parada de 12 min. "
                   "Si sale con 18 min de retraso, ¿a qué hora llega?",
    }],
)

for bloque in resp.content:
    if bloque.type == "thinking":
        print("[razonamiento]", bloque.thinking[:200], "...")
    elif bloque.type == "text":
        print(bloque.text)

if resp.stop_reason == "max_tokens":
    print("Aviso: se agotó max_tokens; la respuesta puede faltar o estar cortada.")
print("tokens de salida:", resp.usage.output_tokens)

import Anthropic from "@anthropic-ai/sdk";

const MODEL = "claude-sonnet-5-5";
const client = new Anthropic();

const resp = await client.messages.create({
  model: MODEL,
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [
    {
      role: "user",
      content:
        "Un tren sale a las 9:40 y tarda 2 h 35 min con una parada de 12 min. " +
        "Si sale con 18 min de retraso, ¿a qué hora llega?",
    },
  ],
});

for (const bloque of resp.content) {
  if (bloque.type === "thinking") console.log("[razonamiento]", bloque.thinking.slice(0, 200), "...");
  else if (bloque.type === "text") console.log(bloque.text);
}
if (resp.stop_reason === "max_tokens") console.warn("Aviso: se agotó max_tokens.");
console.log("tokens de salida:", resp.usage.output_tokens);

Los tokens de razonamiento cuentan como salida en usage.output_tokens y se facturan como tales.

Razonamiento con herramientas

En un bucle de herramientas el modelo puede razonar antes de cada tool_use y después de recibir cada tool_result. La regla que no puedes saltarte: reenvía los bloques thinking sin modificar dentro del mensaje assistant mientras dura el ciclo. Llevan una firma que la API verifica; si los borras o los editas, la petición falla o el modelo pierde el hilo.

La forma más sencilla de cumplirla es añadir resp.content entero al historial, como en Uso de herramientas.

flowchart LR
  P[Petición] --> T[thinking]
  T --> U[tool_use]
  U --> R[tool_result]
  R --> T2[thinking]
  T2 --> X[text final]

Cuándo no compensa

• Tareas simples. Clasificar, extraer un campo o reformular no mejoran pensando más; solo cuestan más.
• Latencia crítica. En voz o autocompletado, el tiempo de razonamiento se nota. Usa esfuerzo bajo o desactívalo.
• Para obtener explicaciones. Si quieres que el modelo explique su respuesta a la persona, pídelo en el prompt. El bloque thinking es material de trabajo, no una explicación pensada para mostrar. Ver Dejar pensar al modelo.

Errores frecuentes

• max_tokens pequeño con esfuerzo alto. El razonamiento se come el presupuesto y la respuesta llega vacía o cortada (stop_reason == "max_tokens").
• Filtrar los bloques thinking del historial en un ciclo de herramientas.
• Subir el esfuerzo para arreglar un mal prompt. Si las instrucciones son ambiguas, pensar más no las aclara.
• Mostrar el razonamiento en bruto en la interfaz sin decidirlo. Puede ser largo y confuso para la persona usuaria.
• Pedir «piensa paso a paso» y además activar thinking. Redundante: el modelo ya tiene espacio para razonar.

Ver también

• Dejar pensar al modelo: cuándo ayuda y cuándo no.
• Esfuerzo (effort) y Razonamiento extendido.
• Costes y límites: el razonamiento en la factura.
• El razonamiento pasa a ser adaptativo.