Construyendo con pensamiento extendido

El pensamiento extendido le da a Claude 3.7 Sonnet capacidades de razonamiento mejoradas para tareas complejas, al mismo tiempo que proporciona 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 de thinking como de text.

En conversaciones de múltiples turnos, solo los bloques de pensamiento asociados con una sesión de uso de herramientas o 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

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

El parámetro budget_tokens determina el número máximo de tokens que se le permite usar a Claude 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.

Su budget_tokens siempre debe ser menor que el max_tokens especificado.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
        }
    ]
}'

​

Entendiendo los bloques de pensamiento

Los bloques de pensamiento representan el proceso de pensamiento interno de Claude. Para permitir que Claude trabaje en 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 bloques de pensamiento cuando se usa uso de herramientas con pensamiento extendido. De lo contrario, puede omitir los bloques de pensamiento de turnos anteriores, o dejar que la API los elimine por usted si los devuelve.
• 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. Estos bloques de pensamiento redactados se descifran cuando se devuelven a la API, permitiendo que Claude continúe su respuesta sin perder contexto.
• Los bloques thinking y redacted_thinking se devuelven antes de los bloques text en la respuesta.

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..."
    }
  ]
}

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

import anthropic

client = anthropic.Anthropic()

# Usando un prompt especial que activa el pensamiento redactado (solo para demostración)
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identificar bloques de pensamiento redactados
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("La respuesta contiene bloques de pensamiento redactados")
    # Estos bloques aún son utilizables en solicitudes subsiguientes

    # Extraer todos los bloques (tanto redactados como no redactados)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # Al pasar a solicitudes subsiguientes, incluir todos los bloques sin modificación
    # Esto preserva la integridad del razonamiento de Claude

    print(f"Se encontraron {len(all_thinking_blocks)} bloques de pensamiento en total")
    print(f"Estos bloques aún son facturables como tokens de salida")

​

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 redactados 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

​

Transmisión de 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:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

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

[Continúa la traducción en el siguiente mensaje debido a limitaciones de longitud…]