Construir con pensamiento extendido

Cómo funciona el pensamiento extendido

Cuando el pensamiento extendido está activado, Claude crea bloques de contenido thinking donde genera su razonamiento interno. Claude incorpora información de este razonamiento antes de elaborar una respuesta final.

La respuesta de la API incluirá bloques de contenido thinking, seguidos de bloques de contenido text.

Aquí hay un ejemplo del formato de respuesta predeterminado:

Para obtener más información sobre el formato de respuesta del pensamiento extendido, consulte la Referencia de la API de Mensajes.

Cómo usar el pensamiento extendido

Aquí hay un ejemplo de uso del pensamiento extendido en la API de Mensajes:

Para activar el pensamiento extendido, agregue un objeto thinking, con el parámetro type establecido en enabled y budget_tokens en un presupuesto de tokens especificado para el pensamiento extendido.

El parámetro budget_tokens determina el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno. En los modelos Claude 4, este límite se aplica a los tokens de pensamiento completo, y no a la salida resumida. Los presupuestos más grandes pueden mejorar la calidad de la respuesta al permitir un análisis más exhaustivo para problemas complejos, aunque Claude puede no usar todo el presupuesto asignado, especialmente en rangos superiores a 32k.

budget_tokens debe establecerse en un valor menor que max_tokens. Sin embargo, cuando se usa pensamiento intercalado con herramientas, puede exceder este límite ya que el límite de tokens se convierte en su ventana de contexto completa (200k tokens).

Pensamiento resumido

Con el pensamiento extendido habilitado, la API de Mensajes para los modelos Claude 4 devuelve un resumen del proceso de pensamiento completo de Claude. El pensamiento resumido proporciona los beneficios de inteligencia completa del pensamiento extendido, mientras previene el mal uso.

Aquí hay algunas consideraciones importantes para el pensamiento resumido:

• Se le cobra por los tokens de pensamiento completo generados por la solicitud original, no por los tokens de resumen.
• El recuento de tokens de salida facturados no coincidirá con el recuento de tokens que ve en la respuesta.
• Las primeras líneas de la salida de pensamiento son más detalladas, proporcionando razonamiento detallado que es particularmente útil para propósitos de ingeniería de prompts.
• A medida que Anthropic busca mejorar la característica de pensamiento extendido, el comportamiento de resumen está sujeto a cambios.
• La resumen preserva las ideas clave del proceso de pensamiento de Claude con latencia mínima agregada, permitiendo una experiencia de usuario transmisible y migración fácil de Claude Sonnet 3.7 a modelos Claude 4.
• La resumen es procesada por un modelo diferente al que apunta en sus solicitudes. El modelo de pensamiento no ve la salida resumida.

Pensamiento en streaming

Puede transmitir respuestas de pensamiento extendido usando eventos enviados por servidor (SSE).

Cuando el streaming está habilitado para el pensamiento extendido, recibe contenido de pensamiento a través de eventos thinking_delta.

Para obtener más documentación sobre streaming a través de la API de Mensajes, consulte Streaming de Mensajes.

Aquí se explica cómo manejar el streaming con pensamiento:

Ejemplo de salida de streaming:

Pensamiento extendido con uso de herramientas

El pensamiento extendido se puede usar junto con uso de herramientas, permitiendo a Claude razonar a través de la selección de herramientas y el procesamiento de resultados.

Cuando se usa pensamiento extendido con uso de herramientas, tenga en cuenta las siguientes limitaciones:

1. Limitación de elección de herramienta: El uso de herramientas con pensamiento solo admite tool_choice: {"type": "auto"} (el predeterminado) o tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} o tool_choice: {"type": "tool", "name": "..."} resultará en un error porque estas opciones fuerzan el uso de herramientas, que es incompatible con el pensamiento extendido.

2. Preservación de bloques de pensamiento: Durante el uso de herramientas, debe pasar bloques thinking de vuelta a la API para el último mensaje del asistente. Incluya el bloque completo sin modificar de vuelta a la API para mantener la continuidad del razonamiento.

Alternancia de modos de pensamiento en conversaciones

No puede alternar el pensamiento en medio de un turno del asistente, incluido durante bucles de uso de herramientas. El turno completo del asistente debe operar en un único modo de pensamiento:

• Si el pensamiento está habilitado, el turno final del asistente debe comenzar con un bloque de pensamiento.
• Si el pensamiento está deshabilitado, el turno final del asistente no debe contener ningún bloque de pensamiento

Desde la perspectiva del modelo, los bucles de uso de herramientas son parte del turno del asistente. Un turno del asistente no se completa hasta que Claude termina su respuesta completa, que puede incluir múltiples llamadas de herramientas y resultados.

Por ejemplo, esta secuencia es toda parte de un único turno del asistente:

Aunque hay múltiples mensajes de API, el bucle de uso de herramientas es conceptualmente parte de una respuesta continua del asistente.

Escenarios de error comunes

Puede encontrar este error:

Esto típicamente ocurre cuando:

1. Tenía pensamiento deshabilitado durante una secuencia de uso de herramientas
2. Desea habilitar el pensamiento nuevamente
3. Su último mensaje del asistente contiene bloques de uso de herramientas pero sin bloque de pensamiento

Orientación práctica

✗ Inválido: Alternancia de pensamiento inmediatamente después del uso de herramientas

✓ Válido: Completar el turno del asistente primero

Mejor práctica: Planifique su estrategia de pensamiento al inicio de cada turno en lugar de intentar alternar a mitad de turno.

Preservación de bloques de pensamiento

Durante el uso de herramientas, debe pasar bloques thinking de vuelta a la API, y debe incluir el bloque completo sin modificar de vuelta a la API. Esto es crítico para mantener el flujo de razonamiento del modelo e integridad de la conversación.

Cuando Claude invoca herramientas, está pausando su construcción de una respuesta para esperar información externa. Cuando se devuelven resultados de herramientas, Claude continuará construyendo esa respuesta existente. Esto requiere preservar bloques de pensamiento durante el uso de herramientas, por un par de razones:

1. Continuidad del razonamiento: Los bloques de pensamiento capturan el razonamiento paso a paso de Claude que condujo a solicitudes de herramientas. Cuando publica resultados de herramientas, incluir el pensamiento original asegura que Claude pueda continuar su razonamiento desde donde se quedó.

2. Mantenimiento del contexto: Aunque los resultados de herramientas aparecen como mensajes de usuario en la estructura de la API, son parte de un flujo de razonamiento continuo. Preservar bloques de pensamiento mantiene este flujo conceptual a través de múltiples llamadas de API. Para obtener más información sobre la gestión del contexto, consulte nuestra guía sobre ventanas de contexto.

Importante: Cuando proporciona bloques thinking, la secuencia completa de bloques thinking consecutivos debe coincidir con las salidas generadas por el modelo durante la solicitud original; no puede reorganizar o modificar la secuencia de estos bloques.

Pensamiento intercalado

El pensamiento extendido con uso de herramientas en modelos Claude 4 admite pensamiento intercalado, que permite a Claude pensar entre llamadas de herramientas y hacer un razonamiento más sofisticado después de recibir resultados de herramientas.

Con pensamiento intercalado, Claude puede:

• Razonar sobre los resultados de una llamada de herramienta antes de decidir qué hacer a continuación
• Encadenar múltiples llamadas de herramientas con pasos de razonamiento en medio
• Tomar decisiones más matizadas basadas en resultados intermedios

Para habilitar el pensamiento intercalado, agregue el encabezado beta interleaved-thinking-2025-05-14 a su solicitud de API.

Aquí hay algunas consideraciones importantes para el pensamiento intercalado:

• Con pensamiento intercalado, budget_tokens puede exceder el parámetro max_tokens, ya que representa el presupuesto total en todos los bloques de pensamiento dentro de un turno del asistente.
• El pensamiento intercalado solo se admite para herramientas utilizadas a través de la API de Mensajes.
• El pensamiento intercalado se admite solo para modelos Claude 4, con el encabezado beta interleaved-thinking-2025-05-14.
• Las llamadas directas a la API de Claude le permiten pasar interleaved-thinking-2025-05-14 en solicitudes a cualquier modelo, sin efecto.
• En plataformas de terceros (por ejemplo, Amazon Bedrock y Vertex AI), si pasa interleaved-thinking-2025-05-14 a cualquier modelo que no sea Claude Opus 4.5, Claude Opus 4.1, Opus 4 u Sonnet 4, su solicitud fallará.

Pensamiento extendido con almacenamiento en caché de indicaciones

El almacenamiento en caché de indicaciones con pensamiento tiene varias consideraciones importantes:

Eliminación del contexto del bloque de pensamiento

• Los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar los puntos de ruptura de caché
• Al continuar conversaciones con uso de herramientas, los bloques de pensamiento se almacenan en caché y cuentan como tokens de entrada cuando se leen desde el caché
• Esto crea una compensación: aunque los bloques de pensamiento no consumen espacio de ventana de contexto visualmente, aún cuentan hacia su uso de tokens de entrada cuando se almacenan en caché
• Si el pensamiento se deshabilita, las solicitudes fallarán si pasa contenido de pensamiento en el turno actual de uso de herramientas. En otros contextos, el contenido de pensamiento pasado a la API simplemente se ignora

Patrones de invalidación de caché

• Los cambios en los parámetros de pensamiento (habilitado/deshabilitado o asignación de presupuesto) invalidan los puntos de ruptura de caché de mensajes
• El pensamiento intercalado amplifica la invalidación de caché, ya que los bloques de pensamiento pueden ocurrir entre múltiples llamadas de herramientas
• Los indicadores del sistema y las herramientas permanecen en caché a pesar de los cambios de parámetros de pensamiento o la eliminación de bloques

Comprensión del comportamiento de almacenamiento en caché de bloques de pensamiento

Cuando se usa pensamiento extendido con uso de herramientas, los bloques de pensamiento exhiben un comportamiento de almacenamiento en caché específico que afecta el conteo de tokens:

Cómo funciona:

1. El almacenamiento en caché solo ocurre cuando realiza una solicitud posterior que incluye resultados de herramientas
2. Cuando se realiza la solicitud posterior, el historial de conversación anterior (incluidos los bloques de pensamiento) puede almacenarse en caché
3. Estos bloques de pensamiento en caché cuentan como tokens de entrada en sus métricas de uso cuando se leen desde el caché
4. Cuando se incluye un bloque de usuario sin resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran y se eliminan del contexto

Flujo de ejemplo detallado:

Solicitud 1:

Respuesta 1:

Solicitud 2:

Respuesta 2:

La solicitud 2 escribe un caché del contenido de la solicitud (no de la respuesta). El caché incluye el mensaje de usuario original, el primer bloque de pensamiento, el bloque de uso de herramientas y el resultado de la herramienta.

Solicitud 3:

Para Claude Opus 4.5 y posteriores, todos los bloques de pensamiento anteriores se mantienen de forma predeterminada. Para modelos más antiguos, porque se incluyó un bloque de usuario sin resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran. Esta solicitud se procesará igual que:

Puntos clave:

• Este comportamiento de almacenamiento en caché ocurre automáticamente, incluso sin marcadores cache_control explícitos
• Este comportamiento es consistente ya sea usando pensamiento regular o pensamiento intercalado

Tokens máximos y tamaño de ventana de contexto con pensamiento extendido

En modelos Claude más antiguos (anteriores a Claude Sonnet 3.7), si la suma de tokens de indicación y max_tokens excedía la ventana de contexto del modelo, el sistema ajustaría automáticamente max_tokens para caber dentro del límite de contexto. Esto significaba que podía establecer un valor grande de max_tokens y el sistema lo reduciría silenciosamente según sea necesario.

Con modelos Claude 3.7 y 4, max_tokens (que incluye su presupuesto de pensamiento cuando el pensamiento está habilitado) se aplica como un límite estricto. El sistema ahora devolverá un error de validación si tokens de indicación + max_tokens excede el tamaño de la ventana de contexto.

La ventana de contexto con pensamiento extendido

Al calcular el uso de la ventana de contexto con pensamiento habilitado, hay algunas consideraciones de las que ser consciente:

• Los bloques de pensamiento de turnos anteriores se eliminan y no cuentan hacia su ventana de contexto
• El pensamiento del turno actual cuenta hacia su límite de max_tokens para ese turno

El diagrama a continuación demuestra la gestión especializada de tokens cuando el pensamiento extendido está habilitado:

La ventana de contexto efectiva se calcula como:

Recomendamos usar la API de conteo de tokens para obtener conteos de tokens precisos para su caso de uso específico, especialmente cuando se trabaja con conversaciones de múltiples turnos que incluyen pensamiento.

La ventana de contexto con pensamiento extendido y uso de herramientas

Cuando se usa pensamiento extendido con uso de herramientas, los bloques de pensamiento deben preservarse explícitamente y devolverse con los resultados de herramientas.

El cálculo de ventana de contexto efectiva para pensamiento extendido con uso de herramientas se convierte en:

El diagrama a continuación ilustra la gestión de tokens para pensamiento extendido con uso de herramientas:

Gestión de tokens con pensamiento extendido

Dado el comportamiento de ventana de contexto y max_tokens con pensamiento extendido en modelos Claude 3.7 y 4, puede que necesite:

• Monitorear y gestionar más activamente su uso de tokens
• Ajustar valores de max_tokens a medida que cambia la longitud de su indicación
• Potencialmente usar los puntos finales de conteo de tokens más frecuentemente
• Ser consciente de que los bloques de pensamiento anteriores no se acumulan en su ventana de contexto

Este cambio se ha realizado para proporcionar un comportamiento más predecible y transparente, especialmente a medida que los límites de tokens máximos han aumentado significativamente.

Encriptación de pensamiento

El contenido completo del pensamiento se encripta y se devuelve en el campo signature. Este campo se utiliza para verificar que los bloques de pensamiento fueron generados por Claude cuando se devuelven a la API.

Aquí hay algunas consideraciones importantes sobre la encriptación de pensamiento:

• Cuando transmite respuestas, la firma se agrega a través de un signature_delta dentro de un evento content_block_delta justo antes del evento content_block_stop.
• Los valores de signature son significativamente más largos en modelos Claude 4 que en modelos anteriores.
• El campo signature es un campo opaco y no debe interpretarse ni analizarse - existe únicamente para propósitos de verificación.
• Los valores de signature son compatibles entre plataformas (API de Claude, Amazon Bedrock y Vertex AI). Los valores generados en una plataforma serán compatibles con otra.

Redacción del pensamiento

Ocasionalmente, el razonamiento interno de Claude será marcado por nuestros sistemas de seguridad. Cuando esto ocurre, ciframos parte o todo el bloque thinking y lo devolvemos como un bloque redacted_thinking. Los bloques redacted_thinking se descifran cuando se devuelven a la API, permitiendo que Claude continúe su respuesta sin perder contexto.

Al construir aplicaciones orientadas al cliente que utilizan pensamiento extendido:

• Ten en cuenta que los bloques de pensamiento redactado contienen contenido cifrado que no es legible por humanos
• Considera proporcionar una explicación simple como: "Parte del razonamiento interno de Claude ha sido cifrado automáticamente por razones de seguridad. Esto no afecta la calidad de las respuestas."
• Si muestras bloques de pensamiento a los usuarios, puedes filtrar los bloques redactados mientras preservas los bloques de pensamiento normales
• Sé transparente sobre que el uso de características de pensamiento extendido puede ocasionalmente resultar en que parte del razonamiento sea cifrado
• Implementa manejo de errores apropiado para gestionar gracefully el pensamiento redactado sin romper tu interfaz de usuario

Aquí hay un ejemplo que muestra tanto bloques de pensamiento normales como redactados:

Al pasar bloques thinking y redacted_thinking de vuelta a la API en una conversación de múltiples turnos, debes incluir el bloque completo sin modificar de vuelta a la API para el último turno del asistente. Esto es crítico para mantener el flujo de razonamiento del modelo. Sugerimos siempre pasar todos los bloques de pensamiento a la API. Para más detalles, consulta la sección Preservando bloques de pensamiento arriba.

Diferencias en el pensamiento entre versiones de modelos

La API de Mensajes maneja el pensamiento de manera diferente entre los modelos Claude Sonnet 3.7 y Claude 4, principalmente en el comportamiento de redacción y resumen.

Consulta la tabla a continuación para una comparación condensada:

Preservación de bloques de pensamiento en Claude Opus 4.5

Claude Opus 4.5 introduce un nuevo comportamiento por defecto: los bloques de pensamiento de turnos anteriores del asistente se preservan en el contexto del modelo por defecto. Esto difiere de los modelos anteriores, que eliminan los bloques de pensamiento de turnos anteriores.

Beneficios de la preservación de bloques de pensamiento:

• Optimización de caché: Al usar herramientas, los bloques de pensamiento preservados habilitan aciertos de caché ya que se devuelven con resultados de herramientas y se cachean incrementalmente a través del turno del asistente, resultando en ahorro de tokens en flujos de trabajo de múltiples pasos
• Sin impacto en la inteligencia: Preservar bloques de pensamiento no tiene efecto negativo en el desempeño del modelo

Consideraciones importantes:

• Uso de contexto: Las conversaciones largas consumirán más espacio de contexto ya que los bloques de pensamiento se retienen en el contexto
• Comportamiento automático: Este es el comportamiento por defecto para Claude Opus 4.5—no se requieren cambios de código ni encabezados beta
• Compatibilidad hacia atrás: Para aprovechar esta característica, continúa pasando bloques de pensamiento completos sin modificar de vuelta a la API como lo harías para el uso de herramientas

Precios

Para información completa de precios incluyendo tasas base, escrituras de caché, aciertos de caché y tokens de salida, consulta la página de precios.

El proceso de pensamiento incurre en cargos por:

• Tokens utilizados durante el pensamiento (tokens de salida)
• Bloques de pensamiento del último turno del asistente incluidos en solicitudes posteriores (tokens de entrada)
• Tokens de salida de texto estándar

Cuando se usa pensamiento resumido:

• Tokens de entrada: Tokens en tu solicitud original (excluye tokens de pensamiento de turnos anteriores)
• Tokens de salida (facturados): Los tokens de pensamiento originales que Claude generó internamente
• Tokens de salida (visibles): Los tokens de pensamiento resumido que ves en la respuesta
• Sin cargo: Tokens utilizados para generar el resumen

Mejores prácticas y consideraciones para pensamiento extendido

Trabajar con presupuestos de pensamiento

• Optimización de presupuesto: El presupuesto mínimo es 1,024 tokens. Sugerimos comenzar con el mínimo e incrementar el presupuesto de pensamiento incrementalmente para encontrar el rango óptimo para tu caso de uso. Los recuentos de tokens más altos habilitan razonamiento más comprehensivo pero con retornos decrecientes dependiendo de la tarea. Incrementar el presupuesto puede mejorar la calidad de la respuesta al costo de mayor latencia. Para tareas críticas, prueba diferentes configuraciones para encontrar el balance óptimo. Ten en cuenta que el presupuesto de pensamiento es un objetivo en lugar de un límite estricto—el uso real de tokens puede variar basado en la tarea.
• Puntos de partida: Comienza con presupuestos de pensamiento más grandes (16k+ tokens) para tareas complejas y ajusta basado en tus necesidades.
• Presupuestos grandes: Para presupuestos de pensamiento por encima de 32k, recomendamos usar procesamiento por lotes para evitar problemas de red. Las solicitudes que empujan al modelo a pensar por encima de 32k tokens causan solicitudes de larga duración que podrían chocar contra tiempos de espera del sistema y límites de conexiones abiertas.
• Seguimiento de uso de tokens: Monitorea el uso de tokens de pensamiento para optimizar costos y desempeño.

Consideraciones de desempeño

• Tiempos de respuesta: Prepárate para tiempos de respuesta potencialmente más largos debido al procesamiento adicional requerido para el proceso de razonamiento. Ten en cuenta que generar bloques de pensamiento puede aumentar el tiempo de respuesta general.
• Requisitos de streaming: El streaming es requerido cuando max_tokens es mayor que 21,333. Cuando se usa streaming, prepárate para manejar tanto bloques de contenido de pensamiento como de texto conforme llegan.

Compatibilidad de características

• El pensamiento no es compatible con modificaciones de temperature o top_k así como con uso forzado de herramientas.
• Cuando el pensamiento está habilitado, puedes establecer top_p a valores entre 1 y 0.95.
• No puedes pre-rellenar respuestas cuando el pensamiento está habilitado.
• Los cambios al presupuesto de pensamiento invalidan prefijos de prompts cacheados que incluyen mensajes. Sin embargo, los prompts de sistema cacheados y definiciones de herramientas continuarán funcionando cuando los parámetros de pensamiento cambien.

Directrices de uso

• Selección de tareas: Usa pensamiento extendido para tareas particularmente complejas que se benefician del razonamiento paso a paso como matemáticas, codificación y análisis.
• Manejo de contexto: No necesitas remover bloques de pensamiento anteriores tú mismo. La API de Claude automáticamente ignora bloques de pensamiento de turnos anteriores y no se incluyen cuando se calcula el uso de contexto.
• Ingeniería de prompts: Revisa nuestros consejos de prompting de pensamiento extendido si quieres maximizar las capacidades de pensamiento de Claude.

Próximos pasos