Qué es Claude Prompt Caching

Prompt Caching almacena temporalmente un prefijo del prompt. Después, solicitudes posteriores pueden reutilizarlo si ese prefijo sigue siendo idéntico.

Por ejemplo, una aplicación puede tener 30,000 tokens de documentación interna y solamente 50 tokens nuevos por pregunta. Sin caché, el sistema procesa los 30,050 tokens una y otra vez. Sin embargo, con un cache hit gran parte del contexto puede reutilizarse.

Asimismo, la función puede trabajar con tools, system messages, mensajes de texto, imágenes, documentos y resultados de herramientas, según el tipo de bloque compatible.

Cómo funciona Prompt Caching paso a paso

En primer lugar, cuando habilitas la caché, Anthropic comprueba si el prefijo correspondiente ya existe. Si lo encuentra, realiza una lectura. En cambio, si no existe, procesa el contenido y crea una entrada nueva cuando empieza la respuesta.

Cuánto puede reducir el coste Claude Prompt Caching

Anthropic utiliza multiplicadores diferentes para lectura y escritura. Por ello, escribir una caché cuesta más que un input normal. Sin embargo, las lecturas posteriores cuestan mucho menos.

Ejemplo sencillo de ahorro

Imagina que un contexto estable contiene 100,000 tokens y recibe diez preguntas durante la vida de la caché. La primera llamada crea la entrada. Después, las siguientes pueden reutilizar esos 100,000 tokens.

En consecuencia, el ahorro puede ser considerable cuando existe mucha repetición. En cambio, un prompt pequeño que solamente se usa una vez normalmente no se beneficia de la misma forma.

Cómo activar la caché automática en Claude API

En términos generales, la caché automática es la forma más sencilla de empezar. Solo necesitas añadir cache_control a nivel superior de la petición.

Después, Anthropic coloca automáticamente el breakpoint en el último bloque cacheable. Además, en conversaciones de varios turnos el punto avanza conforme crece el historial.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=700,
    cache_control={
        "type": "ephemeral"
    },
    system=(
        "Eres un asistente experto en documentación técnica. "
        "Responde con precisión y utiliza únicamente el contexto disponible."
    ),
    messages=[
        {
            "role": "user",
            "content": "Resume los puntos principales del documento."
        }
    ]
)

print(response.content[0].text)
print(response.usage)

Este enfoque funciona bien cuando el historial crece de forma natural. Sin embargo, puede fallar si el último bloque cacheable cambia en cada petición. Por ejemplo, un timestamp variable puede impedir que coincida el prefijo esperado.

Cuándo utilizar breakpoints explícitos

Por otra parte, los breakpoints explícitos ofrecen más control. En lugar de permitir que Anthropic elija el último bloque cacheable, colocas cache_control exactamente donde termina el contenido reutilizable.

Por ejemplo, puedes cachear un manual grande y dejar fuera la pregunta del usuario. Así, cada solicitud mantiene el mismo prefijo.

import anthropic

client = anthropic.Anthropic()

DOCUMENTATION = """
[DOCUMENTACIÓN LARGA DEL PRODUCTO]
...
"""

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=700,
    system=[
        {
            "type": "text",
            "text": (
                "Eres un asistente de soporte. "
                "No inventes información."
            )
        },
        {
            "type": "text",
            "text": DOCUMENTATION,
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "¿Cómo cancelo una suscripción?"
        }
    ]
)

print(response.content[0].text)
print(response.usage)

TTL de 5 minutos vs caché de 1 hora

De forma predeterminada, Prompt Caching utiliza un TTL de cinco minutos. Además, cada lectura vuelve a refrescar esa entrada sin coste adicional de escritura.

Por tanto, el TTL corto funciona muy bien en aplicaciones con solicitudes frecuentes. Por ejemplo, un chatbot activo puede mantener su contexto caliente mientras el usuario continúa conversando.

Cómo activar el TTL de 1 hora

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=700,
    cache_control={
        "type": "ephemeral",
        "ttl": "1h"
    },
    system="Contexto largo que reutilizaremos.",
    messages=[
        {
            "role": "user",
            "content": "Analiza el primer punto."
        }
    ]
)

Finalmente, recuerda que ambos TTL ofrecen el mismo tipo de mejora de latencia. La diferencia principal está en cuánto tiempo quieres conservar la entrada antes de necesitar una nueva escritura.

Cómo comprobar si Claude Prompt Caching está funcionando

De hecho, no necesitas adivinar si existe un cache hit. Anthropic expone métricas dentro del objeto usage de cada respuesta.

usage = response.usage

print(
    "Cache write:",
    usage.cache_creation_input_tokens
)

print(
    "Cache read:",
    usage.cache_read_input_tokens
)

print(
    "Uncached input:",
    usage.input_tokens
)

total_input = (
    usage.cache_creation_input_tokens
    + usage.cache_read_input_tokens
    + usage.input_tokens
)

print("Total input:", total_input)

Si las dos métricas de caché permanecen en cero, comprueba primero la longitud mínima requerida por el modelo. Después, revisa que el prefijo realmente sea idéntico entre solicitudes.

Cuándo merece la pena utilizar Prompt Caching

El beneficio aumenta cuando una parte grande del input se repite. Por tanto, no todos los workloads necesitan la misma configuración.

Qué puede invalidar la caché de Claude

En primer lugar, Prompt Caching depende de un prefijo idéntico. Por tanto, cualquier cambio relevante antes del breakpoint puede obligar a crear una nueva entrada.

Prompt Caching para agentes y conversaciones largas

Por ejemplo, los agentes suelen reutilizar instrucciones, tools e historial durante varios pasos. Por ello, Prompt Caching puede ser especialmente valioso en workflows agentic.

Además, la caché automática puede mover el punto de caché conforme crece la conversación. Así, el sistema reutiliza el historial anterior y procesa principalmente los turnos recientes.

Sin embargo, Anthropic utiliza una ventana de búsqueda de 20 bloques por breakpoint. Por tanto, conversaciones que añaden muchos bloques por turno pueden necesitar breakpoints adicionales.

Precalentar una caché antes del tráfico

Para workloads con un system prompt muy grande, Anthropic también documenta una estrategia de pre-warming. Primero envías una solicitud que construye la entrada. Después, las solicitudes reales pueden beneficiarse de ella.

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": LONG_SYSTEM_PROMPT,
        "cache_control": {
            "type": "ephemeral"
        }
    }
]

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=0,
    system=SYSTEM_PROMPT,
    messages=[
        {
            "role": "user",
            "content": "warmup"
        }
    ]
)

No obstante, el TTL continúa aplicándose. Por eso, un pre-warm solo tiene sentido cuando esperas tráfico posterior dentro de esa ventana.

Errores frecuentes con Claude Prompt Caching

Preguntas frecuentes sobre Claude Prompt Caching