El pensamiento extendido proporciona a Claude 3.7 Sonnet capacidades de razonamiento mejoradas para tareas complejas, al tiempo que brinda transparencia en su proceso de pensamiento paso a paso antes de entregar su respuesta final.

Cómo funciona el pensamiento extendido

Cuando el pensamiento extendido está activado, Claude crea bloques de contenido thinking donde muestra su razonamiento interno. Claude incorpora las ideas de este razonamiento antes de elaborar una respuesta final.

La respuesta de la API incluirá bloques de contenido tanto thinking como text.

En conversaciones de múltiples turnos, solo los bloques de pensamiento asociados con una sesión de uso de herramientas o un turno del assistant en la última posición del mensaje son visibles para Claude y se facturan como tokens de entrada; los bloques de pensamiento asociados con mensajes anteriores del assistant no son visibles para Claude durante el muestreo y no se facturan como tokens de entrada.

Implementando el pensamiento extendido

Agrega el parámetro thinking y un presupuesto de tokens especificado para usar en el pensamiento extendido a tu solicitud de API.

El parámetro budget_tokens determina el número máximo de tokens que Claude puede usar para su proceso de razonamiento interno. 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.

Tu budget_tokens siempre debe ser menor que el max_tokens especificado.

La respuesta de la API incluirá bloques de contenido tanto de pensamiento como de texto:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "To approach this, let's think about what we know about prime numbers...",
            "signature": "zbbJhbGciOiJFU8zI1NiIsImtakcjsu38219c0.eyJoYXNoIjoiYWJjMTIzIiwiaWFxxxjoxNjE0NTM0NTY3fQ...."
        },
        {
            "type": "text",
            "text": "Yes, there are infinitely many prime numbers such that..."
        }
    ]
}

Entendiendo los bloques de pensamiento

Los bloques de pensamiento representan el proceso de pensamiento interno de Claude. Para permitir que Claude resuelva problemas con restricciones internas mínimas mientras mantiene nuestros estándares de seguridad y nuestras APIs sin estado, hemos implementado lo siguiente:

  • Los bloques de pensamiento contienen un campo signature. Este campo contiene un token criptográfico que verifica que el bloque de pensamiento fue generado por Claude, y se verifica cuando los bloques de pensamiento se devuelven a la API. Al transmitir 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. Solo es estrictamente necesario devolver los bloques de pensamiento cuando se usa uso de herramientas con pensamiento extendido. De lo contrario, puedes omitir los bloques de pensamiento de turnos anteriores, o dejar que la API los elimine por ti si los devuelves.
  • Ocasionalmente, el razonamiento interno de Claude será marcado por nuestros sistemas de seguridad. Cuando esto ocurre, encriptamos parte o todo el bloque thinking y lo devolvemos como un bloque redacted_thinking. Estos bloques de pensamiento redactados se descifran cuando se devuelven a la API, permitiendo que Claude continúe su respuesta sin perder contexto.

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

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpP..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Ver bloques de pensamiento redactados en tu salida es un comportamiento esperado. El modelo aún puede usar este razonamiento redactado para informar sus respuestas mientras mantiene las barreras de seguridad.

Si necesitas probar el manejo de pensamiento redactado en tu aplicación, puedes usar esta cadena especial de prueba como tu prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

Cuando se devuelven bloques thinking y redacted_thinking 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 devolver todos los bloques de pensamiento a la API. Para más detalles, consulta la sección Preservando bloques de pensamiento.

Sugerencias para manejar el pensamiento redactado en producción

Al construir aplicaciones orientadas al cliente que usan pensamiento extendido:

  • Ten en cuenta que los bloques de pensamiento redactado contienen contenido encriptado que no es legible por humanos
  • Considera 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 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 funciones de pensamiento extendido puede ocasionalmente resultar en que algún razonamiento sea encriptado
  • Implementa un manejo de errores apropiado para gestionar el pensamiento redactado sin romper tu UI

Transmitiendo pensamiento extendido

Cuando la transmisión está habilitada, recibirás contenido de pensamiento a través de eventos thinking_delta. Aquí te mostramos cómo manejar la transmisión con pensamiento:

Ejemplo de salida de transmisión:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

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": "27 * 453 = 12,231"}}

// 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"}

Sobre el comportamiento de transmisión con pensamiento

Cuando se usa la transmisión con el pensamiento habilitado, podrías notar que el texto a veces llega en fragmentos más grandes alternando con una entrega más pequeña, token por token. Este es un comportamiento esperado, especialmente para el contenido de pensamiento.

El sistema de transmisión necesita procesar el contenido en lotes para un rendimiento óptimo, lo que puede resultar en este patrón de entrega “fragmentado”. Estamos trabajando continuamente para mejorar esta experiencia, con actualizaciones futuras enfocadas en hacer que el contenido de pensamiento se transmita de manera más fluida.

Los bloques redacted_thinking no tendrán deltas asociados y se enviarán como un solo evento.

Consideraciones importantes al usar el pensamiento extendido

Trabajando con el presupuesto de pensamiento: El presupuesto mínimo es de 1,024 tokens. Sugerimos comenzar con el mínimo y aumentar el presupuesto de pensamiento incrementalmente para encontrar el rango óptimo para que Claude se desempeñe bien en tu caso de uso. Los conteos de tokens más altos pueden permitirte lograr un razonamiento más completo y matizado, pero también puede haber rendimientos decrecientes dependiendo de la tarea.

  • El presupuesto de pensamiento es un objetivo más que un límite estricto - el uso real de tokens puede variar según la tarea.
  • Prepárate para tiempos de respuesta potencialmente más largos debido al procesamiento adicional requerido para el proceso de razonamiento.
  • Se requiere transmisión cuando max_tokens es mayor que 21,333.

Para presupuestos de pensamiento por encima de 32K: Recomendamos usar procesamiento por lotes para cargas de trabajo donde el presupuesto de pensamiento se establece por encima de 32K 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 los tiempos de espera del sistema y los límites de conexiones abiertas.

Compatibilidad del pensamiento con otras características:

  • El pensamiento no es compatible con modificaciones de temperature, top_p, o top_k así como con uso forzado de herramientas.
  • No puedes pre-llenar respuestas cuando el pensamiento está habilitado.
  • Los cambios en el presupuesto de pensamiento invalidan los prefijos de prompt en caché que incluyen mensajes. Sin embargo, los prompts del sistema en caché y las definiciones de herramientas seguirán funcionando cuando cambien los parámetros de pensamiento.

Precios y uso de tokens para el pensamiento extendido

Los tokens de pensamiento extendido cuentan hacia la ventana de contexto y se facturan como tokens de salida. Dado que los tokens de pensamiento se tratan como tokens de salida normales, también cuentan hacia tus límites de tasa. Asegúrate de tener en cuenta este mayor uso de tokens al planificar tu uso de la API.

Para Claude 3.7 Sonnet, los precios son:

Uso de tokensCosto
Tokens de entrada$3 / MTok
Tokens de salida (incluyendo tokens de pensamiento)$15 / MTok
Escritura en caché de prompt$3.75 / MTok
Lectura de caché de prompt$0.30 / MTok

El procesamiento por lotes para el pensamiento extendido está disponible con un 50% de descuento sobre estos precios y a menudo se completa en menos de 1 hora.

Todos los tokens de pensamiento extendido (incluyendo los tokens de pensamiento redactado) se facturan como tokens de salida y cuentan hacia tus límites de tasa.

En conversaciones de múltiples turnos, los bloques de pensamiento asociados con mensajes anteriores del asistente no se facturan como tokens de entrada.

Cuando el pensamiento extendido está habilitado, se incluye automáticamente un prompt del sistema especializado de 28 o 29 tokens para soportar esta característica.

Capacidades de salida extendida (beta)

Claude 3.7 Sonnet puede producir respuestas sustancialmente más largas que los modelos anteriores con soporte para hasta 128K tokens de salida (beta)—más de 15 veces más largo que otros modelos de Claude. Esta capacidad expandida es particularmente efectiva para casos de uso de pensamiento extendido que involucran razonamiento complejo, generación de código rica y creación de contenido integral.

Esta característica se puede habilitar pasando un encabezado anthropic-beta de output-128k-2025-02-19.

Cuando uses pensamiento extendido con salidas más largas, puedes asignar un presupuesto de pensamiento más grande para soportar un razonamiento más exhaustivo, mientras aún tienes tokens amplios disponibles para la respuesta final.

Sugerimos usar transmisión o modo por lotes con esta capacidad de salida extendida; para más detalles consulta nuestra guía sobre consideraciones de fiabilidad de red para solicitudes largas.

Usando el pensamiento extendido con caché de prompts

El caché de prompts con pensamiento tiene varias consideraciones importantes:

Inclusión de bloques de pensamiento en prompts en caché

  • El pensamiento solo se incluye cuando se genera un turno del asistente y no está destinado a ser cacheado.
  • Los bloques de pensamiento de turnos anteriores son ignorados.
  • Si el pensamiento se deshabilita, cualquier contenido de pensamiento pasado a la API simplemente se ignora.

Reglas de invalidación de caché

  • Las alteraciones a los parámetros de pensamiento (habilitar/deshabilitar o cambios de presupuesto) invalidan los puntos de ruptura de caché establecidos en los mensajes.
  • Los prompts del sistema y las herramientas mantienen el caché incluso cuando cambian los parámetros de pensamiento.

Ejemplos de caché de prompts con pensamiento extendido

Max tokens y tamaño de ventana de contexto con pensamiento extendido

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

Con Claude 3.7 Sonnet, max_tokens (que incluye tu 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.

Cómo se calcula la ventana de contexto con pensamiento extendido

Al calcular el uso de la ventana de contexto con el pensamiento habilitado, hay algunas consideraciones a tener en cuenta:

  • Los bloques de pensamiento de turnos anteriores se eliminan y no se cuentan hacia tu ventana de contexto
  • El pensamiento del turno actual cuenta hacia tu 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:

ventana de contexto =
  (tokens de entrada actuales - tokens de pensamiento anteriores) +
  (tokens de pensamiento + tokens de pensamiento redactado + tokens de salida de texto)

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

Puedes leer nuestra guía sobre ventanas de contexto para una inmersión más profunda.

Gestionando tokens con pensamiento extendido

Dado el nuevo comportamiento de ventana de contexto y max_tokens con modelos de pensamiento extendido como Claude 3.7 Sonnet, es posible que necesites:

  • Monitorear y gestionar más activamente tu uso de tokens
  • Ajustar los valores de max_tokens a medida que cambia la longitud de tu prompt
  • Potencialmente usar los endpoints de conteo de tokens con más frecuencia
  • Ser consciente de que los bloques de pensamiento anteriores no se acumulan en tu ventana de contexto

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

Pensamiento extendido con uso de herramientas

Cuando uses pensamiento extendido con uso de herramientas, ten en cuenta el siguiente patrón de comportamiento:

  1. Primer turno del asistente: Cuando envías un mensaje inicial del usuario, la respuesta del asistente incluirá bloques de pensamiento seguidos por solicitudes de uso de herramientas.

  2. Turno de resultado de herramienta: Cuando pasas el mensaje del usuario con bloques de resultado de herramienta, el mensaje subsiguiente del asistente no contendrá bloques de pensamiento adicionales.

Para expandir aquí, el orden normal de una conversación de uso de herramientas con pensamiento sigue estos pasos:

  1. El usuario envía el mensaje inicial
  2. El asistente responde con bloques de pensamiento y solicitudes de herramientas
  3. El usuario envía mensaje con resultados de herramientas
  4. El asistente responde con más llamadas a herramientas o solo texto (sin bloques de pensamiento en esta respuesta)
  5. Si se solicitan más herramientas, repite los pasos 3-4 hasta que la conversación esté completa

Este diseño permite que Claude muestre su proceso de razonamiento antes de hacer solicitudes de herramientas, pero no repita el proceso de pensamiento después de recibir resultados de herramientas. Claude no generará otro bloque de pensamiento hasta después del siguiente turno de user que no sea tool_result.

El diagrama a continuación ilustra la gestión de tokens de ventana de contexto cuando se combina pensamiento extendido con uso de herramientas:

Preservando bloques de pensamiento

Durante el uso de herramientas, debes pasar bloques thinking y redacted_thinking de vuelta a la API, y debes 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.

Si bien puedes omitir bloques thinking y redacted_thinking de turnos anteriores con rol assistant, sugerimos siempre devolver 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á los tokens de entrada para los bloques mostrados a Claude

Por qué los bloques de pensamiento deben ser preservados

Cuando Claude invoca herramientas, está pausando su construcción de una respuesta para esperar información externa. Cuando se devuelven los resultados de la herramienta, Claude continuará construyendo esa respuesta existente. Esto necesita preservar los 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 llevó a las solicitudes de herramientas. Cuando publicas resultados de herramientas, incluir el pensamiento original asegura que Claude pueda continuar su razonamiento desde donde lo dejó.

  2. Mantenimiento del contexto: Si bien 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.

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

Consejos para hacer el mejor uso del modo de pensamiento extendido

Para obtener el máximo provecho del pensamiento extendido:

  1. Establece presupuestos apropiados: Comienza con presupuestos de pensamiento más grandes (16,000+ tokens) para tareas complejas y ajusta según tus necesidades.

  2. Experimenta con presupuestos de tokens de pensamiento: El modelo podría comportarse de manera diferente con diferentes configuraciones de presupuesto máximo de pensamiento. Aumentar el presupuesto máximo de pensamiento puede hacer que el modelo piense mejor/más duro, a cambio de una mayor latencia. Para tareas críticas, considera probar diferentes configuraciones de presupuesto para encontrar el equilibrio óptimo entre calidad y rendimiento.

  3. No necesitas eliminar los bloques de pensamiento anteriores tú mismo: La API de Anthropic ignora automáticamente los bloques de pensamiento de turnos anteriores y no se incluyen al calcular el uso del contexto.

  4. Monitorea el uso de tokens: Mantén un registro del uso de tokens de pensamiento para optimizar costos y rendimiento.

  5. Usa el pensamiento extendido para tareas particularmente complejas: Habilita el pensamiento para tareas que se benefician del razonamiento paso a paso como matemáticas, codificación y análisis.

  6. Ten en cuenta el tiempo de respuesta extendido: Ten en cuenta que generar bloques de pensamiento puede aumentar el tiempo de respuesta general.

  7. Maneja la transmisión apropiadamente: Al transmitir, prepárate para manejar tanto bloques de contenido de pensamiento como de texto a medida que llegan.

  8. Ingeniería de prompts: Revisa nuestros consejos de prompting para pensamiento extendido si quieres maximizar las capacidades de pensamiento de Claude.

Próximos pasos