Construyendo con pensamiento extendido

El pensamiento extendido proporciona a Claude capacidades de razonamiento mejoradas para tareas complejas, a la vez que ofrece 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 estructuras de la API permanecen exactamente iguales.

Para más información, consulta 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 muestra 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:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Déjame analizar esto paso a paso...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Basado en mi análisis..."
    }
  ]
}

Para más información sobre el formato de respuesta del pensamiento extendido, consulta 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:

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-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
        }
    ]
}'

Para activar el pensamiento extendido, añade un objeto thinking, con el parámetro thinking establecido en enabled y el budget_tokens a un presupuesto específico de tokens para el pensamiento extendido.

El parámetro budget_tokens determina el número máximo de tokens que Claude puede utilizar para su proceso de razonamiento interno. En los modelos Claude 4, este límite se aplica a los tokens de pensamiento completo, y no al resumen de salida. 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 utilizar 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 utiliza pensamiento intercalado con herramientas, puedes exceder este límite ya que el límite de tokens se convierte en toda tu 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, a la vez que previene el uso indebido.

Aquí hay algunas consideraciones importantes para el pensamiento resumido:

Se te cobra por los tokens de pensamiento completo 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 ves en la respuesta.
Las primeras líneas de la salida de pensamiento son más detalladas, proporcionando un razonamiento detallado que es particularmente útil para fines de ingeniería de prompts.
A medida que Anthropic busca mejorar la función de pensamiento extendido, el comportamiento de resumen está sujeto a cambios.
El resumen preserva las ideas clave del proceso de pensamiento de Claude con una latencia mínima añadida, permitiendo una experiencia de usuario transmisible y una fácil migración de los modelos Claude 3.7 a los modelos Claude 4.
El resumen es procesado por un modelo diferente al que se dirige en tus 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 necesites acceso a la salida de pensamiento completa para los modelos Claude 4, contacta a nuestro equipo de ventas.

Transmisión de pensamiento

Puedes transmitir respuestas de pensamiento extendido utilizando eventos enviados por el servidor (SSE).

Cuando la transmisión está habilitada para el pensamiento extendido, recibes contenido de pensamiento a través de eventos thinking_delta.

Para más documentación sobre la transmisión a través de la API de Mensajes, consulta Transmisión de Mensajes.

Aquí se muestra 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-sonnet-4-20250514",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "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-sonnet-4-20250514", "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"}

Cuando se utiliza la transmisión con el pensamiento habilitado, es posible que notes 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 “irregular”, con posibles retrasos entre eventos de transmisión. Estamos trabajando continuamente para mejorar esta experiencia, con actualizaciones futuras centradas en hacer que el contenido de pensamiento se transmita de manera más fluida.

Pensamiento extendido con uso de herramientas

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

Cuando se utiliza el pensamiento extendido con el uso de herramientas, ten en cuenta las siguientes limitaciones:

Limitación de elección de herramientas: El uso de herramientas con pensamiento solo admite tool_choice: any (no specific, auto u otros valores).
Preservación de bloques de pensamiento: Durante el uso de herramientas, debes pasar los bloques thinking de vuelta a la API para el último mensaje del asistente. Incluye el bloque completo sin modificar de vuelta a la API para mantener la continuidad del razonamiento.

Ejemplo: Pasar bloques de pensamiento con resultados de herramientas

Aquí hay un ejemplo práctico que muestra cómo preservar los bloques de pensamiento al proporcionar resultados de herramientas:

weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
}

# First request - Claude responds with thinking and tool request
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)

La respuesta de la API incluirá bloques de pensamiento, texto y uso de herramientas:

{
    "content": [
        {
            "type": "thinking",
            "thinking":  "El usuario quiere saber el clima actual en París. Tengo acceso a una función `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "Puedo ayudarte a obtener la información del clima actual para París. Déjame verificar eso para ti"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

Ahora continuemos la conversación y usemos la herramienta

# Extract thinking block and tool use block
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Call your actual weather API, here is where your actual API call would go
# let's pretend this is what we get back
weather_data = {"temperature": 88}

# Second request - Include thinking block and tool result
# No new thinking blocks will be generated in the response
continuation = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # notice that the thinking_block is passed in as well as the tool_use_block
        # if this is not passed in, an error is raised
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Current temperature: {weather_data['temperature']}°F"
        }]}
    ]
)

La respuesta de la API ahora solo incluirá texto

{
    "content": [
        {
            "type": "text",
            "text": "Actualmente en París, la temperatura es de 88°F (31°C)"
        }
    ]
}

Preservación de bloques de pensamiento

Durante el uso de herramientas, debes pasar los bloques 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.

Aunque puedes omitir los bloques thinking de turnos anteriores del 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
Utilizará 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 Claude invoca herramientas, está pausando la 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 requiere 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 publicas 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 las 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 la gestión del contexto, consulta 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 puedes reorganizar o modificar la secuencia de estos bloques.

Pensamiento intercalado

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

Con el pensamiento intercalado, Claude puede:

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

Para habilitar el pensamiento intercalado, añade el encabezado beta interleaved-thinking-2025-05-14 a tu solicitud de API.

El pensamiento intercalado solo es compatible con herramientas utilizadas a través de la API de Mensajes.

Con el pensamiento intercalado, el budget_tokens puede exceder el parámetro max_tokens ya que representa el presupuesto total a través de todos los bloques de pensamiento dentro de un turno del asistente.

Uso de herramientas sin pensamiento intercalado

import anthropic

client = anthropic.Anthropic()

# Define tools
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request - Claude thinks once before all tool calls
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

# Response includes thinking followed by tool uses
# Note: Claude thinks once at the beginning, then makes all tool decisions
print("First response:")
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking (summarized): {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# You would execute the tools and return results...
# After getting both tool results back, Claude directly responds without additional thinking

En este ejemplo 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 los resultados de las herramientas, Claude proporciona inmediatamente una respuesta sin pensamiento adicional

Uso de herramientas con pensamiento intercalado

import anthropic

client = anthropic.Anthropic()

# Same tool definitions as before
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request with interleaved thinking enabled
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    # Enable interleaved thinking with beta header
    extra_headers={
        "anthropic-beta": "interleaved-thinking-2025-05-14"
    },
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

print("Initial response:")
thinking_blocks = []
tool_use_blocks = []

for block in response.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# First tool result (calculator)
calculator_result = "7500"  # 150 * 50

# Continue with first tool result
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "interleaved-thinking-2025-05-14"
    },
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        }
    ]
)

print("\nAfter calculator result:")
# With interleaved thinking, Claude can think about the calculator result
# before deciding to query the database
for block in response2.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Interleaved thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")

# Second tool result (database)
database_result = "5200"  # Example average monthly revenue

# Continue with second tool result
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "interleaved-thinking-2025-05-14"
    },
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        },
        {
            "role": "assistant",
            "content": thinking_blocks[1:] + tool_use_blocks[1:]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[1].id,
                "content": database_result
            }]
        }
    ]
)

print("\nAfter database result:")
# With interleaved thinking, Claude can think about both results
# before formulating the final response
for block in response3.content:
    if block.type == "thinking":
        print(f"Final thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Final response: {block.text}")

En este ejemplo 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

Este patrón permite cadenas de razonamiento más sofisticadas donde la salida de cada herramienta informa la siguiente decisión.

Pensamiento extendido con almacenamiento en caché de prompts

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

Eliminación de bloques de pensamiento del contexto

Los bloques de pensamiento de turnos anteriores se eliminan del contexto, lo que puede afectar a los puntos de interrupción de la 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 la caché
Esto crea una compensación: mientras que los bloques de pensamiento no consumen espacio de ventana de contexto visualmente, todavía cuentan para tu uso de tokens de entrada cuando se almacenan en caché
Si el pensamiento se desactiva, las solicitudes fallarán si pasas 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 interrupción de la caché de mensajes
El pensamiento intercalado amplifica la invalidación de caché, ya que los bloques de pensamiento pueden ocurrir entre múltiples llamadas a 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 almacenamiento en caché y los cálculos de contexto, deben preservarse al continuar conversaciones con uso de herramientas, especialmente con pensamiento intercalado.

Entendiendo el comportamiento de almacenamiento en caché de bloques de pensamiento

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

Cómo funciona:

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

Flujo de ejemplo detallado:

Solicitud 1:

Usuario: "¿Cuál es el clima en París?"

Respuesta 1:

[thinking_block_1] + [tool_use block 1]

Solicitud 2:

Usuario: ["¿Cuál es el clima en París?"], 
Asistente: [thinking_block_1] + [tool_use block 1], 
Usuario: [tool_result_1, cache=True]

Respuesta 2:

[thinking_block_2] + [text block 2]

La solicitud 2 escribe una caché del contenido de la solicitud (no de la respuesta). La 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:

Usuario: ["¿Cuál es el clima en París?"], 
Asistente: [thinking_block_1] + [tool_use block 1], 
Usuario: [tool_result_1, cache=True], 
Asistente: [thinking_block_2] + [text block 2], 
Usuario: [Respuesta de texto, cache=True]

Debido a que se incluyó un bloque de usuario que no es un resultado de herramienta, todos los bloques de pensamiento anteriores se ignoran. Esta solicitud se procesará igual que:

Usuario: ["¿Cuál es el clima en París?"], 
Asistente: [tool_use block 1], 
Usuario: [tool_result_1, cache=True], 
Asistente: [text block 2], 
Usuario: [Respuesta de texto, cache=True]

Puntos clave:

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

Almacenamiento en caché de prompt del sistema (preservado cuando cambia el pensamiento)

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

SYSTEM_PROMPT=[
    {
        "type": "text",
        "text": "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.",
    },
    {
        "type": "text",
        "text": LARGE_TEXT,
        "cache_control": {"type": "ephemeral"}
    }
]

MESSAGES = [
    {
        "role": "user",
        "content": "Analyze the tone of this passage."
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

# Third request - different thinking parameters (cache miss for messages)
print("\nThird request - different thinking parameters (cache miss for messages)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Changed thinking budget
    },
    system=SYSTEM_PROMPT,  # System prompt remains cached
    messages=MESSAGES  # Messages cache is invalidated
)

print(f"Third response usage: {response3.usage}")

Almacenamiento en caché de mensajes (invalidado cuando cambia el pensamiento)

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

# No system prompt - caching in messages instead
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {
                "type": "text",
                "text": "Analyze the tone of this passage."
            }
        ]
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000  # Same thinking budget
    },
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response2.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the setting in this passage."
})

# Third request - different thinking budget (cache miss expected)
print("\nThird request - different thinking budget (cache miss expected)")
response3 = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Different thinking budget breaks cache
    },
    messages=MESSAGES
)

print(f"Third response usage: {response3.usage}")

Aquí está la salida del script (puedes ver números ligeramente diferentes)

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)

Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

Este ejemplo demuestra que cuando el almacenamiento en caché se configura en el array de mensajes, cambiar los parámetros de pensamiento (budget_tokens aumentado de 4000 a 8000) invalida la caché. La tercera solicitud no muestra ningún acierto de caché con cache_creation_input_tokens=1370 y cache_read_input_tokens=0, lo que demuestra que el almacenamiento en caché basado en mensajes se invalida cuando cambian los parámetros de pensamiento.

Max tokens 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 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 los modelos Claude 3.7 y 4, 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.

Puedes 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 el pensamiento habilitado, hay algunas consideraciones a tener en cuenta:

Los bloques de pensamiento de turnos anteriores se eliminan y no se cuentan para tu ventana de contexto
El pensamiento del turno actual cuenta para 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 encriptados + tokens de salida de texto)

Recomendamos usar la API de conteo de tokens para obtener recuentos precisos de tokens para tu 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 utiliza el pensamiento extendido con uso de herramientas, los bloques de pensamiento deben ser explícitamente preservados y devueltos con los resultados de las herramientas.

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

ventana de contexto =
  (tokens de entrada actuales + tokens de pensamiento anteriores + tokens de uso de herramientas) +
  (tokens de pensamiento + tokens de pensamiento encriptados + tokens de salida de texto)

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

Gestión de 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, 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.

Encriptación de pensamiento

El contenido completo de pensamiento está encriptado y se devuelve en el campo signature. Este campo se utiliza para verificar que los bloques de pensamiento fueron generados por Claude cuando se pasan de vuelta a la API. Cuando se transmiten respuestas, la firma se añade a través de un signature_delta dentro de un evento content_block_delta justo antes del evento content_block_stop.

Ten en cuenta que el campo de firma será significativamente más largo que en modelos anteriores. Este es un campo opaco y no debe ser interpretado o analizado - existe únicamente para fines de verificación.

Solo es estrictamente necesario devolver los bloques de pensamiento cuando se utilizan 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 pasas de vuelta.

Si devuelves bloques de pensamiento, recomendamos devolver todo tal como lo recibiste para mantener la consistencia y evitar posibles problemas.

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 te 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 utilizan 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 el hecho de que usar características 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 interfaz de usuario

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

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Déjame analizar esto paso a paso...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Basado en mi análisis..."
    }
  ]
}

Ver bloques de pensamiento redactados en tu salida es un comportamiento esperado. El modelo todavía 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

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

Ejemplo: Trabajando con bloques de pensamiento redactados

Este ejemplo demuestra cómo manejar bloques redacted_thinking que pueden aparecer en las respuestas cuando el razonamiento interno de Claude contiene contenido marcado por los sistemas de seguridad:

import anthropic

client = anthropic.Anthropic()

# Using a special prompt that triggers redacted thinking (for demonstration purposes only)
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identify redacted thinking blocks
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("Response contains redacted thinking blocks")
    # These blocks are still usable in subsequent requests

    # Extract all blocks (both redacted and non-redacted)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # When passing to subsequent requests, include all blocks without modification
    # This preserves the integrity of Claude's reasoning

    print(f"Found {len(all_thinking_blocks)} thinking blocks total")
    print(f"These blocks are still billable as output tokens")

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:

Característica	Claude Sonnet 3.7	Modelos Claude 4
Salida de Pensamiento	Devuelve la salida de pensamiento completa	Devuelve el pensamiento resumido
Pensamiento Intercalado	No soportado	Soportado con el encabezado beta `interleaved-thinking-2025-05-14`

Precios

El pensamiento extendido utiliza el esquema de precios de tokens estándar:

Modelo	Tokens de Entrada Base	Escrituras en 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 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 el pensamiento extendido está habilitado, se incluye automáticamente un prompt de sistema especializado para soportar esta característica.

Cuando se utiliza el 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 resumidos que ves en la respuesta
Sin cargo: Tokens utilizados para generar el resumen

El recuento de tokens de salida facturados no coincidirá con el recuento de tokens visibles en la respuesta. Se te factura por el proceso de pensamiento completo, no por el resumen que ves.

Mejores prácticas y consideraciones para el pensamiento extendido

Trabajando con presupuestos de pensamiento

Optimización del presupuesto: 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 tu caso de uso. Recuentos de tokens más altos permiten un razonamiento más completo pero con rendimientos decrecientes dependiendo de la tarea. Aumentar el presupuesto puede mejorar la calidad de la respuesta a cambio de una mayor latencia. Para tareas críticas, prueba diferentes configuraciones para encontrar el equilibrio óptimo. Ten en cuenta que 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.
Puntos de partida: Comienza con presupuestos de pensamiento más grandes (16k+ tokens) para tareas complejas y ajusta según 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 los tiempos de espera del sistema y los límites de conexiones abiertas.
Seguimiento del uso de tokens: Monitorea el uso de tokens de pensamiento para optimizar costos y rendimiento.

Consideraciones de rendimiento

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 transmisión: La transmisión es requerida cuando max_tokens es mayor que 21,333. Al transmitir, prepárate para manejar tanto los 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 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 precompletar 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 de sistema en caché y las definiciones de herramientas seguirán funcionando cuando cambien los parámetros de pensamiento.

Directrices de uso

Selección de tareas: Usa el 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 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 de contexto.
Ingeniería de prompts: Revisa nuestros consejos de prompting para pensamiento extendido si quieres maximizar las capacidades de pensamiento de Claude.

Próximos pasos

Prueba el libro de recetas de pensamiento extendido

Explora ejemplos prácticos de pensamiento en nuestro libro de recetas.

Consejos de prompting para pensamiento extendido

Aprende las mejores prácticas de ingeniería de prompts para el pensamiento extendido.

Caché de prompts Mensajes en streaming

On this page

Modelos compatibles
Cómo funciona el pensamiento extendido
Cómo usar el pensamiento extendido
Pensamiento resumido
Transmisión de pensamiento
Pensamiento extendido con uso de herramientas
Preservación de bloques de pensamiento
Pensamiento intercalado
Pensamiento extendido con almacenamiento en caché de prompts
Entendiendo el comportamiento de almacenamiento en caché de bloques de pensamiento
Max tokens y tamaño de ventana de contexto con pensamiento extendido
La ventana de contexto con pensamiento extendido
La ventana de contexto con pensamiento extendido y uso de herramientas
Gestión de tokens con pensamiento extendido
Encriptación de pensamiento
Redacción de pensamiento
Diferencias en el pensamiento entre versiones de modelos
Precios
Mejores prácticas y consideraciones para el pensamiento extendido
Trabajando con presupuestos de pensamiento
Consideraciones de rendimiento
Compatibilidad de características
Directrices de uso
Próximos pasos

Primeros pasos

Modelos y precios

Aprender sobre Claude

Capacidades

Herramientas

Protocolo de contexto del modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer salvaguardas

Centro legal

Construyendo con pensamiento extendido

Modelos compatibles

Cómo funciona el pensamiento extendido

Cómo usar el pensamiento extendido

Pensamiento resumido

Transmisión de pensamiento

Pensamiento extendido con uso de herramientas

Preservación de bloques de pensamiento

Pensamiento intercalado

Pensamiento extendido con almacenamiento en caché de prompts

Entendiendo el comportamiento de almacenamiento en caché de bloques de pensamiento

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

La ventana de contexto con pensamiento extendido

La ventana de contexto con pensamiento extendido y uso de herramientas

Gestión de tokens con pensamiento extendido

Encriptación de pensamiento

Redacción de pensamiento

Diferencias en el pensamiento entre versiones de modelos

Precios

Mejores prácticas y consideraciones para el pensamiento extendido

Trabajando con presupuestos de pensamiento

Consideraciones de rendimiento

Compatibilidad de características

Directrices de uso

Próximos pasos

Prueba el libro de recetas de pensamiento extendido

Consejos de prompting para pensamiento extendido

Primeros pasos

Modelos y precios

Aprender sobre Claude

Capacidades

Herramientas

Protocolo de contexto del modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer salvaguardas

Centro legal

​Modelos compatibles

​Cómo funciona el pensamiento extendido

​Cómo usar el pensamiento extendido

​Pensamiento resumido

​Transmisión de pensamiento

​Pensamiento extendido con uso de herramientas

​Preservación de bloques de pensamiento

​Pensamiento intercalado

​Pensamiento extendido con almacenamiento en caché de prompts

​Entendiendo el comportamiento de almacenamiento en caché de bloques de pensamiento

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

​La ventana de contexto con pensamiento extendido

​La ventana de contexto con pensamiento extendido y uso de herramientas

​Gestión de tokens con pensamiento extendido

​Encriptación de pensamiento

​Redacción de pensamiento

​Diferencias en el pensamiento entre versiones de modelos

​Precios

​Mejores prácticas y consideraciones para el pensamiento extendido

​Trabajando con presupuestos de pensamiento

​Consideraciones de rendimiento

​Compatibilidad de características

​Directrices de uso

​Próximos pasos

Prueba el libro de recetas de pensamiento extendido

Consejos de prompting para pensamiento extendido

Modelos compatibles

Cómo funciona el pensamiento extendido

Cómo usar el pensamiento extendido

Pensamiento resumido

Transmisión de pensamiento

Pensamiento extendido con uso de herramientas

Preservación de bloques de pensamiento

Pensamiento intercalado

Pensamiento extendido con almacenamiento en caché de prompts

Entendiendo el comportamiento de almacenamiento en caché de bloques de pensamiento

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

La ventana de contexto con pensamiento extendido

La ventana de contexto con pensamiento extendido y uso de herramientas

Gestión de tokens con pensamiento extendido

Encriptación de pensamiento

Redacción de pensamiento

Diferencias en el pensamiento entre versiones de modelos

Precios

Mejores prácticas y consideraciones para el pensamiento extendido

Trabajando con presupuestos de pensamiento

Consideraciones de rendimiento

Compatibilidad de características

Directrices de uso

Próximos pasos