Construyendo con pensamiento extendido
El pensamiento extendido le da a Claude capacidades de razonamiento mejoradas para tareas complejas, mientras proporciona diferentes niveles de transparencia en su proceso de pensamiento paso a paso antes de entregar su respuesta final.
Modelos compatibles
El pensamiento extendido es compatible con los siguientes modelos:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
)
El comportamiento de la API difiere entre los modelos Claude 3.7 y Claude 4, pero las formas de la API permanecen exactamente iguales.
Para más información, consulte Diferencias en el pensamiento entre versiones de modelos.
Cómo funciona el pensamiento extendido
Cuando el pensamiento extendido está activado, Claude crea bloques de contenido thinking
donde produce su razonamiento interno. Claude incorpora ideas 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 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 el budget_tokens
a 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 completos, y no a la salida resumida. 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 toda su ventana de contexto (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 todos los beneficios de inteligencia 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 completos generados por la solicitud original, no por los tokens del 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 verbosas, proporcionando razonamiento detallado que es particularmente útil para propósitos de ingeniería de prompts.
- Mientras Anthropic busca mejorar la función de pensamiento extendido, el comportamiento de resumir está sujeto a cambios.
- El resumen preserva las ideas clave del proceso de pensamiento de Claude con latencia mínima agregada, habilitando una experiencia de usuario transmisible y migración fácil de modelos Claude 3.7 a modelos Claude 4.
- El resumen es procesado por un modelo diferente al que usted apunta en sus solicitudes. El modelo de pensamiento no ve la salida resumida.
Claude Sonnet 3.7 continúa devolviendo la salida de pensamiento completa.
En casos raros donde necesite acceso a la salida de pensamiento completa para modelos Claude 4, contacte a nuestro equipo de ventas.
Transmisión de pensamiento
Puede transmitir respuestas de pensamiento extendido usando eventos enviados por el servidor (SSE).
Cuando la transmisión está habilitada para el pensamiento extendido, recibe contenido de pensamiento a través de eventos thinking_delta
.
Para más documentación sobre transmisión a través de la API de Mensajes, consulte Transmisión de Mensajes.
Aquí está cómo manejar la transmisión con pensamiento:
Ejemplo de salida de transmisión:
Cuando use transmisión con pensamiento habilitado, podría notar que el texto a veces llega en fragmentos más grandes alternando con entrega más pequeña, token por token. Este es el comportamiento esperado, especialmente para contenido de pensamiento.
El sistema de transmisión necesita procesar contenido en lotes para un rendimiento óptimo, lo que puede resultar en este patrón de entrega “fragmentado”, con posibles retrasos entre eventos de transmisión. Estamos trabajando continuamente para mejorar esta experiencia, con futuras actualizaciones enfocadas en hacer que el contenido de pensamiento se transmita más suavemente.
Pensamiento extendido con uso de herramientas
El pensamiento extendido puede usarse junto con uso de herramientas, permitiendo a Claude razonar a través de la selección de herramientas y el procesamiento de resultados.
Cuando use pensamiento extendido con uso de herramientas, tenga en cuenta las siguientes limitaciones:
-
Limitación de elección de herramienta: El uso de herramientas con pensamiento solo admite
tool_choice: {"type": "auto"}
(el predeterminado) otool_choice: {"type": "none"}
. Usartool_choice: {"type": "any"}
otool_choice: {"type": "tool", "name": "..."}
resultará en un error porque estas opciones fuerzan el uso de herramientas, lo cual es incompatible con el pensamiento extendido. -
Preservar 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.
Preservar 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 y la integridad de la conversación.
Aunque puede omitir bloques thinking
de turnos assistant
anteriores, sugerimos siempre pasar de vuelta todos los bloques de pensamiento a la API para cualquier conversación de múltiples turnos. La API:
- Filtrará automáticamente los bloques de pensamiento proporcionados
- Usará los bloques de pensamiento relevantes necesarios para preservar el razonamiento del modelo
- Solo facturará por los tokens de entrada para los bloques mostrados a Claude
Cuando Claude invoca herramientas, está pausando su construcción de una respuesta para esperar información externa. Cuando se devuelven los resultados de las herramientas, Claude continuará construyendo esa respuesta existente. Esto hace necesario preservar los bloques de pensamiento durante el uso de herramientas, por un par de razones:
-
Continuidad del razonamiento: Los bloques de pensamiento capturan el razonamiento paso a paso de Claude que llevó a las solicitudes de herramientas. Cuando publique resultados de herramientas, incluir el pensamiento original asegura que Claude pueda continuar su razonamiento desde donde lo dejó.
-
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 los bloques de pensamiento mantiene este flujo conceptual a través de múltiples llamadas a la API. Para más información sobre gestión de contexto, consulte nuestra guía sobre ventanas de contexto.
Importante: Al proporcionar bloques thinking
, toda la secuencia 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 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 el 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, el
budget_tokens
puede exceder el parámetromax_tokens
, ya que representa el presupuesto total a través de todos los bloques de pensamiento dentro de un turno del asistente. - El pensamiento intercalado solo es compatible para herramientas usadas a través de la API de Mensajes.
- El pensamiento intercalado es compatible solo para modelos Claude 4, con el encabezado beta
interleaved-thinking-2025-05-14
. - Las llamadas directas a la API de Anthropic 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 aparte de Claude Opus 4 o Sonnet 4, su solicitud fallará.
Pensamiento extendido con caché de prompts
Caché de prompts con pensamiento tiene varias consideraciones importantes:
Las tareas de pensamiento extendido a menudo toman más de 5 minutos para completarse. Considere usar la duración de caché de 1 hora para mantener aciertos de caché a través de sesiones de pensamiento más largas y flujos de trabajo de múltiples pasos.
Eliminación de contexto de bloques de pensamiento
- Los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar los puntos de interrupción del 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 del caché
- Esto crea un compromiso: aunque los bloques de pensamiento no consumen espacio de ventana de contexto visualmente, aún cuentan hacia su uso de tokens de entrada cuando están en caché
- Si el pensamiento se desactiva, 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 a los parámetros de pensamiento (habilit ado/deshabilitado o asignación de presupuesto) invalidan los puntos de interrupción del caché de mensajes
- Pensamiento intercalado amplifica la invalidación del caché, ya que los bloques de pensamiento pueden ocurrir entre múltiples llamadas de herramientas
- Los prompts del sistema y las herramientas permanecen en caché a pesar de los cambios en los parámetros de pensamiento o la eliminación de bloques
Aunque los bloques de pensamiento se eliminan para el caché y los cálculos de contexto, deben preservarse al continuar conversaciones con uso de herramientas, especialmente con pensamiento intercalado.
Entender el comportamiento de caché de bloques de pensamiento
Cuando use pensamiento extendido con uso de herramientas, los bloques de pensamiento exhiben un comportamiento de caché específico que afecta el conteo de tokens:
Cómo funciona:
- El caché solo ocurre cuando hace una solicitud subsecuente que incluye resultados de herramientas
- Cuando se hace la solicitud subsecuente, el historial de conversación anterior (incluyendo bloques de pensamiento) puede ser almacenado en caché
- Estos bloques de pensamiento en caché cuentan como tokens de entrada en sus métricas de uso cuando se leen del caché
- Cuando se incluye un bloque de usuario que no es resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran y se eliminan del contexto
Ejemplo de flujo detallado:
Solicitud 1:
Respuesta 1:
Solicitud 2:
Respuesta 2:
La Solicitud 2 escribe un caché del contenido de la solicitud (no la respuesta). El caché incluye el mensaje original del usuario, el primer bloque de pensamiento, el bloque de uso de herramienta, y el resultado de la herramienta.
Solicitud 3:
Porque se incluyó un bloque de usuario que no es resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran. Esta solicitud será procesada igual que:
Puntos clave:
- Este comportamiento de caché ocurre automáticamente, incluso sin marcadores explícitos
cache_control
- 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 prompt 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 fuera necesario.
Con los 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 prompt + max_tokens
excede el tamaño de la ventana de contexto.
Puede leer nuestra guía sobre ventanas de contexto para una inmersión más profunda.
La ventana de contexto con pensamiento extendido
Al calcular el uso de la ventana de contexto con pensamiento habilitado, hay algunas consideraciones a tener en cuenta:
- Los bloques de pensamiento de turnos anteriores se eliminan y no se cuentan hacia su ventana de contexto
- El pensamiento del turno actual cuenta hacia su límite
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 trabaje con conversaciones de múltiples turnos que incluyen pensamiento.
La ventana de contexto con pensamiento extendido y uso de herramientas
Cuando use pensamiento extendido con uso de herramientas, los bloques de pensamiento deben preservarse explícitamente y devolverse con los resultados de las 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:
Gestionar tokens con pensamiento extendido
Dado el comportamiento de la ventana de contexto y max_tokens
con los modelos Claude 3.7 y 4 de pensamiento extendido, puede necesitar:
- Monitorear y gestionar más activamente su uso de tokens
- Ajustar valores de
max_tokens
a medida que cambia la longitud de su prompt - Potencialmente usar los endpoints 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 hecho para proporcionar un comportamiento más predecible y transparente, especialmente ya que los límites máximos de tokens han aumentado significativamente.
Encriptación de pensamiento
El contenido de pensamiento completo se encripta y se devuelve en el campo signature
. Este campo se usa para verificar que los bloques de pensamiento fueron generados por Claude cuando se pasan de vuelta a la API.
Solo es estrictamente necesario enviar de vuelta bloques de pensamiento cuando se usan herramientas con pensamiento extendido. De lo contrario, puede omitir bloques de pensamiento de turnos anteriores, o dejar que la API los elimine por usted si los pasa de vuelta.
Si envía de vuelta bloques de pensamiento, recomendamos pasar todo de vuelta como lo recibió para consistencia y para evitar problemas potenciales.
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 eventocontent_block_delta
justo antes del eventocontent_block_stop
. - Los valores de
signature
son significativamente más largos en Claude 4 que en modelos anteriores. - El campo
signature
es un campo opaco y no debe interpretarse o analizarse - existe únicamente para propósitos de verificación. - Los valores de
signature
son compatibles entre plataformas (APIs de Anthropic, Amazon Bedrock, y Vertex AI). Los valores generados en una plataforma serán compatibles con otra.
Redacción de pensamiento
Ocasionalmente el razonamiento interno de Claude será marcado por nuestros sistemas de seguridad. Cuando esto ocurre, encriptamos parte o todo el bloque thinking
y se lo devolvemos como un bloque redacted_thinking
. Los bloques redacted_thinking
se desencriptan cuando se pasan de vuelta a la API, permitiendo a Claude continuar su respuesta sin perder contexto.
Al construir aplicaciones orientadas al cliente que usan pensamiento extendido:
- Sea consciente de que los bloques de pensamiento redactados contienen contenido encriptado que no es legible para humanos
- Considere proporcionar una explicación simple como: “Parte del razonamiento interno de Claude ha sido automáticamente encriptado por razones de seguridad. Esto no afecta la calidad de las respuestas.”
- Si muestra bloques de pensamiento a los usuarios, puede filtrar bloques redactados mientras preserva bloques de pensamiento normales
- Sea transparente de que usar funciones de pensamiento extendido puede ocasionalmente resultar en que algo del razonamiento sea encriptado
- Implemente manejo de errores apropiado para gestionar pensamiento redactado elegantemente sin romper su UI
Aquí hay un ejemplo que muestra tanto bloques de pensamiento normales como redactados:
Ver bloques de pensamiento redactados en su salida es comportamiento esperado. El modelo aún puede usar este razonamiento redactado para informar sus respuestas mientras mantiene barreras de seguridad.
Si necesita probar el manejo de pensamiento redactado en su aplicación, puede usar esta cadena de prueba especial como su prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
Al pasar bloques thinking
y redacted_thinking
de vuelta a la API en una conversación de múltiples turnos, debe 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 de vuelta todos los bloques de pensamiento a la API. Para más detalles, consulte la sección Preservar 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 resumir.
Consulte la tabla a continuación para una comparación condensada:
Característica | Claude Sonnet 3.7 | Modelos Claude 4 |
---|---|---|
Salida de Pensamiento | Devuelve salida de pensamiento completa | Devuelve pensamiento resumido |
Pensamiento Intercalado | No compatible | Compatible con encabezado beta interleaved-thinking-2025-05-14 |
Precios
El pensamiento extendido usa el esquema de precios de tokens estándar:
Modelo | Tokens de Entrada Base | Escrituras de Caché | Aciertos de Caché | Tokens de Salida |
---|---|---|---|---|
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / MTok |
El proceso de pensamiento incurre en cargos por:
- Tokens usados durante el pensamiento (tokens de salida)
- Bloques de pensamiento del último turno del asistente incluidos en solicitudes subsecuentes (tokens de entrada)
- Tokens de salida de texto estándar
Cuando el pensamiento extendido está habilitado, un prompt del sistema especializado se incluye automáticamente para apoyar esta función.
Cuando se usa pensamiento resumido:
- Tokens de entrada: Tokens en su 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 resumidos que ve en la respuesta
- Sin cargo: Tokens usados para generar el resumen
El recuento de tokens de salida facturados no coincidirá con el recuento de tokens visibles en la respuesta. Se le factura por el proceso de pensamiento completo, no por el resumen que ve.
Mejores prácticas y consideraciones para el pensamiento extendido
Trabajar con presupuestos de pensamiento
- Optimización de presupuesto: El presupuesto mínimo es 1,024 tokens. Sugerimos comenzar en el mínimo y aumentar el presupuesto de pensamiento incrementalmente para encontrar el rango óptimo para su caso de uso. Conteos de tokens más altos permiten razonamiento más comprensivo pero con rendimientos decrecientes dependiendo de la tarea. Aumentar el presupuesto puede mejorar la calidad de la respuesta con el compromiso de mayor latencia. Para tareas críticas, pruebe diferentes configuraciones para encontrar el equilibrio óptimo. Note que el presupuesto de pensamiento es un objetivo más que un límite estricto—el uso real de tokens puede variar basado en la tarea.
- Puntos de partida: Comience con presupuestos de pensamiento más grandes (16k+ tokens) para tareas complejas y ajuste basado en sus necesidades.
- Presupuestos grandes: Para presupuestos de pensamiento superiores a 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 conexión abierta.
- Seguimiento de uso de tokens: Monitoree el uso de tokens de pensamiento para optimizar costos y rendimiento.
Consideraciones de rendimiento
- Tiempos de respuesta: Esté preparado para tiempos de respuesta potencialmente más largos debido al procesamiento adicional requerido para el proceso de razonamiento. Considere que generar bloques de pensamiento puede aumentar el tiempo de respuesta general.
- Requisitos de transmisión: La transmisión es requerida cuando
max_tokens
es mayor que 21,333. Cuando transmita, esté preparado para manejar tanto bloques de contenido de pensamiento como de texto a medida que llegan.
Compatibilidad de características
- El pensamiento no es compatible con modificaciones de
temperature
otop_k
así como uso forzado de herramientas. - Cuando el pensamiento está habilitado, puede establecer
top_p
a valores entre 1 y 0.95. - No puede pre-llenar respuestas cuando el pensamiento está habilitado.
- Los cambios al presupuesto de pensamiento invalidan prefijos de prompt en caché que incluyen mensajes. Sin embargo, prompts del sistema en caché y definiciones de herramientas continuarán funcionando cuando cambien los parámetros de pensamiento.
Pautas de uso
- Selección de tareas: Use 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 necesita eliminar bloques de pensamiento anteriores usted mismo. La API de Anthropic automáticamente ignora bloques de pensamiento de turnos anteriores y no se incluyen al calcular el uso de contexto.
- Ingeniería de prompts: Revise nuestros consejos de prompting de pensamiento extendido si quiere maximizar las capacidades de pensamiento de Claude.