Dirigir el pensamiento

El pensamiento de Claude es adaptativo: el modelo evalúa cada solicitud y decide por sí mismo si pensar y cuánto. Tú estableces una intención, opcionalmente especificas el esfuerzo, y el modelo asigna razonamiento donde juzga que el razonamiento ayudará.

Esto hace que el pensamiento sea muy adecuado para cargas de trabajo que mezclan solicitudes triviales y complejas, y para flujos de trabajo agénticos de largo horizonte donde la cantidad correcta de razonamiento varía de un paso a otro.

Para aprender cómo activar el pensamiento, cómo leer la salida del pensamiento y sobre la salida del pensamiento en Claude Fable 5 y Claude Mythos 5, consulta la descripción general de Pensamiento. Esta página cubre cómo Claude decide cuándo pensar, cómo dirigir esa decisión, y las mecánicas de almacenamiento en caché, costo y precios que se derivan de ello.

Cómo decide Claude cuándo pensar

El pensamiento es opcional para el modelo. En cada solicitud, Claude pondera la complejidad de la entrada y decide si un razonamiento más profundo mejoraría la respuesta. Una pregunta factual simple puede recibir una respuesta directa sin ningún bloque de pensamiento; un problema matemático de varios pasos o una tarea de depuración complicada desencadena un razonamiento más profundo.

La decisión ocurre por solicitud. La misma conversación puede contener turnos con y sin pensamiento, y un turno en el que Claude eligió no pensar no contiene ningún bloque de pensamiento. No construyas lógica de aplicación que asuma que cada turno del asistente comienza con uno.

El control principal sobre esta decisión es el parámetro effort (esfuerzo), que actúa como orientación suave sobre qué tan dispuesto debe estar Claude a pensar y con qué profundidad; consulta Niveles de esfuerzo en esta página para ver qué hace cada nivel.

Si quieres que Claude piense con menos frecuencia, baja el nivel de esfuerzo antes de recurrir a la dirección basada en prompts.

El pensamiento también se intercala con el "tool use" (uso de herramientas) automáticamente: Claude puede pensar entre llamadas a herramientas, reflexionando sobre cada resultado de herramienta antes de decidir qué hacer a continuación (pensamiento intercalado). No necesitas un encabezado beta ni ninguna configuración adicional para esto.

Para ver el panorama completo de cómo interactúan la configuración de pensamiento y el parámetro de esfuerzo, consulta Pensamiento y esfuerzo.

Dirigir con qué frecuencia piensa Claude

Si Claude piensa en un turno dado es algo que se puede controlar mediante prompts. El esfuerzo establece la postura general, pero también puedes moldear la decisión directamente con orientación en lenguaje natural, ya sea globalmente en la "system prompt" (indicación del sistema) o por mensaje desde el turno del usuario.

Usa las dos palancas juntas en este orden:

1. Establece el nivel de esfuerzo que coincida con el equilibrio predeterminado de calidad y latencia de tu carga de trabajo.
2. Agrega orientación en el prompt solo si la activación del pensamiento de Claude aún no coincide con tus necesidades en ese nivel.

Para una orientación más amplia sobre prompts con pensamiento, consulta aprovechar las capacidades de pensamiento y pensamiento intercalado.

Niveles de esfuerzo

El esfuerzo es la palanca de dirección principal para el pensamiento. Cada nivel establece un valor predeterminado diferente para la frecuencia y la profundidad con que piensa Claude:

Esta tabla describe cómo cada nivel cambia el comportamiento de pensamiento. Para orientación sobre qué nivel elegir para una carga de trabajo dada, incluidas recomendaciones por modelo, consulta Cuándo ajustar el parámetro de esfuerzo en la página de esfuerzo.

El esfuerzo se establece en output_config.effort, no dentro del objeto thinking; para ejemplos completos por lenguaje, consulta Esfuerzo.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

La disponibilidad de niveles varía según el modelo; la tabla de disponibilidad de esfuerzo en la página de esfuerzo es la autoridad sobre qué niveles admite cada modelo.

Orientación en la indicación del sistema

La orientación en la indicación del sistema desplaza el umbral de pensamiento de Claude para cada solicitud en la conversación. Si Claude está pensando con más frecuencia de lo que tu carga de trabajo necesita, agrega orientación como esta a tu indicación del sistema:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

Para fomentar el pensamiento en su lugar, usa una frase como:

This task involves multistep reasoning. Think carefully before responding.

La efectividad de la dirección puede ser sensible a la redacción exacta. Si una formulación no produce el comportamiento que deseas, prueba una variante más directa.

Dirección por mensaje

También puedes dirigir el pensamiento por mensaje desde el turno del usuario, independientemente de la indicación del sistema. Agregar "Please think hard before responding." a un mensaje del usuario anima a Claude a pensar en ese turno; "Answer directly without deliberating." lo suprime.

La dirección por mensaje es útil cuando solo algunas solicitudes en una conversación justifican un razonamiento extendido. Un arnés de agente, por ejemplo, puede agregar la frase de estímulo en los pasos de planificación y la frase de supresión en las confirmaciones rutinarias, sin tocar la indicación del sistema ni cambiar ningún parámetro de solicitud entre turnos.

Verifica la dirección en tu carga de trabajo

La dirección basada en prompts cambia el comportamiento del modelo, así que trátala como cualquier otro cambio de prompt: mide antes de lanzar. Ejecuta una muestra representativa de tu tráfico con y sin la orientación, y compara con qué frecuencia se activa el pensamiento (la presencia de bloques de pensamiento en las respuestas), el uso de tokens de salida, la latencia y la calidad de las respuestas en los casos que te importan.

Mecánicas

Tres mecánicas se derivan de que Claude gestione su propio pensamiento: la validación de turnos, el almacenamiento en caché de prompts y cómo limitas el costo.

Validación de turnos

Los turnos del asistente no necesitan comenzar con un bloque de pensamiento. (Los modelos que usan un presupuesto de pensamiento manual heredado exigen que el turno final del asistente de una solicitud con pensamiento habilitado comience con uno; consulta Estructura de turnos en modo manual.)

Para aplicaciones de múltiples turnos, esto significa que puedes devolver el historial de conversación en la forma en que lo tengas:

• Los turnos del asistente en los que Claude eligió no pensar son historial válido tal como están.
• Puedes reanudar una conversación que comenzó sin pensamiento, o que usó una configuración de pensamiento diferente, sin reescribir su historial.
• El historial ensamblado a partir de fuentes mixtas no necesita que se reinserten bloques de pensamiento al inicio de cada turno del asistente para pasar la validación.

La flexibilización se refiere a la validación, no a lo que deberías enviar. Cuando tengas bloques de pensamiento, devuélvelos sin modificar, particularmente durante el uso de herramientas, donde contienen el razonamiento detrás de las llamadas a herramientas de Claude. Consulta la descripción general de Pensamiento para ver las reglas completas.

Almacenamiento en caché de prompts

Las solicitudes consecutivas que mantienen la misma configuración de pensamiento y nivel de esfuerzo preservan el "prompt caching" (almacenamiento en caché de prompts); consulta Pensamiento y almacenamiento en caché de prompts para ver las reglas completas. El valor de esfuerzo resuelto se incorpora en el prompt, por lo que cambiarlo entre solicitudes invalida los puntos de interrupción de caché, al igual que lo hace cambiar el parámetro heredado budget_tokens en los modelos que lo usan. Establecer effort explícitamente al valor predeterminado del modelo es equivalente a omitirlo y no rompe la caché.

La consecuencia práctica: elige una configuración de pensamiento y un nivel de esfuerzo por conversación y mantenlos. Si algunos turnos necesitan más o menos pensamiento, dirige con prompts por mensaje: la orientación agregada al mensaje de usuario más reciente deja intactos los puntos de interrupción de caché anteriores, mientras que un cambio de configuración o de esfuerzo no lo hace.

El siguiente ejemplo demuestra la invalidación con un script de múltiples turnos que puedes ejecutar tú mismo:

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# Obtener el contenido del artículo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usar solo el texto suficiente para el almacenamiento en caché (primeros capítulos)
LARGE_TEXT = book_content[:10000]

# Sin indicación del sistema: se almacena en caché en los mensajes
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# Primera solicitud: establecer la caché
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# Segunda solicitud: misma configuración (se espera acierto de caché)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# Tercera solicitud: nivel de esfuerzo diferente (se espera fallo de caché)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

Control de costos

No estableces un presupuesto de tokens de pensamiento. Dos controles limitan el costo:

• max_tokens es un límite estricto sobre la salida total de la solicitud, pensamiento y texto de respuesta combinados. Claude nunca genera más allá de él. En un bucle de uso de herramientas, cada solicitud en el turno tiene su propio max_tokens, por lo que no limita el gasto de todo el turno.
• effort es una orientación suave sobre cuánto de esa salida asigna Claude al pensamiento. Moldea el comportamiento pero no garantiza un conteo de tokens.

Dado que el pensamiento cuenta para max_tokens, establécelo lo suficientemente alto para dejar espacio tanto para el razonamiento como para la respuesta. Un max_tokens dimensionado para una respuesta sin pensamiento suele ser demasiado pequeño una vez que Claude comienza a pensar en solicitudes difíciles.

Con esfuerzo high y superior, Claude puede pensar extensamente y es más probable que agote el presupuesto. Si ves stop_reason: "max_tokens" en las respuestas, tienes dos remedios:

• Aumenta max_tokens para darle al modelo más espacio para el pensamiento más la respuesta.
• Baja el nivel de esfuerzo para que Claude piense menos y deje más del presupuesto para el texto de respuesta.

Cuál es el correcto depende de si las respuestas truncadas necesitaban el razonamiento. Si la calidad en esas solicitudes importa, aumenta el límite; si se pensaron en exceso, baja el esfuerzo.

Precios

El pensamiento genera cargos por:

• Tokens que Claude usa mientras piensa (facturados como tokens de salida)
• Bloques de pensamiento de turnos anteriores del asistente que permanecen en contexto, según el valor predeterminado de preservación: todos los turnos de forma predeterminada en modelos que conservan todo, solo el último turno en los demás (facturados como tokens de entrada)
• Tokens de salida de texto estándar

Lo que se te factura es lo mismo independientemente de la configuración de display; solo cambia lo que ves:

Para ver cuántos tokens de salida facturados se gastaron en razonamiento interno, lee usage.output_tokens_details.thinking_tokens en la respuesta. Este valor refleja el razonamiento en bruto que generó el modelo (no el texto resumido devuelto en el cuerpo) y siempre es menor o igual que output_tokens. Réstalo de output_tokens para aproximar la porción de la salida que no es razonamiento. Al usar streaming, este desglose aparece solo en el evento final message_delta.

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokens sigue siendo el total inclusivo y autoritativo usado para la facturación. output_tokens_details es un desglose de solo lectura para observabilidad. Para información completa de precios, incluidas tarifas base, escrituras en caché, aciertos de caché y tokens de salida, consulta Precios.

Próximos pasos