Prompt caching: pagar menos por el contexto que se repite

¿Qué se guarda exactamente?

Un modelo procesa el prompt completo en cada llamada, contando cada token de la ventana de contexto. Muchas aplicaciones envían casi lo mismo una y otra vez: las mismas instrucciones, las mismas definiciones de herramientas, el mismo documento de referencia. Con caché, la API guarda ese prefijo y, si la siguiente petición empieza igual, lo reutiliza.

Según la documentación de Anthropic, el caché cubre “the entire prompt: tools, system, and messages (in that order), up to and including the block designated with cache_control”. Es decir, el orden importa: primero las herramientas, luego el system prompt y al final los mensajes.

¿Cómo se activa?

Hay dos formas. La automática pone un cache_control en el nivel superior de la petición y la API coloca el punto de corte en el último bloque que se puede guardar y lo desplaza a medida que crece la conversación. La explícita pone cache_control en bloques concretos, con hasta cuatro puntos de corte. La explícita da más control, por ejemplo para separar instrucciones estables de un documento que cambia cada semana. El caché automático ocupa uno de esos cuatro lugares, así que si ya marcaste cuatro bloques a mano, la petición con caché automático falla con un error 400.

¿Cuánto cuesta y cuánto dura?

Según la documentación de Anthropic (consultada en noviembre de 2026), los multiplicadores respecto al precio base de entrada son:

El TTL por defecto es de cinco minutos y se renueva sin costo cada vez que el contenido se usa. La opción de una hora conviene cuando el mismo prompt se reutiliza cada cinco minutos a una hora. La lectura es todavía más barata en algunos modelos: 0.05 veces en Claude Opus 5.5 y Sonnet 5.5, y 0.025 veces en Claude Fable 5.1 y Mythos 5.1. Por ejemplo, con Sonnet 5.5 (2 dólares por millón de tokens de entrada) escribir en caché cuesta 2.50 dólares y leer cuesta 0.10 dólares por millón de tokens. Los multiplicadores se combinan con otros descuentos, como el de la Batch API. Revisa la tabla de precios del modelo que uses antes de hacer cuentas.

La cuenta sale a favor cuando el prefijo se reutiliza algunas veces. Si una llamada escribe en caché y nunca se vuelve a leer, pagaste de más.

¿Por qué le importa a un diseñador?

Porque el costo de una función de IA depende de cómo se arma el prompt, y esa decisión suele caer en diseño. Algunas consecuencias prácticas:

• Un asistente con instrucciones largas y estables es un buen candidato a caché. Un asistente que inserta la hora actual al principio del prompt no lo es: cada llamada cambia el prefijo.
• Las plantillas de respuesta, las guías de tono y los catálogos de componentes son contenido estable que conviene poner al inicio. Es parte de la disciplina de context engineering: decidir qué entra y en qué orden.
• Las instrucciones de un archivo como CLAUDE.md son contenido estable por naturaleza, así que suelen ser buenos candidatos.
• Una experiencia que recarga el mismo contexto en cada turno de una conversación gasta de más sin que el usuario lo note.

¿Cuándo NO conviene?

• Cuando cada llamada tiene un prefijo distinto, por ejemplo si el usuario cambia el contexto en cada petición.
• Cuando el prompt es más corto que el mínimo de tokens del modelo. Según la documentación, el mínimo va de 512 a 4,096 tokens según el modelo: 512 en la familia 5.x más reciente (Opus 5.5, Sonnet 5.5 y Haiku 5.5, entre otros), 1,024 en Sonnet 5, Sonnet 4.6 y Sonnet 4.5, 2,048 en Opus 4.7 y 4,096 en Opus 4.6, Opus 4.5 y Haiku 4.5. Si no lo alcanzas, el prompt se procesa sin caché y no hay error, así que conviene revisar los campos de uso.
• Cuando el contenido cambia más rápido que el TTL. Si se renueva cada diez minutos, el caché de cinco no sirve de nada.

Ejemplo

Ejemplo ilustrativo: un equipo de diseño tiene un agente que revisa pantallas contra su sistema de componentes. Cada revisión incluye 30 páginas de reglas y la definición de cuatro herramientas. Antes, cada llamada pagaba ese contexto completo. Después, el equipo mueve las reglas y las herramientas al inicio, pone el cache_control después de ellas y deja la pantalla a revisar al final. Las llamadas dentro de cinco minutos leen el prefijo desde caché, y el costo baja en la parte que se repite. Lo que cambia (la pantalla) queda al final, para no invalidar lo anterior.

¿Cómo sabes si el caché funciona?

La respuesta de la API incluye campos de uso que separan los tokens leídos desde caché (cache_read_input_tokens), los escritos en caché (cache_creation_input_tokens) y los procesados después del último punto de corte (input_tokens). Según la documentación, el total de tokens de entrada es la suma de esas tres partes. Revisa los campos en un par de llamadas reales antes de presupuestar. Si la lectura de caché sigue en cero entre llamadas que deberían compartir prefijo, algo cambia el inicio del prompt: una fecha, un identificador o un orden distinto de herramientas. Registrar esos campos en tu panel de costos es la forma más directa de saber si la optimización funciona.

Qué puedes hacer mañana

Toma un prompt que uses en una aplicación o en un flujo repetido y separa sus partes en tres grupos: lo que nunca cambia, lo que cambia cada día y lo que cambia en cada llamada. Mueve el primer grupo al inicio y el último al final. Después revisa los campos de uso de dos llamadas seguidas y compara las lecturas de caché. Si no mejoran, busca en el inicio del prompt algo que cambie sin que lo notes.

Errores comunes

• Poner la fecha, un ID de usuario o un timestamp al principio del system prompt. Cambia el prefijo en cada llamada.
• Medir el ahorro sin mirar los campos de uso de la respuesta. Hay que comparar lecturas y escrituras de caché.
• Usar la opción de una hora cuando el tráfico es esporádico y el costo de escritura no se recupera.
• Pensar que el caché modifica lo que el modelo responde. Solo cambia el procesamiento de la entrada.

Fuentes

• Prompt caching, documentación de la API de Claude
• How the agent loop works, Agent SDK de Claude Code