Pensamiento adaptativo

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

El pensamiento adaptativo es la forma recomendada de usar pensamiento extendido con Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6, y es el modo predeterminado en Claude Mythos Preview (donde se aplica automáticamente cuando thinking no está establecido). En lugar de establecer manualmente un presupuesto de tokens de pensamiento, el pensamiento adaptativo permite que Claude determine dinámicamente cuándo y cuánto usar el pensamiento extendido en función de la complejidad de cada solicitud. En Claude Opus 4.7, el pensamiento adaptativo es el único modo de pensamiento soportado; thinking: {type: "enabled", budget_tokens: N} manual ya no se acepta.

El pensamiento adaptativo puede proporcionar un mejor rendimiento que el pensamiento extendido con un budget_tokens fijo para muchas cargas de trabajo, especialmente tareas bimodales y flujos de trabajo de agentes de largo horizonte. No se requiere encabezado beta.

Si tu carga de trabajo requiere latencia predecible o control preciso sobre los costos de pensamiento, el pensamiento extendido con budget_tokens sigue siendo funcional en Claude Opus 4.6 y Claude Sonnet 4.6 pero está deprecado y ya no se recomienda. Consulta la advertencia a continuación.

Modelos soportados

El pensamiento adaptativo es soportado en los siguientes modelos:

Claude Mythos Preview (claude-mythos-preview), el pensamiento adaptativo es el predeterminado; thinking: {type: "disabled"} no es soportado
Claude Opus 4.7 (claude-opus-4-7), el pensamiento adaptativo es el único modo de pensamiento soportado. El pensamiento está desactivado a menos que establezca explícitamente thinking: {type: "adaptive"} en tu solicitud; thinking: {type: "enabled"} manual se rechaza con un error 400.
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)

thinking.type: "enabled" y budget_tokens están deprecados en Opus 4.6 y Sonnet 4.6 y se eliminarán en una futura versión del modelo. Usa thinking.type: "adaptive" con el parámetro effort en su lugar. Las configuraciones existentes de budget_tokens siguen siendo funcionales pero ya no se recomiendan; planifica migrar.

Los modelos más antiguos (Sonnet 4.5, Opus 4.5, etc.) no soportan pensamiento adaptativo y requieren thinking.type: "enabled" con budget_tokens.

Cómo funciona el pensamiento adaptativo

En modo adaptativo, el pensamiento es opcional para el modelo. Claude evalúa la complejidad de cada solicitud y determina si debe usar pensamiento extendido y cuánto. En el nivel de esfuerzo predeterminado (high), Claude casi siempre piensa. En niveles de esfuerzo más bajos, Claude puede omitir el pensamiento para problemas más simples.

El pensamiento adaptativo también habilita automáticamente pensamiento intercalado. Esto significa que Claude puede pensar entre llamadas de herramientas, lo que lo hace especialmente efectivo para flujos de trabajo de agentes.

Cómo usar el pensamiento adaptativo

Establece thinking.type a "adaptive" en tu solicitud de API:

Pensamiento adaptativo con el parámetro de esfuerzo

Puedes combinar el pensamiento adaptativo con el parámetro de esfuerzo para guiar cuánto piensa Claude. El nivel de esfuerzo actúa como orientación suave para la asignación de pensamiento de Claude:

Nivel de esfuerzo	Comportamiento de pensamiento
`max`	Claude siempre piensa sin restricciones en la profundidad del pensamiento. Disponible en Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6.
`xhigh`	Claude siempre piensa profundamente con exploración extendida. Disponible en Claude Opus 4.7.
`high` (predeterminado)	Claude siempre piensa. Proporciona razonamiento profundo en tareas complejas.
`medium`	Claude usa pensamiento moderado. Puede omitir el pensamiento para consultas muy simples.
`low`	Claude minimiza el pensamiento. Omite el pensamiento para tareas simples donde la velocidad es lo más importante.

Transmisión con pensamiento adaptativo

El pensamiento adaptativo funciona sin problemas con transmisión. Los bloques de pensamiento se transmiten a través de eventos thinking_delta al igual que el modo de pensamiento manual:

Pensamiento adaptativo vs manual vs deshabilitado

Modo	Configuración	Disponibilidad	Cuándo usar
Adaptativo	`thinking: {type: "adaptive"}`	Claude Mythos Preview (predeterminado), Opus 4.7 (único modo), Opus 4.6, Sonnet 4.6	Claude determina cuándo y cuánto usar pensamiento extendido. Usa `effort` para guiar.
Manual	`thinking: {type: "enabled", budget_tokens: N}`	Todos los modelos excepto Claude Opus 4.7 (rechazado). Deprecado en Opus 4.6 y Sonnet 4.6 (considera modo adaptativo en su lugar).	Cuando necesitas control preciso sobre el gasto de tokens de pensamiento.
Deshabilitado	Omite el parámetro `thinking` o pasa `{type: "disabled"}`	Todos los modelos excepto Claude Mythos Preview	Cuando no necesitas pensamiento extendido y quieres la latencia más baja.

El pensamiento adaptativo está disponible en Claude Mythos Preview, Claude Opus 4.7, Opus 4.6 y Sonnet 4.6. En Mythos Preview, el pensamiento adaptativo es el predeterminado y se aplica automáticamente cuando thinking no está establecido. En Claude Opus 4.7, el pensamiento adaptativo es el único modo soportado y type: "enabled" con budget_tokens se rechaza. Los modelos más antiguos solo soportan type: "enabled" con budget_tokens. En Opus 4.6 y Sonnet 4.6, type: "enabled" con budget_tokens sigue siendo funcional pero está deprecado.

Disponibilidad de pensamiento intercalado por modo:

Modo adaptativo: El pensamiento intercalado se habilita automáticamente en Claude Mythos Preview, Claude Opus 4.7, Opus 4.6 y Sonnet 4.6. En Mythos Preview y Opus 4.7, el razonamiento entre herramientas siempre vive dentro de bloques de pensamiento.
Modo manual en Sonnet 4.6: El pensamiento intercalado funciona a través del encabezado beta interleaved-thinking-2025-05-14.
Modo manual en Opus 4.6: El pensamiento intercalado no está disponible. Si tu flujo de trabajo de agente requiere pensamiento entre llamadas de herramientas en Opus 4.6, usa modo adaptativo.

Consideraciones importantes

Cambios de validación

Cuando se usa pensamiento adaptativo, los turnos anteriores del asistente no necesitan comenzar con bloques de pensamiento. Esto es más flexible que el modo manual, donde la API requiere que los turnos con pensamiento habilitado comiencen con un bloque de pensamiento.

Almacenamiento en caché de indicaciones

Las solicitudes consecutivas que usan pensamiento adaptive preservan los puntos de ruptura de almacenamiento en caché de indicaciones. Sin embargo, cambiar entre modos de pensamiento adaptive y enabled/disabled rompe los puntos de ruptura de caché para mensajes. Los indicadores del sistema y las definiciones de herramientas permanecen en caché independientemente de los cambios de modo.

Ajuste del comportamiento de pensamiento

El comportamiento de activación del pensamiento adaptativo es indicable. Si Claude está pensando más o menos a menudo de lo que te gustaría, puedes agregar orientación 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 multi-step reasoning. When in doubt, respond directly.

Dirigir a Claude a pensar menos a menudo puede reducir la calidad en tareas que se benefician del razonamiento. Mide el impacto en tus cargas de trabajo específicas antes de implementar ajustes basados en indicaciones en producción. Considera probar primero con niveles de esfuerzo más bajos.

Control de costos

Usa max_tokens como límite duro en la salida total (pensamiento + texto de respuesta). El parámetro effort proporciona orientación suave adicional sobre cuánto pensamiento asigna Claude. Juntos, estos te dan control efectivo sobre el costo.

En niveles de esfuerzo high y max, Claude puede pensar más extensamente y es más probable que agote el presupuesto de max_tokens. Si observas stop_reason: "max_tokens" en respuestas, considera aumentar max_tokens para dar más espacio al modelo, o bajar el nivel de esfuerzo.

Trabajar con bloques de pensamiento

Los siguientes conceptos se aplican a todos los modelos que soportan pensamiento extendido, independientemente de si usas modo adaptativo o manual.

Pensamiento resumido

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

Here are some important considerations for summarized thinking:

You're charged for the full thinking tokens generated by the original request, not the summary tokens.
The billed output token count will not match the count of tokens you see in the response.
On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience.
Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

In rare cases where you need access to full thinking output for Claude 4 models, contact our sales team.

Controlando la visualización del pensamiento

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

"summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
"omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
display is invalid with thinking.type: "disabled" (there is nothing to display).
When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

The signature field is identical whether display is "summarized" or "omitted". Switching display values between turns in a conversation is supported.

En Claude Opus 4.7, thinking.display tiene como predeterminado "omitted". Los bloques de pensamiento aún aparecen en el flujo de respuesta, pero su campo thinking está vacío a menos que optes explícitamente. Este es un cambio silencioso de Claude Opus 4.6, donde el predeterminado era "summarized". Para restaurar el texto de pensamiento resumido en Claude Opus 4.7, establece thinking.display a "summarized" explícitamente:

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Para ejemplos de código y comportamiento de transmisión con display: "omitted", consulta Controlando la visualización del pensamiento en la página de pensamiento extendido. Los ejemplos allí usan type: "enabled"; con pensamiento adaptativo, usa:

thinking = {"type": "adaptive", "display": "omitted"}

Encriptación de pensamiento

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

It is only strictly necessary to send back thinking blocks when using tools with extended thinking. Otherwise you can omit thinking blocks from previous turns. If you pass them back, whether the API keeps or strips them depends on the model: Opus 4.5+ and Sonnet 4.6+ keep them in context by default; earlier Opus/Sonnet models and all Haiku models strip them. See context editing to configure this.

If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.

Here are some important considerations on thinking encryption:

When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
signature values are significantly longer in Claude 4 models than in previous models.
The signature field is an opaque field and should not be interpreted or parsed.
signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Precios

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

Tokens used during thinking (output tokens)
Thinking blocks from prior assistant turns kept in context: only the last turn on earlier Opus/Sonnet models and all Haiku models; all turns by default on Opus 4.5+ and Sonnet 4.6+ (input tokens)
Standard text output tokens

When extended thinking is enabled, a specialized system prompt is automatically included to support this feature.

When using summarized thinking:

Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
Output tokens (billed): The original thinking tokens that Claude generated internally
Output tokens (visible): The summarized thinking tokens you see in the response
No charge: Tokens used to generate the summary

When using display: "omitted":

Input tokens: Tokens in your original request (same as summarized)
Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
Output tokens (visible): Zero thinking tokens (the thinking field is empty)

The billed output token count will not match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.

Temas adicionales

La página de pensamiento extendido cubre varios temas con más detalle con ejemplos de código específicos del modo:

Uso de herramientas con pensamiento: Las mismas reglas se aplican para pensamiento adaptativo: preserva bloques de pensamiento entre llamadas de herramientas y ten en cuenta las limitaciones de tool_choice cuando el pensamiento está activo.
Almacenamiento en caché de indicaciones: Con pensamiento adaptativo, las solicitudes consecutivas que usan el mismo modo de pensamiento preservan los puntos de ruptura de caché. Cambiar entre modos adaptive y enabled/disabled rompe los puntos de ruptura de caché para mensajes (los indicadores del sistema y las definiciones de herramientas permanecen en caché).
Ventanas de contexto: Cómo los tokens de pensamiento interactúan con max_tokens y los límites de la ventana de contexto.

Próximos pasos

Pensamiento extendido

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.content[0].text)

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)