Agrega caché de prompts a una llamada de la API de Claude

La caché de prompts es la mejora de rendimiento más barata de la API de Claude, y también la que más gente cree tener activada sin que sea cierto. El modelo mental cabe en una frase: la caché es un match por prefijo, y cualquier cambio de un byte en el prefijo invalida todo lo que viene después. Si ordenas bien, casi todo el ahorro te sale gratis. Si ordenas mal, pones un marcador cache_control, no ves ningún error y terminas pagando precio completo en cada request sin enterarte. Esta guía recorre la mecánica real, un ejemplo en TypeScript, los números que te dicen si de verdad vale la pena, y los invalidadores silenciosos que te tumban el hit rate.

00 · Requisitos previos

Necesitas tres cosas listas. Es un checklist de cinco minutos, no un proyecto.

• Una llamada a Claude que ya haces de forma repetida: mismo contexto grande, cola distinta. La caché solo rinde si hay repetición. Un prompt de una sola vez no tiene nada que reusar.
• El paquete @anthropic-ai/sdk instalado y una ANTHROPIC_API_KEY en tu entorno. Los ejemplos asumen Opus 4.8, pero todo aplica igual a Sonnet 4.6 y Haiku 4.5.
• Una forma de leer response.usage después de la llamada. Ese objeto es tu única fuente de verdad para saber si la caché está funcionando. Sin él, estás adivinando.

01 · Cómo funciona el match por prefijo

La clave de caché sale de los bytes exactos del prompt renderizado hasta cada breakpoint de cache_control. La API arma tu request en un orden fijo: primero tools, luego system, luego messages. Todo lo que esté antes de un breakpoint tiene que ser idéntico byte por byte entre llamadas para que ese breakpoint pegue.

En ese orden está toda la jugada. Un cambio en una sección anterior invalida la caché de todo lo que viene después, porque los bytes del prefijo ya no coinciden. En concreto:

• Cambias una definición de tool (agregas, quitas o reordenas) e invalidas tools, system y messages: la caché completa.
• Cambias el system prompt y conservas la caché de tools, pero pierdes system y messages.
• Agregas un nuevo turno de usuario y conservas tools y system. Ese es el caso normal, el que no te duele.

La regla práctica que sale de esto: lo estable va primero, lo volátil va al final. Tu bloque de instrucciones congelado, tus documentos recuperados, tu lista de tools van adelante, antes del breakpoint. La pregunta real del usuario, la fecha de hoy, un ID de request van después.

02 · Agregar el breakpoint

Agrega un marcador cache_control al último bloque que quieras incluir en el prefijo cacheado. La forma más simple es el auto-cacheo a nivel raíz, que coloca el marcador por ti en el último bloque cacheable:

import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic()

const res = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" }, // cachea el último bloque cacheable
  system: longInstructionsAndPolicy,    // grande y estable: vive en el prefijo
  messages,                             // la cola que cambia
})

Cuando necesitas más precisión, cachear solo la parte compartida de un request mientras la cola varía, pon el marcador en un bloque de contenido específico. El patrón de abajo cachea un preámbulo compartido y deja la pregunta variable sin cachear, para que cada request lea el mismo prefijo en vez de escribir una entrada nueva que nunca va a reusar:

const res = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: longInstructionsAndPolicy,
      cache_control: { type: "ephemeral" }, // TTL de 5 minutos por defecto
    },
  ],
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: sharedRetrievedDocs, cache_control: { type: "ephemeral" } },
        { type: "text", text: usersQuestion }, // sin marcador: cambia cada vez
      ],
    },
  ],
})

Tienes un máximo de 4 breakpoints por request, y cache_control puede ir en cualquier bloque de contenido: texto de system, definiciones de tools o bloques de mensaje. Para un set largo de instrucciones más una lista fija de tools, un breakpoint en el último bloque de system cachea tools y system juntos, porque tools se renderiza antes que system.

03 · Confirmar que de verdad pegaste un hit

Este es el paso que todo el mundo se salta, y es el único que te dice la verdad. El objeto usage de cada respuesta te reporta exactamente lo que pasó:

• cache_creation_input_tokens: tokens escritos a la caché en este request, cobrados al premium de write de 1.25x.
• cache_read_input_tokens: tokens servidos desde la caché, cobrados como a 0.1x.
• input_tokens: el resto sin cachear, cobrado a precio completo.

console.log(res.usage.cache_creation_input_tokens) // primera llamada: alto; luego: 0
console.log(res.usage.cache_read_input_tokens)     // primera llamada: 0; luego: alto
console.log(res.usage.input_tokens)                // solo la cola sin cachear

El patrón que esperas entre dos llamadas con el mismo prefijo: la primera muestra un número grande en cache_creation y cero reads; de ahí en adelante todas muestran cero creation y un cache_read grande. Si cache_read_input_tokens se te queda en cero entre requests que crees idénticos, tienes un invalidador silencioso. Ve a la sección 05.

04 · Los números, para que sepas si vale la pena

La caché no es gratis, y un marcador en el lugar equivocado te cuesta dinero en vez de ahorrártelo. Las cuentas son lo bastante simples como para calcularlas de cabeza.

Un read de caché cuesta como 0.1x del precio base de input. Un write cuesta como 1.25x con el TTL por defecto de 5 minutos, o 2x con el TTL de 1 hora. Así que con el TTL por defecto, dos requests quedan a mano: el primero paga 1.25x por escribir, el segundo paga 0.1x por leer, total 1.35x, contra 2x de dos requests sin cachear. Del tercer request en adelante, todo es ganancia.

Cuándo rinde el TTL de 1 hora

El TTL de 1 hora mantiene viva la entrada durante los huecos del tráfico a ráfagas, pero el costo de write duplicado (2x) significa que necesitas al menos tres reusos para quedar a mano, en vez de dos. Úsalo cuando tu tráfico llega a ráfagas con huecos de inactividad mayores a cinco minutos: una cola de soporte que se calma de noche, un batch job que corre cada hora. Para tráfico continuo, donde los requests llegan cada pocos segundos, quédate con el por defecto. Cada request real mantiene la caché caliente por su cuenta y el premium del write de 1 hora se desperdicia.

Dónde importa esto en la práctica

El caso clásico es un contexto grande y fijo reusado en muchas llamadas: un set de documentos para RAG que consultas una y otra vez, una política o guía de estilo larga que prefija cada request, un bloque de definiciones de tools en un loop de agente. Piensa en un loop de deliberación que reusa el mismo prompt grande de encuadre a lo largo de decenas de turnos. Justo la forma donde un solo breakpoint sobre el prefijo estable convierte reads repetidos a precio completo en reads de 0.1x.

05 · Invalidadores silenciosos (la parte que de verdad muerde)

Todo lo de arriba es fácil. Aquí es donde se cae la caché de verdad. Un invalidador silencioso es cualquier cosa que cambie los bytes del prefijo entre requests que crees idénticos. Sin error, solo un hit rate en cero. Cuando cache_read_input_tokens se queda en cero, hazle grep a tu código de armado de prompts buscando esto:

1. Un timestamp en el prefijo. new Date(), Date.now(), un "fecha actual: …" interpolado en el system prompt: el prefijo cambia en cada request. Muévelo después del último breakpoint, a la cola del mensaje.
2. Un ID de request o UUID al principio del contenido. Mismo problema: cada request se vuelve único byte a byte. Los identificadores por request van al final del todo, si es que van.
3. Serialización JSON no determinista. Un JSON.stringify sobre un objeto cuyo orden de claves no es estable, o cualquier cosa armada a partir de un Set, produce bytes distintos en cada corrida. Serializa de forma determinista (ordena las claves).
4. Un valor por usuario en el system prompt. Interpolar un ID o nombre de usuario en el prefijo compartido le da a cada usuario un prefijo distinto y mata el reuso entre usuarios. Mete ese contexto más adelante, en messages.
5. Un set de tools que varía por request. Las tools se renderizan en la posición 0; armarlas condicionalmente (buildTools(user)) significa que nada cachea entre usuarios. Mantén la lista de tools fija y determinista, ordenada por nombre.

Dos detalles más que conviene saber en loops largos de agente. Cada breakpoint retrocede como máximo 20 bloques de contenido buscando una entrada de caché previa, así que un turno que agregue más de 20 bloques (común cuando hay muchos pares tool_use/tool_result) puede fallar en silencio. Mete un breakpoint intermedio cada 15 bloques más o menos. Y una entrada de caché solo se vuelve legible después de que la primera respuesta empieza a hacer streaming, así que N requests en paralelo con prefijos idénticos pagan todos precio completo. Lanza uno, espera su primer token, y de ahí dispara el resto.

La caché de prompts premia un armado de prompts aburrido y disciplinado: congela el frente, ordena lo que serializas, empuja todo lo que cambia hacia atrás, y confirma con usage en vez de dar por sentado. Hazlo y bajas latencia y costo en cada prompt grande repetido sin una sola sorpresa en la factura. Sáltate el paso de verificación y vas a desplegar un marcador que no hace nada, que es peor que no tener caché, porque vas a creer que el problema ya está resuelto.