Dirigir el pensamiento
Dirige con qué frecuencia y con qué profundidad piensa Claude mediante niveles de esfuerzo, orientación en la indicación del sistema y dirección por mensaje, y comprende el costo y los precios del pensamiento.
El pensamiento de Claude es adaptativo: el modelo evalúa cada solicitud y determina si debe pensar y cuánto. Tú estableces una intención, opcionalmente especificas el esfuerzo, y el modelo asigna razonamiento donde es probable que el razonamiento ayude.
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 en los que la cantidad adecuada de razonamiento varía de un paso a otro.
Para aprender cómo activar el pensamiento y cómo leer la salida del pensamiento, consulta la descripción general de Pensamiento. Esta página explica cómo Claude determina cuándo pensar, cómo dirigir el pensamiento y la mecánica de caché, costo y precios que se derivan de ello.
Cómo Claude determina cuándo pensar
El pensamiento es opcional para el modelo. En cada solicitud, Claude evalúa la complejidad de la entrada y determina 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.
Esta determinación ocurre en cada solicitud. La misma conversación puede contener turnos con y sin pensamiento, y un turno en el que Claude omite el pensamiento 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 determinación es el parámetro effort (esfuerzo), que actúa como una orientación flexible sobre con qué frecuencia y con qué profundidad Claude usa el pensamiento; consulta Niveles de esfuerzo en esta página para ver qué hace cada nivel.
Si quieres que Claude piense con menos frecuencia, reduce el nivel de esfuerzo antes de recurrir a la dirección basada en prompts.
El pensamiento también se intercala automáticamente con el uso de herramientas: Claude puede pensar entre llamadas a herramientas, evaluando cada resultado de herramienta antes de determinar qué hacer a continuación (pensamiento intercalado).
Para conocer todos los detalles sobre cómo interactúan la configuración del pensamiento y el parámetro effort, consulta Pensamiento y esfuerzo.
Dirigir con qué frecuencia piensa Claude
Si Claude piensa en un turno determinado se puede controlar mediante prompts. El esfuerzo establece la postura general, pero también puedes moldear ese comportamiento directamente con orientación en lenguaje natural, ya sea globalmente en la indicación del sistema o para mensajes individuales en el turno del usuario.
Usa las dos palancas juntas en este orden:
- Establece el nivel de esfuerzo que coincida con el equilibrio predeterminado entre calidad y latencia de tu carga de trabajo.
- Agrega orientación en el prompt solo si la activación del pensamiento de Claude aún no se ajusta a tus necesidades en ese nivel.
Para obtener 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 principal para dirigir el pensamiento. Cada nivel establece un valor predeterminado diferente sobre con qué frecuencia y con qué profundidad piensa Claude:
| Nivel de esfuerzo | Comportamiento del pensamiento |
|---|---|
max | Claude piensa con mayor disposición y con la mayor profundidad, sin restricción en la longitud del pensamiento. |
xhigh | Claude piensa con más disposición y con mayor profundidad que en high, adecuado para exploraciones extensas. |
high (predeterminado en la mayoría de los modelos) | Claude piensa en la mayoría de las solicitudes que se benefician de ello. Proporciona un razonamiento profundo en tareas complejas. |
medium (predeterminado en Claude Opus 5.5 y Claude Haiku 5.5) | Claude usa un pensamiento moderado. Puede omitir el pensamiento en consultas simples. |
low | Claude minimiza el pensamiento. Omite el pensamiento en tareas simples donde la velocidad es lo más importante. |
En todos los niveles, Claude determina para cada solicitud si debe pensar. En un bucle de uso de herramientas, la primera solicitud después de una nueva entrada del usuario normalmente concentra la mayor parte del razonamiento, y las solicitudes posteriores que solo procesan resultados de herramientas pueden omitir el pensamiento, incluso en xhigh y max. El pensamiento por solicitud también tiende a disminuir a medida que una conversación se alarga. Ningún nivel garantiza un bloque de pensamiento en cada solicitud.
Esta tabla describe cómo cada nivel cambia el comportamiento del pensamiento. Para obtener orientación sobre qué nivel elegir para una carga de trabajo determinada, incluidas recomendaciones por modelo, consulta Cuándo ajustar el parámetro effort en la página de esfuerzo.
El esfuerzo se establece en output_config.effort, no dentro del objeto thinking; para ver ejemplos completos por lenguaje, consulta Establecer el nivel de esfuerzo.
{
"model": "claude-opus-5-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 referencia oficial 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 de la conversación. Si Claude piensa con más frecuencia de la que necesita tu carga de trabajo, agrega una orientación como la siguiente 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 cambio, usa una frase como:
This task involves multistep reasoning. Think carefully before responding.La eficacia 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 mensaje por mensaje desde el turno del usuario, independientemente de la indicación del sistema. Añadir "Please think hard before responding." a un mensaje del usuario anima a Claude a pensar en ese turno; "Answer directly without deliberating." lo desalienta.
La dirección por mensaje es útil cuando solo algunas solicitudes de una conversación justifican un razonamiento extenso. Un harness de agente, por ejemplo, puede añadir la frase que fomenta el pensamiento en los pasos de planificación y la frase que lo desalienta en las confirmaciones rutinarias, sin tocar la indicación del sistema ni cambiar ningún parámetro de la solicitud entre turnos.
En Claude Haiku 5.5 y Claude Fable 5.2, la frase que desalienta el pensamiento no lo reduce de forma fiable. En las pruebas de Anthropic, no evitó que Claude Fable 5.2 pensara con esfuerzo medium o superior. Donde tu plataforma lo admita, ejecuta los turnos rutinarios en estos modelos con menos pensamiento usando en su lugar un cambio de esfuerzo por mensaje. Esta función beta además conserva la caché del prompt.
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 publicar. 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ánica
De que Claude gestione su propio pensamiento se derivan tres mecanismos: la validación de turnos, el almacenamiento en caché de prompts y cómo acotas 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 último turno del asistente de una solicitud con pensamiento habilitado comience con uno; consulta Estructura de turnos en modo manual.)
Para aplicaciones de varios turnos, esto significa que puedes devolver el historial de la conversación en cualquiera de estas formas:
- Los turnos del asistente que Claude produjo sin pensamiento son un 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 vuelvan a insertar bloques de pensamiento al inicio de cada turno del asistente para pasar la validación.
Esto solo significa que un turno puede comenzar sin un bloque de pensamiento. Cuando tengas bloques de pensamiento, devuélvelos sin modificar, en particular 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 conocer las reglas completas.
Almacenamiento en caché de prompts
Las solicitudes consecutivas que mantienen la misma configuración de pensamiento y el mismo nivel de esfuerzo conservan el almacenamiento en caché de prompts; consulta Pensamiento y almacenamiento en caché de prompts para conocer las reglas completas. El valor de esfuerzo resuelto se representa en el prompt, por lo que cambiarlo entre solicitudes puede invalidar los puntos de interrupción de la caché. También puede hacerlo cambiar el parámetro heredado budget_tokens, en los modelos que lo usan. Establecer effort explícitamente en el valor predeterminado del modelo equivale a omitirlo y no rompe la caché.
La consecuencia práctica: elige una configuración de pensamiento y un nivel de esfuerzo de nivel superior para cada conversación y mantenlos. Si algunos turnos necesitan más o menos pensamiento, usa un cambio de esfuerzo por mensaje, que está en beta, en los modelos que lo admitan. O dirige con prompts por mensaje. Ambos dejan intactos los puntos de interrupción de caché anteriores, mientras que un cambio en la configuración de pensamiento o en el nivel de esfuerzo de nivel superior podría no hacerlo.
El siguiente ejemplo demuestra la invalidación con un script de varios 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)
# Obtén el contenido del artículo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usa solo el texto suficiente para el almacenamiento en caché (primeros capítulos)
LARGE_TEXT = book_content[:10000]
# Sin indicación del sistema: el almacenamiento en caché va 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: establece la caché
print("First request - establishing cache")
response1 = client.messages.create(
model="claude-opus-5-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-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: distinto nivel de esfuerzo (se espera fallo de caché)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "low"},
messages=MESSAGES,
)
print(f"Third response usage: {response3.usage}")Esta es la salida del script (es posible que veas números ligeramente diferentes):
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 }Con el punto de interrupción de caché en el arreglo de mensajes, cambiar el esfuerzo de medium, el valor predeterminado en Claude Opus 5.5, a low lo invalida: la tercera solicitud muestra cache_creation_input_tokens=3546 y cache_read_input_tokens=0 donde la segunda mostraba una lectura completa de la caché.
Control de costos
No estableces un presupuesto de tokens de pensamiento. Dos controles acotan el costo:
max_tokenses un límite estricto de 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 del turno tiene su propiomax_tokens, por lo que no acota el gasto de todo el turno.effortes una orientación flexible sobre cuánto de esa salida asigna Claude al pensamiento. Moldea el comportamiento, pero no garantiza un número de tokens.
Como el pensamiento cuenta para max_tokens, establécelo lo suficientemente alto como 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 empieza 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 soluciones:
- Aumenta
max_tokenspara dar al modelo más espacio para el pensamiento más la respuesta. - Reduce el nivel de esfuerzo para que Claude piense menos y deje más presupuesto para el texto de respuesta.
Cuál es la adecuada 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, reduce el esfuerzo.
Precios
El pensamiento genera cargos por:
- Los tokens que Claude usa mientras piensa (facturados como tokens de salida)
- Los bloques de pensamiento de turnos anteriores del asistente que permanecen en el contexto, según el valor predeterminado de preservación: todos los turnos de forma predeterminada en los modelos que los conservan todos, solo el último turno en los demás (facturados como tokens de entrada)
- Los 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:
display: "summarized" | display: "omitted" | |
|---|---|---|
| Tokens de entrada | Los tokens de tu solicitud original | Igual que con summarized |
| Tokens de salida (facturados) | Todos los tokens de pensamiento que Claude generó internamente | Igual que con summarized |
| Tokens de salida (visibles) | El texto de pensamiento resumido | Cero tokens de pensamiento (el campo thinking está vacío) |
| Generación del resumen | Sin cargo | No aplica |
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 sin procesar 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 parte de la salida que no es razonamiento. Al usar streaming, este desglose aparece solo en el evento message_delta final.
{
"usage": {
"input_tokens": 25,
"output_tokens": 348,
"output_tokens_details": {
"thinking_tokens": 312
}
}
}output_tokens sigue siendo el total inclusivo y oficial utilizado para la facturación. output_tokens_details es un desglose de solo lectura para observabilidad. Para obtener información completa sobre precios, incluidas las tarifas base, las escrituras en caché, los aciertos de caché y los tokens de salida, consulta Precios.
Próximos pasos
Activa el pensamiento, lee la salida del pensamiento y verifica la compatibilidad por modelo.
Conserva los bloques de pensamiento entre llamadas a herramientas y gestiona el pensamiento en conversaciones de varios turnos.
Controla cuánto pensamiento y cuánta salida asigna Claude a cada solicitud.
¿Te resultó útil esta página?