A menudo se dice en ingeniería que "Cache Rules Everything Around Me", y la misma regla se aplica a los agentes.
Los productos agentivos de larga ejecución como Claude Code se hacen viables gracias al prompt caching, que nos permite reutilizar la computación de viajes de ida y vuelta anteriores y reducir significativamente la latencia y el costo.
¿Qué es el prompt caching, cómo funciona y cómo se implementa técnicamente? Lee más en el artículo de @RLanceMartin sobre prompt caching y nuestro nuevo lanzamiento de auto-caching.
En Claude Code, construimos todo nuestro andamiaje en torno al prompt caching. Una alta tasa de aciertos de caché de indicaciones reduce costos y nos ayuda a crear límites de tasa más generosos para nuestros planes de suscripción, por lo que ejecutamos alertas sobre nuestra tasa de aciertos y declaramos SEVs si son demasiado bajas.
Estas son las lecciones (a menudo poco intuitivas) que hemos aprendido al optimizar el prompt caching a escala.
Organiza tu Prompt para el Caching
El prompt caching funciona mediante la coincidencia de prefijos: la API almacena en caché todo desde el inicio de la solicitud hasta cada punto de interrupción de cache_control. Esto significa que el orden en que colocas las cosas importa enormemente; quieres que tantas de tus solicitudes como sea posible compartan un prefijo.
La mejor manera de hacerlo es contenido estático primero, contenido dinámico al final. Para Claude Code, se ve así:
- Static system prompt y herramientas (almacenado en caché globalmente)
- Claude.MD (almacenado en caché dentro de un proyecto)
- Contexto de sesión (almacenado en caché dentro de una sesión)
- Mensajes de conversación
De esta manera maximizamos cuántas sesiones comparten aciertos de caché.
¡Pero esto puede ser sorprendentemente frágil! Ejemplos de razones por las que hemos roto este orden antes incluyen: poner una marca de tiempo detallada en el static system prompt, mezclar las definiciones de orden de herramientas de manera no determinista, actualizar parámetros de herramientas (por ejemplo, qué agentes puede llamar AgentTool), etc.
Usa Mensajes para Actualizaciones
Puede haber ocasiones en que la información que pones en tu prompt se vuelva obsoleta, por ejemplo, si tienes la hora o si el usuario cambia un archivo. Puede ser tentador actualizar el prompt, pero eso resultaría en un fallo de caché y podría terminar siendo bastante costoso para el usuario.
Considera si puedes pasar esta información a través de mensajes en el siguiente turno. En Claude Code, agregamos una etiqueta <system-reminder> en el siguiente mensaje del usuario o resultado de herramienta con la información actualizada para el modelo (por ejemplo, ahora es miércoles), lo que ayuda a preservar la caché.
No Cambies de Modelo a Mitad de Sesión
Los cachés de indicaciones son únicos para cada modelo y esto puede hacer que las cuentas del prompt caching sean bastante poco intuitivas. Si estás a 100k tokens en una conversación con Opus y quieres hacer una pregunta bastante fácil de responder, en realidad sería más costoso cambiar a Haiku que dejar que Opus responda, porque necesitaríamos reconstruir el prompt cache para Haiku.
Si necesitas cambiar de modelo, la mejor manera de hacerlo es con subagentes, donde Opus prepararía un mensaje de "traspaso" a otro modelo sobre la tarea que necesita realizar. Hacemos esto a menudo con los agentes Explore en Claude Code que usan Haiku.
Nunca Añadas o Elimines Herramientas a Mitad de Sesión
Cambiar el conjunto de herramientas en medio de una conversación es una de las formas más comunes en que las personas rompen el prompt caching. Parece intuitivo: solo debes darle al modelo las herramientas que crees que necesita en ese momento. Pero debido a que las herramientas son parte del prefijo en caché, agregar o eliminar una herramienta invalida la caché para toda la conversación.
Modo Plan — Diseña en Torno a la Caché
El modo plan es un gran ejemplo de diseño de características en torno a las limitaciones de caché. El enfoque intuitivo sería: cuando el usuario entra en modo plan, intercambiar el conjunto de herramientas para incluir solo herramientas de solo lectura. Pero eso rompería la caché.
En su lugar, mantenemos todas las herramientas en la solicitud en todo momento y usamos EnterPlanMode y ExitPlanMode como herramientas en sí mismas. Cuando el usuario activa el modo plan, el agente recibe un mensaje del sistema que explica que está en modo plan y cuáles son las instrucciones: explora el código base, no edites archivos, llama a ExitPlanMode cuando el plan esté completo. Las definiciones de herramientas nunca cambian.
Esto tiene un beneficio adicional: debido a que EnterPlanMode es una herramienta que el modelo puede llamar por sí mismo, puede entrar en modo plan de forma autónoma cuando detecta un problema difícil, sin romper la caché.
Búsqueda de Herramientas — Diferir en Lugar de Eliminar
El mismo principio se aplica a nuestra función de búsqueda de herramientas. Claude Code puede tener docenas de herramientas MCP cargadas, e incluirlas todas en cada solicitud sería costoso. Pero eliminarlas a mitad de conversación rompería la caché.
Nuestra solución: defer_loading. En lugar de eliminar herramientas, enviamos stubs ligeros — solo el nombre de la herramienta, con defer_loading: true — que el modelo puede "descubrir" a través de una herramienta ToolSearch cuando sea necesario. Los esquemas completos de las herramientas solo se cargan cuando el modelo las selecciona. Esto mantiene estable el prefijo en caché: los mismos stubs están siempre presentes en el mismo orden.
Afortunadamente, puedes usar la herramienta de búsqueda de herramientas a través de nuestra API para simplificar esto.
Bifurcación de Contexto — Compaction
La compactación (compaction) es lo que sucede cuando te quedas sin la ventana de contexto. Resumimos la conversación hasta ahora y continuamos una nueva sesión con ese resumen.
Sorprendentemente, la compactación tiene muchos casos límite con el prompt caching que pueden ser poco intuitivos.
En particular, cuando compactamos necesitamos enviar toda la conversación al modelo para generar un resumen. Si esta es una llamada API separada con un system prompt diferente y sin herramientas (que es la implementación simple), el prefijo en caché de la conversación principal no coincide en absoluto. Pagas el precio completo por todos esos tokens de entrada, aumentando drásticamente el costo para el usuario.
La Solución — Bifurcación Segura para la Caché
Cuando ejecutamos la compactación, usamos el exactamente mismo system prompt, contexto de usuario, contexto del sistema y definiciones de herramientas que la conversación padre. Anteponemos los mensajes de conversación del padre, luego añadimos el prompt de compactación como un nuevo mensaje de usuario al final.
Desde la perspectiva de la API, esta solicitud se ve casi idéntica a la última solicitud del padre — mismo prefijo, mismas herramientas, mismo historial — por lo que el prefijo en caché se reutiliza. Los únicos tokens nuevos son el propio prompt de compactación.
Sin embargo, esto significa que necesitamos guardar un "buffer de compactación" para tener suficiente espacio en la ventana de contexto para incluir el mensaje compactado y los tokens de salida del resumen.
La compactación es complicada, pero afortunadamente no necesitas aprender estas lecciones tú mismo: basándonos en lo que aprendimos de Claude Code, incorporamos compaction directamente en la API, para que puedas aplicar estos patrones en tus propias aplicaciones.
Lecciones Aprendidas
- El prompt caching es una coincidencia de prefijos. Cualquier cambio en cualquier parte del prefijo invalida todo lo que sigue. Diseña todo tu sistema en torno a esta restricción. Si ordenas correctamente, la mayor parte del caching funciona sin esfuerzo.
- Usa mensajes en lugar de cambios en el system prompt. Puede que te sientas tentado a editar el system prompt para hacer cosas como entrar en modo plan, cambiar la fecha, etc., pero en realidad sería mejor insertarlos en los mensajes durante la conversación.
- No cambies herramientas o modelos a mitad de conversación. Usa herramientas para modelar transiciones de estado (como el modo plan) en lugar de cambiar el conjunto de herramientas. Diferir la carga de herramientas en lugar de eliminarlas.
- Monitorea tu tasa de aciertos de caché como monitoreas el tiempo de actividad. Alertamos sobre roturas de caché y las tratamos como incidentes. Unos pocos puntos porcentuales de tasa de fallos de caché pueden afectar drásticamente el costo y la latencia.
- Las operaciones de bifurcación necesitan compartir el prefijo del padre. Si necesitas ejecutar una computación secundaria (compaction, resumen, ejecución de habilidades), usa parámetros idénticos y seguros para la caché para obtener aciertos de caché en el prefijo del padre.
Claude Code se construyó en torno al prompt caching desde el primer día; deberías hacer lo mismo si estás construyendo un agente.
