--- title: Pensamiento url: https://platform.claude.com/docs/es/build-with-claude/thinking description: "Comprende cómo funciona el pensamiento de Claude: actívalo, lee la salida del pensamiento, controla su profundidad con el esfuerzo y usa el pensamiento con herramientas, almacenamiento en caché y streaming." --- Para saber cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention). Un modelo que responde en una sola pasada tiene que acertar en todo al primer intento: sin borradores, sin verificaciones y sin cambiar de rumbo a mitad de camino. En una demostración, un error complicado o una tarea agéntica larga, el primer enfoque a menudo no es el mejor. El "thinking" (pensamiento) elimina esa restricción. Cuando el pensamiento está activo, Claude trabaja el problema con sus propias palabras antes de responder: reformula lo que se le pide, prueba enfoques, verifica resultados intermedios y abandona los caminos que no se sostienen. Ese pensamiento inicial llega en bloques de contenido `thinking` antes de la respuesta, y Claude se apoya en él para producir la respuesta final. Por eso el pensamiento mejora el rendimiento en tareas complejas como matemáticas, programación, análisis y trabajo agéntico de larga duración. En esas tareas, la calidad de la respuesta depende de un trabajo intermedio que, de otro modo, se comprimiría en la propia respuesta o se omitiría. El pensamiento tiene un costo: los tokens que Claude gasta razonando se facturan como tokens de salida, incluso cuando el texto del pensamiento no se te devuelve, y cuentan para `max_tokens` junto con el texto de la respuesta. Esta página explica cómo se comporta el pensamiento en toda la superficie de la API: cómo activarlo, cómo leer su salida y cómo gestionar sus interacciones con las herramientas, el streaming, el almacenamiento en caché y la "context window" (ventana de contexto). ## Cómo funciona el pensamiento ![Diagrama: Claude determina si debe pensar al inicio, puede pensar entre llamadas a herramientas y devuelve bloques de pensamiento antes del texto](https://platform.claude.com/docs/es/images/how-thinking-works.svg) Si Claude piensa en una solicitud determinada, y con qué profundidad, depende de tu configuración de pensamiento y de la complejidad de la solicitud. Así se ve el pensamiento inicial en una respuesta: uno o más bloques de contenido `thinking` llegan antes de los bloques `text`. El bloque de pensamiento sigue siendo contenido generado, como el bloque `text` que lo sigue, pero está separado de la respuesta canónica. Cada bloque de pensamiento también incluye un campo `signature`, una copia cifrada del razonamiento completo que devuelves sin cambios en conversaciones de varios turnos y de uso de herramientas (consulta [Cifrado del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-encryption)): ```json { "content": [ { "type": "thinking", "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...", "signature": "WaUjzkypQ2mUEVM36O2Txu...." }, { "type": "text", "text": "Based on my analysis..." } ] } ``` No siempre ves este texto, y lo que ves nunca es la cadena de pensamiento sin procesar: el texto de un bloque de pensamiento es un [resumen del razonamiento de Claude](https://platform.claude.com/docs/es/build-with-claude/thinking#summarized-thinking). El campo `display` de la configuración de pensamiento controla si ese resumen se devuelve o no: `"summarized"` lo devuelve, mientras que `"omitted"`, el valor predeterminado en muchos modelos, devuelve bloques de pensamiento con un campo `thinking` vacío. En cualquier caso, el bloque se factura igual y se devuelve igual en conversaciones de varios turnos. Consulta [Controlar la visualización del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#controlling-thinking-display) para conocer los valores predeterminados por modelo y más detalles. Si Claude usa herramientas, el pensamiento también puede aparecer entre llamadas a herramientas. Consulta [Pensamiento con uso de herramientas](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-with-tool-use). Para el formato completo de la respuesta, consulta la [referencia de la API de Messages](https://platform.claude.com/docs/es/api/messages/create). ## Configurar el pensamiento En la mayoría de los modelos, el pensamiento está activado de forma predeterminada o a un parámetro de distancia. La siguiente tabla muestra qué hace cada modelo con cada valor de `thinking` que puede enviar una solicitud. Un error 400 significa que la API rechaza la solicitud, y [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting) incluye cada error y su solución. | Modelo | Sin campo `thinking` | `"adaptive"` | `"enabled"` con `budget_tokens` | `"between_tools"` | `"disabled"` | | --------------------- | ----------------------- | ---------------------- | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | | Claude Opus 5.5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Error 400 | | Claude Sonnet 5.5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Pensamiento inicial desactivado con esfuerzo `high` o inferior | Error 400 | | Claude Haiku 5.5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Pensamiento desactivado con esfuerzo `high` o inferior | | Claude Fable 5.1 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Error 400 | | Claude Mythos 5.1 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Error 400 | | Claude Fable 5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Error 400 | | Claude Mythos 5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Error 400 | | Claude Opus 5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Pensamiento desactivado con esfuerzo `high` o inferior | | Claude Sonnet 5 | Pensamiento adaptativo | Pensamiento adaptativo | Error 400 | Error 400 | Pensamiento desactivado | | Claude Opus 4.8 | Pensamiento desactivado | Pensamiento adaptativo | Error 400 | Error 400 | Pensamiento desactivado | | Claude Opus 4.7 | Pensamiento desactivado | Pensamiento adaptativo | Error 400 | Error 400 | Pensamiento desactivado | | Claude Mythos Preview | Pensamiento adaptativo | Pensamiento adaptativo | Pensamiento extendido | Error 400 | Error 400 | | Claude Opus 4.6 | Pensamiento desactivado | Pensamiento adaptativo | Pensamiento extendido (obsoleto) | Error 400 | Pensamiento desactivado | | Claude Sonnet 4.6 | Pensamiento desactivado | Pensamiento adaptativo | Pensamiento extendido (obsoleto) | Error 400 | Pensamiento desactivado | | Claude Opus 4.5 | Pensamiento desactivado | Error 400 | Pensamiento extendido | Error 400 | Pensamiento desactivado | | Claude Sonnet 4.5 | Pensamiento desactivado | Error 400 | Pensamiento extendido | Error 400 | Pensamiento desactivado | | Claude Haiku 4.5 | Pensamiento desactivado | Error 400 | Pensamiento extendido | Error 400 | Pensamiento desactivado | En la tabla, "con esfuerzo `high` o inferior" significa que la solicitud funciona con esfuerzo `low`, `medium` y `high`, y devuelve un error 400 con `xhigh` o `max`. En Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview y Claude Haiku 5.5, el pensamiento ya está activado y no necesita configuración. `display` tiene como valor predeterminado `"omitted"` en estos modelos, por lo que el texto del pensamiento permanece oculto hasta que lo habilites. Habilítalo con `thinking: {"type": "adaptive", "display": "summarized"}`, como hacen los siguientes ejemplos. En Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 y Claude Sonnet 4.6, el pensamiento está desactivado hasta que configures `thinking: {type: "adaptive"}`, lo que permite a Claude determinar cuándo y con qué profundidad pensar según la solicitud. La misma solicitud, cambiando la [cadena del modelo](https://platform.claude.com/docs/es/models/overview), lo activa allí. Los siguientes ejemplos configuran `display: "summarized"` para que el texto del pensamiento sea visible y usan un `max_tokens` holgado: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --transform content \ --format yaml ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) for block in response.content: match block.type: case "thinking": print(f"\nThinking: {block.thinking}") case "text": print(f"\nResponse: {block.text}") ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] }); for (const block of response.content) { switch (block.type) { case "thinking": console.log(`\nThinking: ${block.thinking}`); break; case "text": console.log(`\nResponse: ${block.text}`); break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [ new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" } ] }; var message = await client.Messages.Create(parameters); foreach (var block in message.Content) { if (block.TryPickThinking(out ThinkingBlock? thinking)) { Console.WriteLine($"\nThinking: {thinking.Thinking}"); } else if (block.TryPickText(out TextBlock? text)) { Console.WriteLine($"\nResponse: {text.Text}"); } } ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch v := block.AsAny().(type) { case anthropic.ThinkingBlock: fmt.Printf("\nThinking: %s", v.Thinking) case anthropic.TextBlock: fmt.Printf("\nResponse: %s", v.Text) } } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); Message response = client.messages().create(params); response.content().forEach(block -> { block.thinking().ifPresent(thinkingBlock -> IO.println("\nThinking: " + thinkingBlock.thinking()) ); block.text().ifPresent(textBlock -> IO.println("\nResponse: " + textBlock.text()) ); }); } ``` ```php PHP use Anthropic\Messages\TextBlock; use Anthropic\Messages\ThinkingBlock; $client = new Client(); $message = $client->messages->create( maxTokens: 16000, messages: [ [ 'role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?' ] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($message->content as $block) { switch (true) { case $block instanceof ThinkingBlock: echo "\nThinking: " . $block->thinking; break; case $block instanceof TextBlock: echo "\nResponse: " . $block->text; break; } } ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", # Un hash simple como este acepta display:. La clase tipada ThinkingConfigAdaptive # lo escribe display_ (con guion bajo final) para no ocultar Kernel#display de Ruby. # La solicitud sigue enviando display. display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) message.content.each do |block| case block when Anthropic::Models::ThinkingBlock puts "\nThinking: #{block.thinking}" when Anthropic::Models::TextBlock puts "\nResponse: #{block.text}" end end ``` Al ejecutar el ejemplo se imprime el pensamiento resumido y luego la respuesta: ```text Output wrap Thinking: Use Euclidean algorithm. 1071 = 2*462 + 147 462 = 3*147 + 21 147 = 7*21 + 0 GCD = 21 Response: ## Finding GCD of 1071 and 462 I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders... ``` Los tokens de pensamiento cuentan para `max_tokens`, así que configúralo lo suficientemente alto como para dejar espacio tanto para el pensamiento como para el texto de la respuesta. Consulta [Control de costos](https://platform.claude.com/docs/es/build-with-claude/thinking-steering-and-cost#cost-control) en la página de control del pensamiento y [El pensamiento y la ventana de contexto](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-the-context-window). ### Desactivar el pensamiento En Claude Sonnet 5, donde el pensamiento está activado de forma predeterminada, puedes desactivarlo: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 4096, "thinking": {"type": "disabled"}, "messages": [ { "role": "user", "content": "Summarize this article in one sentence." } ] }' ``` ```bash CLI ant messages create \ --model claude-sonnet-5 \ --max-tokens 4096 \ --thinking '{type: disabled}' \ --message '{role: user, content: "Summarize this article in one sentence."}' ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-5", max_tokens=4096, thinking={"type": "disabled"}, messages=[{"role": "user", "content": "Summarize this article in one sentence."}], ) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [{ role: "user", content: "Summarize this article in one sentence." }] }); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 4096, Thinking = new ThinkingConfigDisabled(), Messages = [ new() { Role = Role.User, Content = "Summarize this article in one sentence." } ] }; var message = await client.Messages.Create(parameters); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 4096, Thinking: anthropic.ThinkingConfigParamUnion{ OfDisabled: &anthropic.ThinkingConfigDisabledParam{}, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Summarize this article in one sentence.")), }, }) if err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigDisabled; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(4096L) .thinking(ThinkingConfigDisabled.builder().build()) .addUserMessage("Summarize this article in one sentence.") .build(); Message response = client.messages().create(params); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Summarize this article in one sentence.' ] ], model: 'claude-sonnet-5', thinking: ['type' => 'disabled'], ); ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [ { role: "user", content: "Summarize this article in one sentence." } ] ) ``` Claude Opus 5 también tiene el pensamiento activado de forma predeterminada y acepta `thinking: {type: "disabled"}` con un "[effort](https://platform.claude.com/docs/es/build-with-claude/effort)" (esfuerzo) `high` o inferior. Con esfuerzo `xhigh` o `max`, el pensamiento no se puede desactivar: las solicitudes que combinan `thinking: {type: "disabled"}` con esos niveles de esfuerzo devuelven un error 400. Esta restricción se aplica en cada solicitud. Con el pensamiento desactivado, Claude Opus 5 puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible. Consulta [Ejecutar con el pensamiento desactivado](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) para conocer mitigaciones mediante prompts. Claude Sonnet 5.5 también tiene el pensamiento activado de forma predeterminada y rechaza `thinking: {type: "disabled"}` con un error 400. Para desactivar el pensamiento inicial, envía `thinking: {type: "between_tools"}` en su lugar. Es la configuración de pensamiento más baja en Claude Sonnet 5.5 y se acepta con [esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) `high` o inferior. El modelo sigue devolviendo sus [actualizaciones de progreso entre llamadas a herramientas](https://platform.claude.com/docs/es/build-with-claude/thinking#progress-updates). Sin herramientas, la respuesta contiene solo texto, como con `disabled` en Claude Sonnet 5. Consulta [Ejecución sin pensamiento previo](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) para obtener orientación sobre prompts. Claude Haiku 5.5 también tiene el pensamiento activado de forma predeterminada y acepta `thinking: {type: "disabled"}` con un [esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) `high` o inferior. Con esfuerzo `xhigh` o `max`, esa combinación devuelve un error 400. Para obtener menos pensamiento, reduce primero el nivel de esfuerzo. Con el pensamiento desactivado, el modelo puede omitir una llamada a herramienta que necesita cuando también solicitas salida JSON. Un [`output_config.effort` por mensaje](https://platform.claude.com/docs/es/build-with-claude/effort#change-effort-mid-conversation-beta) que difiera del nivel vigente también devuelve un error 400 mientras el pensamiento está desactivado. Consulta [Usa el esfuerzo para controlar el pensamiento](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) y [Usa el pensamiento adaptativo con salida JSON y tus propias herramientas](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools). Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 y Claude Mythos Preview rechazan `thinking: {type: "disabled"}`. El pensamiento no se puede desactivar en estos modelos. Para comprobar si un modelo acepta `"disabled"` antes de enviar una solicitud, lee su valor `capabilities.thinking.types.disabled.supported` desde la API de Models. [Uso de la API de Models](https://platform.claude.com/docs/es/models/overview#using-the-models-api) describe el campo. Si tu modelo solo admite pensamiento extendido (consulta la [tabla de configuración por modelo](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#supported-models)), configúralo con `type: "enabled"` y un valor de `budget_tokens` en su lugar. La página [Pensamiento extendido](https://platform.claude.com/docs/es/build-with-claude/extended-thinking) cubre esa configuración. Y si alguna configuración de pensamiento devuelve un error 400, [Solución de problemas del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting) relaciona cada mensaje de error con su solución. ## Leer la salida del pensamiento ### Controlar la visualización del pensamiento El campo `display` de la configuración de pensamiento controla cómo se devuelve el contenido del pensamiento en las respuestas de la API. `display` funciona en ambos modos: configúralo junto con `type: "adaptive"` o `type: "enabled"`. Acepta estos valores: * `"summarized"`: los bloques de pensamiento contienen texto de [pensamiento resumido](https://platform.claude.com/docs/es/build-with-claude/thinking#summarized-thinking), un resumen legible del razonamiento de Claude. Este es el valor predeterminado en Claude Opus 4.6, Claude Sonnet 4.6 y modelos anteriores. * `"omitted"`: los bloques de pensamiento se devuelven con un campo `thinking` vacío. El campo `signature` sigue conteniendo el pensamiento completo cifrado para la continuidad entre varios turnos (consulta [Cifrado del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-encryption)). Este es el valor predeterminado en Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, [Claude Mythos Preview](https://anthropic.com/glasswing) y Claude Haiku 5.5. * `"updates"` (beta): los bloques de razonamiento se devuelven con un campo `thinking` vacío, como con `"omitted"`, y las breves [actualizaciones de progreso](https://platform.claude.com/docs/es/build-with-claude/thinking#progress-updates) que algunos modelos escriben entre llamadas a herramientas se devuelven como texto legible. Requiere el encabezado beta `thinking-display-updates-2026-08-18`. Configura `display: "omitted"` cuando tu aplicación no muestre el contenido del pensamiento a los usuarios. El principal beneficio es un menor tiempo hasta el primer token de texto al hacer streaming: el servidor omite por completo el streaming de los tokens de pensamiento y entrega solo la firma, por lo que la respuesta de texto final comienza a transmitirse antes. Con `display: "omitted"`, la respuesta contiene bloques `thinking` con un campo `thinking` vacío: ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EosnCkYICxIMMb3LzNrMu..." }, { "type": "text", "text": "The answer is 12,231." } ] } ``` Ten en cuenta lo siguiente al trabajar con pensamiento omitido: * Se te siguen cobrando todos los tokens de pensamiento. Omitirlo reduce la latencia, no el costo. * Si devuelves bloques de pensamiento en conversaciones de varios turnos, devuélvelos sin cambios. El servidor descifra la `signature` para reconstruir el pensamiento original para la construcción del prompt (consulta [Preservar los bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#preserving-thinking-blocks)). Cualquier texto que coloques en el campo `thinking` de un bloque omitido que devuelvas se ignora. * `display` no es válido con `thinking.type: "disabled"` (no hay nada que mostrar) ni con `thinking.type: "between_tools"` (solo Claude Sonnet 5.5), que no acepta ningún otro campo. Con `between_tools`, las actualizaciones de progreso siguen devolviéndose con texto de resumen, como ocurre con `display: "updates"` (consulta [Actualizaciones de progreso](https://platform.claude.com/docs/es/build-with-claude/thinking#progress-updates)). * Al usar `thinking.type: "adaptive"` y el modelo omite el pensamiento para una solicitud simple, no se produce ningún bloque de pensamiento, independientemente de `display`. * Al hacer streaming con `display: "omitted"`, no se transmite texto de pensamiento. Cada bloque de pensamiento transmite un `thinking_delta` con una cadena `thinking` vacía y luego su `signature_delta`. Con `display: "updates"`, solo los [bloques de actualización de progreso](https://platform.claude.com/docs/es/build-with-claude/thinking#progress-updates) transmiten eventos `thinking_delta` que contienen texto. Consulta [Streaming del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#streaming-thinking) para ver la secuencia de eventos. El campo `signature` es idéntico sea cual sea el valor de `display` que configures. Se admite cambiar los valores de `display` entre turnos de una conversación. ### Pensamiento resumido Cuando `display` es `"summarized"`, el texto de pensamiento que recibes es un resumen del proceso de pensamiento completo de Claude en lugar de la cadena de pensamiento sin procesar. El pensamiento resumido ofrece todos los beneficios de inteligencia del pensamiento y, al mismo tiempo, evita el uso indebido. Ninguna configuración de `display` devuelve la cadena de pensamiento sin procesar. Ten en cuenta lo siguiente al trabajar con pensamiento resumido: * Se te cobran todos los tokens de pensamiento generados por la solicitud original, no los tokens del resumen. El recuento de tokens de salida facturados no coincide con el recuento de tokens que ves en la respuesta. * En Claude Opus 4.6, Claude Sonnet 4.6 y modelos anteriores, las primeras líneas de la salida del pensamiento son más detalladas y proporcionan un razonamiento minucioso que resulta especialmente útil para fines de ingeniería de prompts. [Claude Mythos Preview](https://anthropic.com/glasswing) resume desde el primer token, por lo que sus bloques de pensamiento no muestran este preámbulo detallado. * El resumen conserva las ideas clave del proceso de pensamiento de Claude con una latencia adicional mínima, por lo que los resúmenes pueden transmitirse a medida que llegan. * El resumen lo genera un modelo diferente del que usas en tus solicitudes. El modelo que piensa no ve la salida resumida. * A medida que Anthropic busca mejorar la función de pensamiento, el comportamiento del resumen está sujeto a cambios. En los casos poco frecuentes en que necesites acceso a la salida completa del pensamiento, [contacta al equipo de ventas de Anthropic](mailto:sales@anthropic.com). Para ver el razonamiento del modelo, lee los bloques `thinking` en lugar de pedir el razonamiento en el texto de la respuesta. En Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 y Claude Fable 5, una solicitud que intente obtener el razonamiento interno del modelo como parte del texto de la respuesta puede rechazarse con `stop_details.category: "reasoning_extraction"`. Consulta [Categorías de rechazo](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#refusal-response) para la referencia del campo y [Mantén el razonamiento en bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks) para saber qué pedir en su lugar. ### Streaming del pensamiento El pensamiento funciona con [streaming](https://platform.claude.com/docs/es/build-with-claude/streaming). Los bloques de pensamiento se transmiten como eventos `thinking_delta` dentro de eventos `content_block_delta`, seguidos de un único evento `signature_delta` justo antes del `content_block_stop` del bloque. Los bloques de texto se transmiten después, como de costumbre. ![Diagrama de la secuencia de eventos de streaming con pensamiento: el bloque de pensamiento se abre, los deltas de pensamiento contienen texto solo cuando la configuración de display devuelve texto (summarized, o updates para los bloques de actualización de progreso), un único delta de firma cierra el bloque y luego se transmiten los deltas de texto](https://platform.claude.com/docs/es/images/how-thinking-streams.svg) Los siguientes ejemplos transmiten una respuesta con pensamiento adaptativo e imprimen los deltas de pensamiento y de texto a medida que llegan: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "stream": true, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --stream \ --format jsonl ``` ```python Python client = anthropic.Anthropic() with client.messages.stream( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) as stream: for event in stream: match event.type: case "content_block_start": print(f"\nStarting {event.content_block.type} block...") case "content_block_delta": delta = event.delta match delta.type: case "thinking_delta": print(delta.thinking, end="", flush=True) case "text_delta": print(delta.text, end="", flush=True) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }] }); for await (const event of stream) { switch (event.type) { case "content_block_start": console.log(`\nStarting ${event.content_block.type} block...`); break; case "content_block_delta": switch (event.delta.type) { case "thinking_delta": process.stdout.write(event.delta.thinking); break; case "text_delta": process.stdout.write(event.delta.text); break; } break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }] }; await foreach (var rawEvent in client.Messages.CreateStreaming(parameters)) { if (rawEvent.TryPickContentBlockStart(out var start)) { Console.WriteLine($"\nStarting {start.ContentBlock.Type} block..."); } else if (rawEvent.TryPickContentBlockDelta(out var delta)) { if (delta.Delta.TryPickThinking(out var thinkingDelta)) { Console.Write(thinkingDelta.Thinking); } else if (delta.Delta.TryPickText(out var textDelta)) { Console.Write(textDelta.Text); } } } ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) for stream.Next() { event := stream.Current() switch eventVariant := event.AsAny().(type) { case anthropic.ContentBlockStartEvent: fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type) case anthropic.ContentBlockDeltaEvent: switch deltaVariant := eventVariant.Delta.AsAny().(type) { case anthropic.ThinkingDelta: fmt.Print(deltaVariant.Thinking) case anthropic.TextDelta: fmt.Print(deltaVariant.Text) } } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(event -> { switch (event.type().value()) { case CONTENT_BLOCK_START -> { var startEvent = event.asContentBlockStart(); var block = startEvent.contentBlock(); switch (block.type().value()) { case THINKING -> IO.println("\nStarting thinking block..."); case TEXT -> IO.println("\nStarting text block..."); } } case CONTENT_BLOCK_DELTA -> { var deltaEvent = event.asContentBlockDelta(); deltaEvent.delta().thinking().ifPresent(td -> IO.print(td.thinking()) ); deltaEvent.delta().text().ifPresent(td -> IO.print(td.text()) ); } } }); } } ``` ```php PHP use Anthropic\Messages\RawContentBlockDeltaEvent; use Anthropic\Messages\RawContentBlockStartEvent; use Anthropic\Messages\TextDelta; use Anthropic\Messages\ThinkingDelta; $client = new Client(); $stream = $client->messages->createStream( maxTokens: 16000, messages: [ ['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?'] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($stream as $event) { switch (true) { case $event instanceof RawContentBlockStartEvent: echo "\nStarting {$event->contentBlock->type} block...\n"; break; case $event instanceof RawContentBlockDeltaEvent: switch (true) { case $event->delta instanceof ThinkingDelta: echo $event->delta->thinking; break; case $event->delta instanceof TextDelta: echo $event->delta->text; break; } break; } } ``` ```ruby Ruby client = Anthropic::Client.new stream = client.messages.stream( model: "claude-opus-5-5", max_tokens: 16000, # Un hash simple como este acepta display:. La clase tipada ThinkingConfigAdaptive # lo escribe display_ (con guion bajo final) para no ocultar Kernel#display de Ruby. # La solicitud igualmente envía display. thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) stream.each do |event| case event when Anthropic::Streaming::ThinkingEvent print event.thinking when Anthropic::Streaming::TextEvent print event.text end end ``` Para reensamblar bloques de pensamiento completos con sus firmas después del streaming, usa el helper de acumulación de mensajes de tu SDK, `stream.get_final_message()` (typescript: `stream.finalMessage()`; ruby: `stream.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`), en lugar de concatenar los deltas tú mismo. ```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null}} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}} // Additional thinking deltas... event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}} event: content_block_stop data: {"type": "content_block_stop", "index": 0} event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}} event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}} // Additional text deltas... event: content_block_stop data: {"type": "content_block_stop", "index": 1} event: message_delta data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}} event: message_stop data: {"type": "message_stop"} ``` Cuando se configura `display: "omitted"`, el bloque de pensamiento se abre, llega un `thinking_delta` con una cadena `thinking` vacía, le sigue un único `signature_delta` y el bloque se cierra. El streaming de texto comienza inmediatamente después: ```sse Output event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}} event: content_block_stop data: {"type":"content_block_stop","index":0} event: content_block_start data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}} ``` Con `display: "updates"` (beta), los bloques de razonamiento se transmiten igual que con `"omitted"`. Cada [bloque de actualización de progreso](https://platform.claude.com/docs/es/build-with-claude/thinking#progress-updates) transmite su texto como eventos `thinking_delta` antes del bloque `tool_use` que introduce. Es normal una pausa de varios segundos antes de que se abra el bloque de actualización de progreso: ```sse Output event: content_block_start data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}} event: content_block_stop data: {"type":"content_block_stop","index":1} event: content_block_start data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}} ``` Con `"updates"`, trata un bloque como una actualización de progreso en cuanto uno de sus eventos `thinking_delta` contenga texto no vacío. Al usar streaming con el pensamiento habilitado, es posible que notes que el texto a veces llega en fragmentos más grandes que se alternan con una entrega más pequeña, token por token. Este es un comportamiento esperado, especialmente para el contenido del pensamiento. El sistema de streaming procesa el contenido en lotes, lo que puede retrasar y agrupar los eventos de streaming en este patrón de entrega "fragmentado". Para conocer la mecánica general del streaming, consulta [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming). ## Pensamiento y esfuerzo El parámetro `thinking` controla si Claude piensa en [bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking) antes de responder; el parámetro `effort` controla cuánto trabajo dedica Claude a la respuesta completa, lo que en modo adaptativo incluye con qué frecuencia y con qué profundidad piensa. No pases `adaptive` como valor de `effort`: `adaptive` es un modo de pensamiento, no un nivel de esfuerzo. Para saber qué hace cada nivel de esfuerzo en el comportamiento del pensamiento, consulta la [tabla de comportamiento del pensamiento por nivel](https://platform.claude.com/docs/es/build-with-claude/thinking-steering-and-cost#effort-levels) en la página [Dirigir el pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-steering-and-cost). La página [Esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) documenta el parámetro en sí, incluidos los niveles que admite cada modelo. En Claude Opus 4.5, el único modelo exclusivo de pensamiento extendido que admite esfuerzo, el esfuerzo se combina con `budget_tokens`. Consulta [Reglas y ajuste del presupuesto](https://platform.claude.com/docs/es/build-with-claude/extended-thinking#budget-rules-and-tuning). Con los dos controles separados de esta manera, elige el que se ajuste a tu objetivo: * **Menor costo o latencia en una carga de trabajo con pensamiento habilitado:** reduce primero `effort`. Reduce toda la respuesta, incluido el pensamiento. * **Claude piensa con muy poca frecuencia o con poca profundidad:** aumenta `effort`, o consulta [Dirigir con qué frecuencia piensa Claude](https://platform.claude.com/docs/es/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior) en la página de control del pensamiento. * **Necesitas el pensamiento completamente desactivado:** usa `thinking: {type: "disabled"}` en los modelos que lo permiten (consulta la [tabla de configuración por modelo](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#supported-models)). Claude Sonnet 5.5 rechaza `"disabled"`. Su configuración más baja es `thinking: {type: "between_tools"}`, que desactiva el pensamiento inicial. * **Necesitas un límite estricto de gasto:** usa `max_tokens`. El esfuerzo es una orientación flexible. `max_tokens` es un límite estricto. ## Pensamiento con uso de herramientas El pensamiento funciona junto con el "[tool use](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview)" (uso de herramientas), lo que permite a Claude razonar sobre la selección de herramientas y procesar los resultados de las herramientas. Se aplican dos restricciones: 1. **Limitación de la elección de herramientas (modo manual):** el uso de herramientas con pensamiento extendido manual (`thinking: {type: "enabled"}`) solo admite `tool_choice: {"type": "auto"}` (el valor predeterminado) o `tool_choice: {"type": "none"}`. Usar `tool_choice: {"type": "any"}` o `tool_choice: {"type": "tool", "name": "..."}` produce un error porque estas opciones fuerzan el uso de herramientas, lo cual es incompatible con el pensamiento extendido manual. El pensamiento adaptativo, incluso en modelos donde el pensamiento está activado de forma predeterminada, admite el uso forzado de herramientas, excepto en Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1 (consulta [Prellenado de respuestas y uso forzado de herramientas](https://platform.claude.com/docs/es/build-with-claude/thinking#limits-and-feature-compatibility)). Donde se acepta el uso forzado de herramientas, la respuesta comienza con la llamada a la herramienta y no tiene bloque `thinking`. 2. **Preservar los bloques de pensamiento:** cuando devuelves resultados de herramientas, debes devolver a la API los bloques de pensamiento del mensaje del asistente, completos y sin modificar. Consulta [Preservar los bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#preserving-thinking-blocks). **Un bucle de uso de herramientas es un solo turno del asistente.** Desde la perspectiva del modelo, un turno del asistente no se completa hasta que Claude termina su respuesta completa, que puede incluir varias llamadas a herramientas y sus resultados. Toda esta secuencia es un único turno del asistente: ```text wrap User: "What's the weather in Paris?" Assistant: [thinking] + [tool_use: get_weather] User: [tool_result: "20°C, sunny"] Assistant: [text: "The weather in Paris is 20°C and sunny"] ``` Todo el turno se ejecuta en un único modo de pensamiento: no puedes alternar el pensamiento a mitad de un turno, incluso durante el bucle de uso de herramientas. En el modo extendido (manual), la API además exige que el turno final del asistente de una solicitud con pensamiento habilitado comience con un bloque de pensamiento. El modo adaptativo flexibiliza esto: ningún turno del asistente necesita comenzar con uno. **Los conflictos a mitad de turno se degradan de forma controlada.** Si alternas el pensamiento a mitad de un turno (por ejemplo, entre enviar una llamada a herramienta y devolver su resultado), la API no devuelve un error. En su lugar, desactiva silenciosamente el pensamiento para esa solicitud. Para preservar la calidad del modelo, la API puede eliminar bloques de pensamiento que crearían una estructura de turno no válida, o desactivar el pensamiento cuando el historial de la conversación es incompatible con tener el pensamiento habilitado. Para confirmar si el pensamiento estuvo activo, comprueba la presencia de bloques `thinking` en la respuesta. **Alterna entre turnos, no dentro de ellos.** Planifica tu estrategia de pensamiento al inicio de cada turno. Completa el turno del asistente y luego cambia la configuración de pensamiento para el siguiente: ```text wrap User: "What's the weather?" Assistant: [tool_use] (thinking disabled) User: [tool_result] Assistant: [text: "It's sunny"] User: "What about tomorrow?" Assistant: [thinking] + [text: "..."] (thinking enabled - new turn) ``` Alternar los modos de pensamiento también invalida el almacenamiento en caché de prompts. Consulta [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching). ### Preservar los bloques de pensamiento Cuando Claude invoca una herramienta, pausa la construcción de su respuesta para esperar información externa. Cuando devuelves el resultado de la herramienta, Claude sigue construyendo esa misma respuesta, por lo que su razonamiento anterior debe seguir presente. Devuelve a la API cada bloque `thinking` completo y sin modificar, junto con el bloque `tool_use` al que acompañaba. Esto es importante por dos razones: 1. **Continuidad del razonamiento:** los bloques de pensamiento recogen el razonamiento paso a paso que llevó a las solicitudes de herramientas. Incluirlos permite a Claude seguir razonando desde donde lo dejó. 2. **Mantenimiento del contexto:** en la estructura de la API, los resultados de herramientas aparecen como mensajes de usuario, pero forman parte de un único flujo de razonamiento continuo. Preservar los bloques de pensamiento mantiene ese flujo entre llamadas a la API. En resumen: * **Obligatorio:** dentro de un turno de uso de herramientas, devuelve los bloques de pensamiento. * **Recomendado:** entre turnos, devuélvelo todo. * **Permitido:** fuera del uso de herramientas, omite el pensamiento de los turnos anteriores. No necesitas eliminar tú mismo el pensamiento antiguo. Devuelve todos los bloques de pensamiento en las conversaciones de varios turnos: la API los filtra automáticamente, conserva los bloques necesarios para preservar el razonamiento del modelo y solo factura como tokens de entrada los bloques que realmente se muestran a Claude. Los bloques de turnos anteriores que se conservan dependen del modelo. Consulta [Preservación de bloques de pensamiento por modelo](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-block-preservation-by-model). Para cambiar el comportamiento predeterminado, usa la [estrategia de edición de contexto `clear_thinking_20251015`](https://platform.claude.com/docs/es/build-with-claude/context-editing#thinking-block-clearing). Dentro del último mensaje del asistente, la secuencia de bloques `thinking` consecutivos debe coincidir con lo que el modelo generó en la solicitud original: no puedes reordenarlos, editarlos ni eliminar solo algunos. Esto incluye los [bloques `redacted_thinking`](https://platform.claude.com/docs/es/build-with-claude/thinking#redacted-thinking-blocks). Los bloques de pensamiento modificados se rechazan con un error 400. Consulta [Un error 400 indica que los bloques de pensamiento no se pueden modificar](https://platform.claude.com/docs/es/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) para ver el mensaje exacto, las causas habituales y la solución. La única excepción: el texto que coloques en el campo `thinking` vacío de un bloque [omitido](https://platform.claude.com/docs/es/build-with-claude/thinking#controlling-thinking-display) se ignora en lugar de rechazarse. Para ver un ejemplo completo de dos turnos con código en cada SDK, consulta [Pensamiento en flujos de trabajo con herramientas y de varios turnos](https://platform.claude.com/docs/es/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip). El ejemplo define una herramienta, recibe una respuesta con pensamiento y uso de herramientas, y devuelve el turno del asistente junto con el resultado de la herramienta. ### Pensamiento intercalado El "interleaved thinking" (pensamiento intercalado) permite a Claude pensar entre llamadas a herramientas, razonando sobre cada resultado de herramienta antes de actuar en consecuencia. Con el pensamiento intercalado, Claude puede: * Razonar sobre los resultados de una llamada a herramienta antes de determinar qué hacer a continuación * Encadenar varias llamadas a herramientas con pasos de razonamiento entre ellas * Tomar decisiones más matizadas basadas en resultados intermedios Las llamadas consecutivas a herramientas no requieren pensamiento intercalado. Claude puede encadenar llamadas a herramientas con o sin pensamiento intercalado. El intercalado cambia dónde aparecen los bloques de pensamiento entre llamadas a herramientas, no si las llamadas a herramientas pueden encadenarse. Con el pensamiento adaptativo, el pensamiento intercalado es automático en todos los modelos que admiten pensamiento adaptativo. No se necesita ningún encabezado beta. En Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8 y Claude Opus 4.7, el razonamiento entre llamadas a herramientas siempre aparece en bloques de pensamiento. Claude Haiku 4.5 no admite pensamiento intercalado. En los modelos que usan pensamiento extendido manual, el intercalado requiere un encabezado beta y cambia cómo se contabiliza el presupuesto de pensamiento. [Pensamiento intercalado en modo manual](https://platform.claude.com/docs/es/build-with-claude/extended-thinking#interleaved-thinking) cubre las reglas por modelo y el comportamiento del encabezado específico de cada plataforma. Con el pensamiento intercalado, la asignación de pensamiento puede abarcar todo el turno del asistente en lugar de una sola respuesta. El pensamiento intercalado solo se admite para [herramientas usadas a través de la API de Messages](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview). Para ver una comparación práctica que muestra qué cambia el pensamiento intercalado en un flujo de trabajo con dos herramientas, consulta [Cómo el pensamiento intercalado cambia el flujo](https://platform.claude.com/docs/es/build-with-claude/thinking-tool-workflows#how-interleaved-thinking-changes-the-flow). ### Actualizaciones de progreso entre llamadas a herramientas En Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Fable 5, el modelo puede escribir una actualización de progreso entre llamadas a herramientas. Una actualización de progreso es una nota sobre lo que el modelo acaba de encontrar y lo que va a hacer a continuación, escrita para la persona que observa al agente y no como razonamiento. Cada una se devuelve como su propio bloque `thinking` con su propia `signature`, separado de cualquier bloque de razonamiento en el mismo punto. Se ubica inmediatamente antes del bloque `tool_use` o `server_tool_use` que introduce. Como máximo, una actualización de progreso precede a cada llamada a herramienta, y el modelo puede omitir cualquiera de ellas. Las actualizaciones de progreso no son [pensamiento intercalado](https://platform.claude.com/docs/es/build-with-claude/thinking#interleaved-thinking): aparecen tanto si aparecen bloques de razonamiento entre llamadas a herramientas como si no, y una respuesta puede contener ambos. Lo que contiene un bloque de actualización de progreso depende de [`display`](https://platform.claude.com/docs/es/build-with-claude/thinking#controlling-thinking-display): | `display` | Bloques de razonamiento | Bloques de actualización de progreso | | ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------- | | `"omitted"` (el valor predeterminado en estos modelos) | Campo `thinking` vacío | Campo `thinking` vacío | | `"updates"` (beta) | Campo `thinking` vacío | Texto de resumen | | `"summarized"` | Texto de resumen | Texto de resumen, indistinguible de un bloque de razonamiento | En Claude Sonnet 5.5, la configuración de pensamiento más baja es `thinking: {type: "between_tools"}`. Desactiva el pensamiento inicial, y cada actualización de progreso se devuelve con su texto de resumen, como ocurriría con `display: "updates"`. `between_tools` solo se acepta con [esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) `high` o inferior. Con `xhigh` o `max`, una solicitud que lo incluya devuelve un error 400. `between_tools` no admite ningún otro campo: `display`, `budget_tokens` o `block_binding` enviados con él devuelven un error 400. La configuración no necesita encabezado beta y funciona en todas las plataformas que ofrecen Claude Sonnet 5.5. Devuelve los bloques sin cambios: un bloque de actualización de progreso que devuelves le da al modelo la nota completa que escribió, no el resumen. Usa `display: "updates"` para una interfaz de agente que mantiene oculto el razonamiento y muestra al usuario una línea de estado en cada paso. Con este valor, cualquier bloque `thinking` con texto no vacío es una actualización de progreso, así que muestra esos y nada más. Está en beta y requiere el encabezado beta `thinking-display-updates-2026-08-18` (para enviarlo en Amazon Bedrock, Google Cloud o Microsoft Foundry, consulta [Funciones beta en otras plataformas](https://platform.claude.com/docs/es/api/beta-headers#beta-features-on-other-platforms)). Sin él, el valor se rechaza con el mismo error 400 `invalid_request_error` que un valor de `display` desconocido. ```json { "model": "claude-fable-5-1", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "updates" }, "tools": [ { "name": "edit_file", "description": "Replace the contents of a file in the repository.", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": ["path", "content"] } } ], "messages": [ { "role": "user", "content": "The login test fails after an hour of uptime. Find out why and fix it." } ] } ``` Con `"updates"`, el inicio de la respuesta que sigue a un `tool_result` se ve así. El primer bloque es razonamiento y permanece vacío, como ocurriría con `"omitted"`. El segundo contiene texto, por lo que es una actualización de progreso. Con `"summarized"` ambos bloques contienen texto, y con `"omitted"` ambos están vacíos. ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EqMBCkYICxIM..." }, { "type": "thinking", "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.", "signature": "Es8CCkYICxIM..." }, { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "edit_file", "input": { "path": "auth.py", "content": "..." } } ] } ``` Ten en cuenta lo siguiente al trabajar con actualizaciones de progreso: * Devuelve los bloques de actualización de progreso sin cambios junto con el resto del turno del asistente, como cualquier otro bloque `thinking`. * El texto que recibes es un resumen de la actualización de progreso, normalmente una o dos oraciones. No dependas de su longitud. La actualización de progreso cuenta para `usage.output_tokens` con su longitud completa, no con la del resumen. * Un bloque de actualización de progreso puede devolverse con un campo `thinking` vacío con cualquier valor de `display`. No muestres nada para un bloque vacío. Con `"updates"` se ve igual que un bloque de razonamiento vacío y no necesita un manejo aparte. * Cuando una respuesta se detiene por `max_tokens`, `model_context_window_exceeded` o `stop_sequence` poco después de una llamada a herramienta o de un resultado de herramienta, su último bloque puede ser un bloque de actualización de progreso que sustituye al trabajo que el modelo no había terminado. Con `"updates"` y `"summarized"` su texto es exactamente `This part of the response was interrupted before it finished.` y puedes mostrarlo como cualquier otra actualización. Con `"omitted"` está vacío. Para continuar, devuelve el turno del asistente sin cambios y agrega un nuevo mensaje `user` (con un `tool_result` para cada bloque `tool_use` de ese turno). * Al hacer [streaming](https://platform.claude.com/docs/es/build-with-claude/thinking#streaming-thinking), espera una pausa de varios segundos antes de que se abra un bloque de actualización de progreso. Consulta la traza de `"updates"` en [Streaming del pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#streaming-thinking). * Estos modelos escriben menos actualizaciones de progreso con un [esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort) más alto y en cadenas largas de herramientas. Si tu interfaz depende de ellas, consulta [Pide actualizaciones de progreso para el usuario](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates) o, para Claude Opus 5.5, [Actualizaciones de progreso para el usuario](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates). Para Claude Sonnet 5.5, consulta [Actualizaciones de progreso para el usuario](https://platform.claude.com/docs/es/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates). ### Preservación de bloques de pensamiento por modelo Que los bloques de pensamiento de turnos anteriores del asistente permanezcan en el contexto de forma predeterminada depende del modelo: * **Conservar todos los turnos anteriores:** Claude Opus 4.5 y modelos Opus posteriores, Claude Sonnet 4.6 y modelos Sonnet posteriores, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 y Claude Mythos Preview. * **Conservar solo el último turno:** modelos Opus y Sonnet anteriores, y todos los modelos Haiku hasta Claude Haiku 4.5. Cuando devuelves bloques de pensamiento más antiguos, la API los elimina automáticamente. No necesitas eliminarlos tú mismo. La preservación aporta dos beneficios: * **Optimización de caché:** los bloques de pensamiento preservados permiten aciertos de caché durante el "tool use" (uso de herramientas), ya que se devuelven junto con los resultados de herramientas y se almacenan en caché de forma incremental a lo largo del turno del asistente, lo que genera ahorro de tokens en flujos de trabajo de varios pasos. * **Sin impacto en la inteligencia:** preservar los bloques de pensamiento no tiene ningún efecto negativo en el rendimiento del modelo. La contrapartida es el uso del contexto: las conversaciones largas consumen más espacio de contexto en los modelos que conservan todo, porque los bloques de pensamiento retenidos cuentan como entrada igual que cualquier otro historial de conversación (consulta [El pensamiento y la ventana de contexto](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-the-context-window)). El comportamiento es automático en ambos regímenes. No se requieren cambios de código ni encabezados beta, y debes seguir devolviendo los bloques de pensamiento completos y sin modificar, como se describe en [Preservar los bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#preserving-thinking-blocks). Para anular el valor predeterminado en cualquier dirección, usa la [eliminación de bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/context-editing#thinking-block-clearing). **Cambiar de modelo a mitad de la conversación.** Sigue devolviendo los bloques de pensamiento sin cambios cuando cambies de modelo, por ejemplo después de un [fallback por rechazo del clasificador](https://platform.claude.com/docs/es/build-with-claude/refusals-and-fallback). Un bloque de pensamiento solo puede leerlo el modelo que lo produjo y ciertos otros modelos, y la API ignora o descarta los bloques que el modelo de destino no puede leer. En Claude Fable 5.1 y Claude Mythos 5.1 la dirección importa: leen los bloques de pensamiento de modelos anteriores, y solo ellos dos leen los del otro, por lo que cambiar a ellos conserva el razonamiento de la conversación y cambiar de ellos a cualquier otro modelo lo descarta (consulta [cómo se facturan y reportan los bloques descartados](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 lee los bloques de pensamiento de Claude Opus 5 y los de modelos Opus, Sonnet y Haiku anteriores, y, en la Claude API y Google Cloud, los de Claude Haiku 5.5, pero no los de los modelos Claude Fable y Claude Mythos; en la Claude API, Claude Fable 5.1 y Claude Mythos 5.1 leen los bloques de Claude Opus 5.5. Un cambio de Claude Opus 5.5 a Claude Fable 5.1 en la Claude API conserva el razonamiento de los turnos anteriores; un cambio de Claude Fable 5.1 a Claude Opus 5.5 lo descarta. Claude Sonnet 5.5 lee bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores, y, en la Claude API y Google Cloud, de Claude Haiku 5.5, pero no de Claude Opus 5, Claude Opus 5.5 ni de ningún modelo Claude Fable o Claude Mythos. En la Claude API y Google Cloud, Claude Opus 5.5 lee los bloques de Claude Sonnet 5.5 y ningún otro modelo lo hace: un cambio de Claude Sonnet 5.5 a Claude Opus 5.5 en la Claude API y Google Cloud conserva el razonamiento de los turnos anteriores, y cualquier otro cambio desde Claude Sonnet 5.5 lo descarta. Claude Haiku 5.5 lee bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores, pero no de Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ni de ningún modelo Claude Fable o Claude Mythos. En la Claude API y Google Cloud, Claude Opus 5.5 y Claude Sonnet 5.5 leen los bloques de Claude Haiku 5.5 y ningún otro modelo lo hace. Elimina tú mismo los bloques `thinking` y `redacted_thinking` anteriores solo para ahorrar tokens de entrada en modelos que los ignoran en lugar de descartarlos, y nunca al canjear un [crédito de respaldo](https://platform.claude.com/docs/es/build-with-claude/fallback-credit), que requiere el cuerpo sin cambios. ## Pensamiento preservado El [pensamiento preservado](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking) determina si el modelo puede usar un bloque de pensamiento que devuelves de un turno anterior. A partir de Claude Fable 5.1, la API verifica la `signature` de cada bloque `thinking` o `redacted_thinking` en una solicitud para comprobar dos cosas: * **El modelo que lo produjo.** Cada modelo lee sus propios bloques de pensamiento y los de un conjunto fijo de otros modelos. Claude Fable 5.1 lee bloques de Claude Opus 5 y, en la Claude API, de Claude Opus 5.5; ni Claude Opus 5 ni Claude Opus 5.5 leen bloques de Claude Fable 5.1. La API descarta un bloque que el modelo actual no puede leer, sin error y sin facturarlo. Consulta [Cambiar de modelo a mitad de la conversación](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#switching-models). * **Todo lo enviado antes de él.** Un bloque sigue siendo válido solo mientras la indicación `system` de nivel superior, las `tools` y los mensajes anteriores a él no cambien. Si alguno de ellos cambia, ese bloque y todos los bloques de pensamiento posteriores dejan de ser válidos, y la API rechaza la solicitud con un error 400 o descarta los bloques no válidos, según lo que elijas. Consulta [Mantener el prefijo sin cambios](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#prefix-check). Los bloques de pensamiento de Claude Sonnet 5.5 y Claude Haiku 5.5 también están vinculados a la cuenta que los produjo. Consulta [Los bloques de pensamiento permanecen con la cuenta que los produjo](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#account-bound-thinking) para saber dónde aplica esto la API. La verificación del modelo se aplica a todas las cuentas. La API aplica la verificación del prefijo de forma predeterminada para las cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC. En cuentas más antiguas, aplica la verificación solo en solicitudes que establecen `thinking.block_binding.prefix_mismatch_behavior`. Haz que tu integración solo agregue contenido al final, independientemente de la antigüedad de tu cuenta, para que el mismo código funcione en todas las cuentas, incluidas las cuentas más nuevas en las que se aplica de forma predeterminada. Para mantener válido el pensamiento, devuelve cada turno del asistente exactamente como lo recibiste y agrega mensajes nuevos solo al final de `messages`. Si tu código construye el arreglo `messages` por sí mismo, la página de Pensamiento preservado cubre: * [Qué cuenta como una edición](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#what-counts-as-an-edit), y [cómo comprobar si tu código realiza una](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). * [La función de la API que reemplaza cada edición común](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#replace-prefix-edits): mensajes del sistema a mitad de la conversación para nuevas instrucciones y recordatorios por turno, bloques `tool_addition` y `tool_removal` para cambios de herramientas, `output_config` por mensaje para cambios de esfuerzo, y compactación del lado del servidor y edición de contexto para recortar. * [Compactación del lado del cliente](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#custom-compaction-on-the-client): qué patrones mantienen válido el pensamiento y cuáles no. * [El encabezado beta `thinking-binding-controls-2026-08-01`](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#preserved-thinking-controls). Agrega un campo `block_binding.prefix_mismatch_behavior` (`"error"` o `"drop_block"`) a la configuración de pensamiento y un arreglo `input_transformations` a cada respuesta. El arreglo enumera cada bloque de pensamiento que la API descartó, o que no superó la verificación del prefijo y se dejó pasar. ## Pensamiento y almacenamiento en caché de prompts El ["prompt caching" (almacenamiento en caché de prompts)](https://platform.claude.com/docs/es/build-with-claude/prompt-caching) interactúa con el pensamiento de algunas maneras específicas. Las siguientes reglas se aplican en ambos modos de pensamiento. **Los cambios de configuración invalidan la caché.** La configuración de pensamiento y el nivel de [`effort`](https://platform.claude.com/docs/es/build-with-claude/effort) resuelto se representan dentro del propio prompt, por lo que cambiar cualquiera de ellos inicia un nuevo prefijo de caché. Cambiar entre `adaptive`, `enabled` y `disabled`, cambiar `budget_tokens` y cambiar el valor de esfuerzo invalidan los puntos de interrupción de caché: los puntos de interrupción a nivel de mensaje siempre fallan, y los puntos de interrupción de herramientas y de la "system prompt" (indicación del sistema) también pueden fallar, según dónde represente el modelo la configuración. Trata cualquier cambio de pensamiento o de esfuerzo de nivel superior como un reinicio de la caché. En los modelos que admiten [esfuerzo por mensaje](https://platform.claude.com/docs/es/build-with-claude/effort#change-effort-mid-conversation-beta), un cambio de esfuerzo incluido en un mensaje `role: "system"` dentro de `messages` deja intacto el prefijo en caché. Las solicitudes consecutivas que mantienen la misma configuración preservan la caché, y establecer un parámetro explícitamente en su valor predeterminado equivale a omitirlo. Un bloque de pensamiento que la API descarta bajo cualquier [condición de pensamiento preservado](https://platform.claude.com/docs/es/build-with-claude/thinking#preserved-thinking) cambia el prefijo en caché desde la posición de ese bloque en adelante. Los bloques devueltos sin cambios mantienen intacta la caché. Hay una demostración práctica con la salida de uso en la página [Dirigir el pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking-steering-and-cost#prompt-caching). **Los bloques de pensamiento se almacenan en caché con los resultados de herramientas.** Durante un bucle de uso de herramientas, el almacenamiento en caché ocurre cuando haces una solicitud de seguimiento que incluye resultados de herramientas. En ese momento, el historial de conversación anterior, incluidos sus bloques de pensamiento, puede almacenarse en caché, y esos bloques de pensamiento en caché cuentan como tokens de entrada en tus métricas de uso cuando se leen desde la caché. Esto ocurre automáticamente, incluso sin marcadores `cache_control` explícitos, y se comporta igual para el pensamiento regular y el intercalado. La contrapartida: los bloques de pensamiento que nunca vuelves a ver en las respuestas siguen contribuyendo al uso de tokens de entrada cuando se leen desde la caché. **Que los bloques anteriores estén o no en el contexto depende del modelo.** El [valor predeterminado de preservación](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-block-preservation-by-model) rige esto. En los modelos que conservan todo, los bloques de pensamiento de turnos anteriores permanecen en caché y en el contexto. En los modelos que conservan solo el último turno, una vez que envías un mensaje de usuario que no es un resultado de herramienta, todos los bloques de pensamiento anteriores se eliminan del contexto. En esos modelos, una conversación como esta: ```text wrap User: ["What's the weather in Paris?"], Assistant: [thinking_block_1] + [tool_use block 1], User: [tool_result_1, cache=True], Assistant: [thinking_block_2] + [text block 2], User: [Text response, cache=True] ``` se procesa como si los bloques de pensamiento nunca hubieran estado allí: ```text wrap User: ["What's the weather in Paris?"], Assistant: [tool_use block 1], User: [tool_result_1, cache=True], Assistant: [text block 2], User: [Text response, cache=True] ``` En los modelos que conservan todo, la misma solicitud mantiene `thinking_block_1` y `thinking_block_2` en el contexto y en la caché. **La degradación elimina el pensamiento del historial almacenable en caché.** Si el pensamiento se desactiva a mitad del turno y pasas contenido de pensamiento en el turno actual de uso de herramientas, el contenido de pensamiento se elimina y el pensamiento permanece desactivado para esa solicitud (consulta [degradación elegante](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-with-tool-use)). El [pensamiento intercalado](https://platform.claude.com/docs/es/build-with-claude/thinking#interleaved-thinking) amplifica los efectos de invalidación de la caché, porque los bloques de pensamiento pueden aparecer entre múltiples llamadas a herramientas. Las tareas con mucho pensamiento suelen tardar más en completarse que la vida útil predeterminada de la caché de 5 minutos. Considera la [duración de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration) para mantener los aciertos de caché en sesiones de pensamiento más largas y flujos de trabajo de varios pasos. ## El pensamiento y la ventana de contexto `max_tokens`, que incluye todo el pensamiento que Claude genera en el turno actual, se aplica como un límite estricto. En los modelos Claude 4.5 y más recientes, si los tokens de entrada más `max_tokens` superan el tamaño de la "context window" (ventana de contexto), la API acepta la solicitud. Si luego la generación alcanza el límite de la ventana de contexto, se detiene con `stop_reason: "model_context_window_exceeded"` en lugar de devolver un error. En modelos anteriores, la API devuelve en su lugar un error de validación. Consulta [Manejo de los motivos de detención](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons). Cómo cuenta el pensamiento contra la ventana depende de cuándo se generó: * **El pensamiento del turno actual** siempre cuenta para `max_tokens`, se factura como tokens de salida y ocupa espacio en la ventana de contexto durante el turno que lo generó. * **El pensamiento de turnos anteriores** depende del [valor predeterminado de preservación](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-block-preservation-by-model). En los [modelos que conservan todos los turnos anteriores](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-block-preservation-by-model), los bloques de pensamiento anteriores permanecen en el contexto, cuentan para la ventana y se facturan como tokens de entrada como el resto del historial de conversación. En los modelos que conservan solo el último turno, la API elimina automáticamente los bloques de pensamiento más antiguos cuando los devuelves, por lo que no consumen espacio de la ventana ni tokens de entrada. En la práctica: * En los modelos que conservan todo, planifica tu ventana de contexto como si el pensamiento fuera historial de conversación ordinario, porque lo es. Las sesiones agénticas largas acumulan pensamiento en el contexto. Usa la [eliminación de bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/context-editing#thinking-block-clearing) si necesitas recuperar espacio. * En los modelos que conservan solo el último turno, el pensamiento es solo un costo por turno: el pensamiento de cada turno cuenta contra el `max_tokens` de ese turno y luego sale de la ventana. Los siguientes diagramas ilustran el régimen de solo el último turno (eliminación). El primero muestra una conversación de varios turnos: el bloque de pensamiento de cada turno se genera en la salida, pero no se traslada a la entrada de los turnos posteriores. ![Diagrama del pensamiento en un modelo que elimina los bloques de pensamiento anteriores: el bloque de pensamiento de cada turno se genera en la salida y no se traslada a la entrada de los turnos posteriores](https://platform.claude.com/docs/es/images/context-window-thinking.svg) El segundo muestra el mismo régimen con uso de herramientas: el pensamiento permanece en el contexto junto con su resultado de herramienta durante el turno del asistente y luego sale en el siguiente turno del usuario. ![Diagrama del pensamiento con uso de herramientas en un modelo que elimina los bloques de pensamiento anteriores: el pensamiento se conserva con su resultado de herramienta y luego se descarta en el siguiente turno del usuario](https://platform.claude.com/docs/es/images/context-window-thinking-tools.svg) Usa la [API de conteo de tokens](https://platform.claude.com/docs/es/build-with-claude/token-counting) para obtener conteos precisos para tu caso de uso específico, especialmente en conversaciones de varios turnos que incluyen pensamiento. ## Cifrado del pensamiento El contenido completo del pensamiento se cifra y se devuelve en el campo `signature` de cada bloque de pensamiento. Cuando devuelves los bloques de pensamiento, la API usa la firma para verificar que Claude los generó. Ten en cuenta lo siguiente al trabajar con firmas: * Solo es estrictamente necesario devolver los bloques de pensamiento cuando [usas herramientas con pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-with-tool-use). En los demás casos, puedes omitir los bloques de pensamiento de turnos anteriores. Si los devuelves, que la API los conserve o los elimine depende del modelo (consulta [Preservación de bloques de pensamiento por modelo](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-block-preservation-by-model)). Usa la [edición de contexto](https://platform.claude.com/docs/es/build-with-claude/context-editing) para configurar esto. * Al devolver bloques de pensamiento, devuelve todo exactamente como lo recibiste, por coherencia y para evitar posibles problemas. * Al hacer [streaming de respuestas](https://platform.claude.com/docs/es/build-with-claude/thinking#streaming-thinking), la firma llega como un `signature_delta` dentro de un evento `content_block_delta`, justo antes del evento `content_block_stop`. * Los valores de `signature` son considerablemente más largos en Claude 4 y modelos posteriores que en los modelos anteriores. * El campo `signature` es opaco, así que no lo interpretes ni lo analices. * Los valores de `signature` son compatibles entre plataformas (la Claude API, [Amazon Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock) y [Google Cloud](https://platform.claude.com/docs/es/build-with-claude/claude-on-vertex-ai)). Los valores generados en una plataforma funcionan en otra, excepto que los bloques de pensamiento de Claude Sonnet 5.5 y Claude Haiku 5.5 solo funcionan en la cuenta que los produjo o en una cuenta vinculada a ella. Consulta [Los bloques de pensamiento permanecen con la cuenta que los produjo](https://platform.claude.com/docs/es/build-with-claude/preserved-thinking#account-bound-thinking). ## Bloques de pensamiento censurados Además de los bloques `thinking` regulares, la API puede devolver bloques `redacted_thinking` cuando partes del razonamiento de Claude se censuran por motivos de seguridad. Un bloque `redacted_thinking` contiene contenido de pensamiento cifrado en un campo `data`, sin texto legible: ```json { "type": "redacted_thinking", "data": "..." } ``` El campo `data` es opaco y está cifrado. Al igual que el campo `signature` de los bloques de pensamiento regulares, devuelve los bloques `redacted_thinking` a la API sin cambios cuando continúes una conversación de varios turnos con [herramientas](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-with-tool-use). Si tu código filtra los bloques de contenido por tipo (por ejemplo, `block.type == "thinking"`) al reenviar respuestas con uso de herramientas, incluye también los bloques `redacted_thinking`. Filtrar solo por `block.type == "thinking"` descarta silenciosamente los bloques `redacted_thinking` y rompe el protocolo de varios turnos descrito en [Preservar los bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking#preserving-thinking-blocks). Los bloques `redacted_thinking` son un tipo de bloque de contenido distinto que se devuelve cuando el pensamiento se censura por motivos de seguridad. Esto es independiente de la opción [`display: "omitted"`](https://platform.claude.com/docs/es/build-with-claude/thinking#controlling-thinking-display), que devuelve bloques `thinking` regulares con un campo `thinking` vacío. ## Límites y compatibilidad de funciones ### Parámetros de muestreo En Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 y Claude Haiku 5.5, los valores no predeterminados de `temperature`, `top_p` o `top_k` devuelven un error 400 en cada solicitud, independientemente de si se usa el pensamiento. En estos modelos, el valor predeterminado de `top_p` es `0.99`, por lo que un `top_p` de `1` devuelve un error 400, al igual que una solicitud que incluye tanto `temperature` como `top_p`, incluso con sus valores predeterminados. Consulta [Elimina los parámetros de muestreo](https://platform.claude.com/docs/es/models/haiku-5-5/migration-guide#remove-sampling-parameters). En modelos más antiguos, la restricción se aplica solo mientras el pensamiento está activado: `temperature` y `top_k` son incompatibles con el pensamiento, y `top_p` se permite con valores entre 0.95 y 1. ### Prellenado de respuestas y uso forzado de herramientas Los modelos Claude 4.6 y posteriores y Claude Mythos Preview rechazan un turno final del asistente prellenado con un error 400, esté o no activado el pensamiento (consulta [Prefill no admitido](https://platform.claude.com/docs/es/api/errors#prefill-not-supported)). En modelos anteriores, no puedes prellenar la respuesta del asistente mientras el pensamiento está activado. El uso forzado de herramientas (`tool_choice: {"type": "any"}` o `{"type": "tool", ...}`) es incompatible con el pensamiento extendido manual, pero funciona con el pensamiento adaptativo. Las excepciones son Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1, que rechazan el uso forzado de herramientas en cada solicitud con un error 400. En esos modelos, usa en su lugar `tool_choice: {"type": "auto"}` con [uso estricto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) o [salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs). Donde se acepta el uso forzado de herramientas, la respuesta comienza con la llamada a la herramienta y no tiene bloque `thinking`. Para permitir que el modelo piense antes de llamar a una herramienta, usa `tool_choice: {"type": "auto"}` e indica en el prompt cuándo usar la herramienta. Consulta [Pensamiento con uso de herramientas](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-with-tool-use). ### Límites de salida Cada modelo acepta `max_tokens` hasta el límite indicado aquí. En la [API de Message Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing#extended-output-beta), el [encabezado beta](https://platform.claude.com/docs/es/api/beta-headers) `output-300k-2026-03-24` eleva ese límite para los modelos que tienen un límite de lotes indicado. | Model | Max output tokens | Batches beta ceiling | | :-------------------- | :---------------- | :------------------- | | Claude Fable 5.1 | 128K | — | | Claude Mythos 5.1 | 128K | — | | Claude Fable 5 | 128K | — | | Claude Mythos 5 | 128K | — | | Claude Mythos Preview | 128K | Not available | | Claude Opus 5.5 | 128K | 300K | | Claude Opus 5 | 128K | 300K | | Claude Opus 4.8 | 128K | 300K | | Claude Opus 4.7 | 128K | 300K | | Claude Opus 4.6 | 128K | 300K | | Claude Opus 4.5 | 64K | Not available | | Claude Sonnet 5.5 | 128K | 300K | | Claude Sonnet 5 | 128K | 300K | | Claude Sonnet 4.6 | 128K | 300K | | Claude Sonnet 4.5 | 64K | Not available | | Claude Haiku 5.5 | 128K | 300K | | Claude Haiku 4.5 | 64K | Not available | Consulta la [descripción general de los modelos](https://platform.claude.com/docs/es/models/overview) para conocer los límites de los modelos heredados. ### Solicitudes largas El SDK requiere "streaming" cuando `max_tokens` es mayor que 21,333, para evitar tiempos de espera HTTP en solicitudes de larga duración. Esta es una validación del lado del cliente, no una restricción de la API. Si no necesitas procesar los eventos de forma incremental, usa `.stream()` (java: `.createStreaming()`; csharp: `.CreateStreaming()`; go: `.NewStreaming()`; php: `->createStream()`) con `.get_final_message()` (typescript: `.finalMessage()`; ruby: `.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`) para obtener el objeto `Message` completo sin tener que ensamblarlo tú mismo a partir de eventos individuales. Consulta [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming#get-the-final-message-without-handling-events). Espera tiempos de respuesta más largos cuando el pensamiento está activo, porque generar bloques de pensamiento agrega tiempo de procesamiento. Para cargas de trabajo que llevan el pensamiento por encima de aproximadamente 32k tokens por solicitud, usa el [procesamiento por lotes](https://platform.claude.com/docs/es/build-with-claude/batch-processing) para evitar problemas de red: esas solicitudes pueden durar lo suficiente como para alcanzar los tiempos de espera del sistema y los límites de conexiones abiertas. ## Próximos pasos Controla con qué frecuencia y con qué profundidad piensa Claude mediante niveles de effort, orientación en la indicación del sistema y dirección por mensaje. Además, comprende el costo y los precios del pensamiento. Recorre un ciclo completo de uso de herramientas de dos turnos que preserva correctamente los bloques de pensamiento, y descubre cómo el pensamiento intercalado cambia el flujo. Averigua si tu integración con la API de Messages edita el historial de conversación, y reemplaza cada edición con la función de la API que mantiene válidos los bloques de pensamiento anteriores. Diagnostica y corrige los fallos de pensamiento más comunes, como errores 400 de configuración, bloques de pensamiento vacíos o ausentes, detenciones por max\_tokens y fallos de caché. Controla cuántos tokens usa Claude al responder mediante el parámetro effort, equilibrando la exhaustividad de la respuesta y la eficiencia de tokens.