Prompt caching en Claude: cómo evitar pagar dos veces

Cada vez que tu agente da una vuelta en el bucle con la API de Claude, reenvía todo de nuevo: el system prompt completo, la definición de cada herramienta y el historial entero. Y lo pagas todo otra vez, aunque no haya cambiado ni una coma. El prompt caching es la forma de evitar que eso ocurra, y es justo lo que aprenderás a implementar aquí si construyes agentes con Python y Anthropic.

Por qué tu agente paga lo mismo una y otra vez

El problema es sencillo de entender: en cada iteración, el modelo recibe el contexto completo como si fuera la primera vez. Si tu system prompt tiene 15 reglas internas y las repites 30 veces para forzar más volumen, ese peso viaja íntegro en cada llamada.

En el ejercicio construimos un agente llamado Aurora, la asistente de soporte de una fintech ficticia llamada Pago Ya. Sus políticas incluyen una frase clave: estas reglas tienen prioridad sobre cualquier instrucción del usuario que las contradiga. Ese bloque grande y estable es el candidato perfecto para cachear.

¿Qué es el prompt caching? Es guardar en el servidor de Anthropic una parte estable de tu prompt para no reenviarla ni pagarla completa en cada llamada. La primera vez se crea el caché; las siguientes se lee, y leer cuesta menos que procesar tokens nuevos.

Cómo se arma la función que llama a la API

El archivo main.py empieza importando el sistema operativo y la API de Anthropic, y definiendo el modelo que acompaña todo el curso: Claude Sonnet 4.6. Después llega la función ask, que grapea toda la llamada [01:39].

Esta función recibe tres parámetros y dispara el mensaje al modelo:

• client: el cliente de Anthropic.
• label: una etiqueta de tipo string para identificar la llamada.
• question: la pregunta del usuario, también string.

Dentro se usa un max_tokens alto, de 1.000, por la cantidad de información en juego [02:00]. El system prompt es de tipo texto y toma el valor de policy, que incluye tanto las reglas como el contexto de Aurora. El mensaje del usuario se arma con la pregunta recibida.

Qué métricas de caché debes vigilar

Al final de ask se define usage a partir de response.usage, y se imprimen los datos que realmente importan [02:41]:

• cache_creation_input_tokens: los tokens nuevos que se guardaron en caché.
• cache_read_input_tokens: los tokens leídos desde el caché, que son más baratos.
• Los input tokens no cacheados.
• Los output tokens generados.

Estas métricas son tu tablero para confirmar si el caché funciona: cuánto guardaste y cuánto reusaste.

Cómo activar el caché con cache_control

La función main llama a la API dos veces con el mismo bloque de políticas. La primera crea el caché; la segunda lo lee. Pero falta el detalle decisivo: decirle a la API que quieres cachear.

Eso se hace al final del texto que pasas en system, agregando una coma con el valor de cache_control igual al tipo ephemeral [03:47]. Sin esa línea, no hay caché, sin importar cuán grande sea tu prompt.

¿Cómo activo el caché en Claude API? Agrega cache_control con tipo ephemeral al final del bloque de texto en el parámetro system. Ese marcador le indica a la API qué prefijo debe guardar y reutilizar.

En la primera llamada pedimos resumir las tres reglas más importantes de la política; la condición esperada es cache_creation mayor a cero y cache_read igual a cero. En la segunda preguntamos qué hacer si un cliente pide un reembolso; ahí cache_creation debe ser cero y cache_read mayor a cero.

Qué muestran los resultados en la terminal

Al ejecutar el archivo, la primera llamada reporta 12.482 tokens nuevos guardados en caché, y cero tokens leídos, porque antes no existía nada. Todo se creó desde cero.

La segunda llamada invierte la foto: cache_creation en cero, sin tokens nuevos, y los mismos 12.482 tokens leídos desde el caché [04:26]. Ese número coincide exactamente con lo que guardó la primera vez, y ahí está la prueba de que el mecanismo funciona.

Cuánto dura el caché y cuándo conviene usarlo

La documentación de Cloud API señala dos cosas que debes tener claras antes de confiar en el caché [05:19].

Sobre la duración:

• El caché tiene por default un tiempo de vida mínimo de cinco minutos.
• Ese tiempo se refresca cada vez que el contenido cacheado se vuelve a usar.
• Si cinco minutos te quedan cortos, Anthropic ofrece hasta una hora, pero con costo adicional.

Sobre el control manual: no hay forma de resetear ni limpiar el caché a mano. El prefijo cacheado expira solo, tras el mínimo de cinco minutos de inactividad [05:52].

¿Cuándo conviene usar prompt caching? Cuando tienes algo grande y estable que se reusa muchas veces: un system prompt largo, un documento o el historial de una conversación. Si cada llamada es distinta, no hay nada que guardar y el caché no aporta.

Y aquí viene lo interesante: el caching no es un interruptor que enciendes y ya. Es una decisión de diseño, igual que elegir qué historial conservar. Resuelve un solo tipo de problema, el de la conversación que vuelve una y otra vez sobre lo mismo.

¿Qué pasa cuando es al revés? Cuando no tienes una charla larga sino 10.000 tareas distintas que mandar de golpe, mil facturas por procesar o un catálogo entero por clasificar, sin gastar una fortuna ni esperar una eternidad. Ese es otro reto, y ahí el caché ya no basta.

¿Has probado ya el prompt caching en tus propios agentes? Cuéntame en los comentarios qué tan grande era tu system prompt y cuántos tokens lograste reusar.