Modelos soportados
El pensamiento extendido es compatible con los siguientes modelos:- Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929) - Claude Sonnet 4 (
claude-sonnet-4-20250514) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219) (deprecado) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001) - Claude Opus 4.1 (
claude-opus-4-1-20250805) - Claude Opus 4 (
claude-opus-4-20250514)
El comportamiento de la API difiere entre los modelos Claude Sonnet 3.7 y Claude 4, pero las formas de la API siguen siendo 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 contenidothinking 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:
Cómo usar el pensamiento extendido
Aquí hay un ejemplo de uso del pensamiento extendido en la API de Mensajes: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 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.
Claude Sonnet 3.7 continúa devolviendo la salida de pensamiento completo.En casos raros donde necesita acceso a la salida de pensamiento completo para modelos Claude 4, contacte a nuestro equipo de ventas.
Pensamiento en streaming
Puede hacer streaming de respuestas de pensamiento extendido usando eventos enviados por el servidor (SSE). Cuando el streaming está habilitado para el pensamiento extendido, recibe contenido de pensamiento a través de eventosthinking_delta.
Para más documentación sobre streaming a través de la API de Mensajes, consulte Streaming de Mensajes.
Aquí se muestra cómo manejar el streaming con pensamiento:
Cuando se usa streaming con pensamiento habilitado, es posible que note que el texto a veces llega en fragmentos más grandes alternando con entrega token por token. Este es el comportamiento esperado, especialmente para contenido de pensamiento.El sistema de streaming necesita procesar contenido en lotes para un rendimiento óptimo, lo que puede resultar en este patrón de entrega “fragmentada”, con posibles retrasos entre eventos de streaming. 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 se puede usar junto con uso de herramientas, permitiendo que Claude razone 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:-
Limitación de elección de herramienta: El uso de herramientas con pensamiento solo soporta
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, que es incompatible con el pensamiento extendido. -
Preservar bloques de pensamiento: Durante el uso de herramientas, debe pasar bloques
thinkingde 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.
Alternar modos de pensamiento en conversaciones
No puede alternar el pensamiento en medio de un turno del asistente, incluyendo 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
Escenarios de error comunes
Puede encontrar este error:- Tenía pensamiento deshabilitado durante una secuencia de uso de herramientas
- Quiere habilitar pensamiento nuevamente
- Su último mensaje del asistente contiene bloques de uso de herramientas pero sin bloque de pensamiento
Orientación práctica
✗ Inválido: Alternar pensamiento inmediatamente después del uso de herramientasAlternar modos de pensamiento también invalida el almacenamiento en caché de prompts para el historial de mensajes. Para más detalles, consulte la sección Pensamiento extendido con almacenamiento en caché de prompts.
Ejemplo: Pasar bloques de pensamiento con resultados de herramientas
Ejemplo: Pasar bloques de pensamiento con resultados de herramientas
Aquí hay un ejemplo práctico que muestra cómo preservar bloques de pensamiento al proporcionar resultados de herramientas:La respuesta de la API incluirá bloques de pensamiento, texto y tool_use:Ahora continuemos la conversación y usemos la herramientaLa respuesta de la API ahora solo incluirá texto
Preservar bloques de pensamiento
Durante el uso de herramientas, debe pasar bloquesthinking 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.
Aunque puede omitir bloques
thinking de turnos anteriores del assistant, sugerimos siempre pasar todos los bloques de pensamiento de vuelta 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á los tokens de entrada para los bloques mostrados a Claude
Cuando alterna modos de pensamiento durante una conversación, recuerde que el turno completo del asistente (incluyendo bucles de uso de herramientas) debe operar en un único modo de pensamiento. Para más detalles, consulte Alternar modos de pensamiento en conversaciones.
- Continuidad del razonamiento: Los bloques de pensamiento capturan el razonamiento paso a paso de Claude que llevó a solicitudes de herramientas. Cuando publica 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 bloques de pensamiento mantiene este flujo conceptual a través de múltiples llamadas de API. Para más información sobre gestión de contexto, consulte nuestra guía sobre ventanas de contexto.
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 soporta pensamiento intercalado, que permite que Claude piense entre llamadas de herramientas y haga 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
interleaved-thinking-2025-05-14 a su solicitud de API.
Aquí hay algunas consideraciones importantes para pensamiento intercalado:
- Con pensamiento intercalado,
budget_tokenspuede exceder el parámetromax_tokens, ya que representa el presupuesto total en todos los bloques de pensamiento dentro de un turno del asistente. - El pensamiento intercalado solo es soportado para herramientas usadas a través de la API de Mensajes.
- El pensamiento intercalado es soportado para modelos Claude 4 solo, con el encabezado beta
interleaved-thinking-2025-05-14. - Las llamadas directas a la API de Claude le permiten pasar
interleaved-thinking-2025-05-14en solicitudes a cualquier modelo, sin efecto. - En plataformas de terceros (p. ej., Amazon Bedrock y Vertex AI), si pasa
interleaved-thinking-2025-05-14a cualquier modelo que no sea Claude Opus 4.1, Opus 4, o Sonnet 4, su solicitud fallará.
Uso de herramientas sin pensamiento intercalado
Uso de herramientas sin pensamiento intercalado
- Claude piensa una vez al principio para entender la tarea
- Toma todas las decisiones de uso de herramientas por adelantado
- Cuando se devuelven resultados de herramientas, Claude proporciona inmediatamente una respuesta sin pensamiento adicional
Uso de herramientas con pensamiento intercalado
Uso de herramientas con pensamiento intercalado
- Claude piensa sobre la tarea inicialmente
- Después de recibir el resultado de la calculadora, Claude puede pensar nuevamente sobre lo que significa ese resultado
- Claude luego decide cómo consultar la base de datos basándose en el primer resultado
- Después de recibir el resultado de la base de datos, Claude piensa una vez más sobre ambos resultados antes de formular una respuesta final
- El presupuesto de pensamiento se distribuye entre todos los bloques de pensamiento dentro del turno
Pensamiento extendido con almacenamiento en caché de prompts
El almacenamiento en caché de prompts con pensamiento tiene varias consideraciones importantes:Las tareas de pensamiento extendido a menudo tardan más de 5 minutos en completarse. Considere usar la duración de caché de 1 hora para mantener aciertos de caché en sesiones de pensamiento más largas y flujos de trabajo de múltiples pasos.
- Los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar los puntos de ruptura de caché
- Cuando se continúan 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 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
- 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 prompts del sistema y las herramientas permanecen en caché a pesar de cambios en parámetros de pensamiento o eliminación de bloques
Aunque los bloques de pensamiento se eliminan para el almacenamiento en caché y cálculos de contexto, deben preservarse cuando se continúan conversaciones con uso de herramientas, especialmente con pensamiento intercalado.
Entender el 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 recuento de tokens: Cómo funciona:- El almacenamiento en caché solo ocurre cuando realiza una solicitud posterior que incluye resultados de herramientas
- Cuando se realiza la solicitud posterior, el historial de conversación anterior (incluyendo bloques de pensamiento) puede almacenarse 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 sin resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran y se eliminan del contexto
- Este comportamiento de almacenamiento en caché ocurre automáticamente, incluso sin marcadores
cache_controlexplícitos - Este comportamiento es consistente ya sea usando pensamiento regular o pensamiento intercalado
Almacenamiento en caché de prompt del sistema (preservado cuando cambia el pensamiento)
Almacenamiento en caché de prompt del sistema (preservado cuando cambia el pensamiento)
Almacenamiento en caché de mensajes (invalidado cuando cambia el pensamiento)
Almacenamiento en caché de mensajes (invalidado cuando cambia el pensamiento)
cache_creation_input_tokens=1370 y cache_read_input_tokens=0, probando que el almacenamiento en caché basado en mensajes se invalida cuando cambian los parámetros de pensamiento.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 ymax_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 los tokens de prompt + max_tokens exceden el tamaño de la ventana de contexto.
Puede leer nuestra guía sobre ventanas de contexto para un análisis más profundo.
La ventana de contexto con pensamiento extendido
Cuando se calcula 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_tokenspara ese turno
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 efectivo de la ventana de contexto para pensamiento extendido con uso de herramientas se convierte en:Gestionar tokens con pensamiento extendido
Dado el comportamiento de ventana de contexto ymax_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_tokensa medida que cambia la longitud de su prompt - 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
Encriptación de pensamiento
El contenido de pensamiento completo se encripta y se devuelve en el camposignature. Este campo se usa para verificar que los bloques de pensamiento fueron generados por Claude cuando se devuelven a la API.
Es solo estrictamente necesario enviar bloques de pensamiento de vuelta 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 devuelve.Si envía bloques de pensamiento de vuelta, recomendamos devolver todo tal como lo recibió para consistencia y para evitar posibles problemas.
- Cuando se hace streaming de respuestas, la firma se agrega a través de un
signature_deltadentro de un eventocontent_block_deltajusto antes del eventocontent_block_stop. - Los valores de
signatureson significativamente más largos en modelos Claude 4 que en modelos anteriores. - El campo
signaturees un campo opaco y no debe interpretarse o analizarse - existe únicamente para propósitos de verificación. - Los valores de
signatureson compatibles entre plataformas (APIs de Claude, 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 bloquethinking y lo devolvemos como un bloque redacted_thinking. Los bloques redacted_thinking se desencriptan cuando se devuelven a la API, permitiendo que Claude continúe su respuesta sin perder contexto.
Cuando se construyen aplicaciones orientadas al cliente que usan pensamiento extendido:
- Sea consciente de que los bloques de pensamiento redactado contienen contenido encriptado que no es legible por humanos
- Considere proporcionar una explicación simple como: “Parte del razonamiento interno de Claude ha sido encriptado automáticamente por razones de seguridad. Esto no afecta la calidad de las respuestas.”
- Si muestra bloques de pensamiento a usuarios, puede filtrar bloques redactados mientras preserva bloques de pensamiento normales
- Sea transparente de que usar características de pensamiento extendido puede ocasionalmente resultar en que parte del razonamiento sea encriptado
- Implemente manejo de errores apropiado para gestionar gracefully el pensamiento redactado sin romper su interfaz de usuario
Ver bloques de pensamiento redactado en su salida es comportamiento esperado. El modelo aún puede usar este razonamiento redactado para informar sus respuestas mientras mantiene salvaguardas 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_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CBthinking 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 devolver todos los bloques de pensamiento a la API. Para más detalles, consulte la sección Preservar bloques de pensamiento arriba.
Ejemplo: Trabajar con bloques de pensamiento redactado
Ejemplo: Trabajar con bloques de pensamiento redactado
Este ejemplo demuestra cómo manejar bloques
redacted_thinking que pueden aparecer en respuestas cuando el razonamiento interno de Claude contiene contenido marcado por sistemas de seguridad:Diferencias en el pensamiento entre versiones de modelos
La API de Mensajes maneja el pensamiento de manera diferente entre modelos Claude Sonnet 3.7 y Claude 4, principalmente en el comportamiento de redacción y resumen. 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 completo | Devuelve pensamiento resumido |
| Pensamiento intercalado | No soportado | Soportado 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.1 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $0.30 / MTok | $15 / 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 |
- Tokens usados 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 el pensamiento extendido está habilitado, un prompt del sistema especializado se incluye automáticamente para soportar esta característica.
- 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 cobra por el proceso de pensamiento completo, no por el resumen que ve.
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 gradualmente para encontrar el rango óptimo para su caso de uso. Los recuentos de tokens más altos permiten un razonamiento más exhaustivo pero con rendimientos decrecientes dependiendo de la tarea. Aumentar el presupuesto puede mejorar la calidad de la respuesta al costo de mayor latencia. Para tareas críticas, pruebe diferentes configuraciones para encontrar el equilibrio óptimo. Tenga 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: Comience con presupuestos de pensamiento más grandes (16k+ tokens) para tareas complejas y ajuste según sea necesario.
- Presupuestos grandes: Para presupuestos de pensamiento superiores a 32k, recomendamos usar procesamiento por lotes para evitar problemas de red. Las solicitudes que empujan el modelo a pensar por encima de 32k tokens causan solicitudes de larga duración que podrían encontrarse con límites de tiempo 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: Prepárese para tiempos de respuesta potencialmente más largos debido al procesamiento adicional requerido para el proceso de razonamiento. Tenga en cuenta que generar bloques de pensamiento puede aumentar el tiempo de respuesta general.
- Requisitos de streaming: El streaming es requerido cuando
max_tokenses mayor que 21.333. Cuando se hace streaming, prepárese para manejar bloques de contenido tanto de pensamiento como de texto a medida que llegan.
Compatibilidad de características
- El pensamiento no es compatible con modificaciones de
temperatureotop_kasí como fuerza de uso de herramientas. - Cuando el pensamiento está habilitado, puede establecer
top_pen valores entre 1 y 0.95. - No puede rellenar previamente respuestas cuando el pensamiento está habilitado.
- Los cambios en el pres presupuesto de pensamiento invalidan los prefijos de prompts en caché que incluyen mensajes. Sin embargo, los prompts del sistema en caché y definiciones de herramientas continuarán funcionando cuando cambien los parámetros de pensamiento.
Directrices 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 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: Revise nuestros consejos de prompting de pensamiento extendido si desea maximizar las capacidades de pensamiento de Claude.