A menudo se dice en ingeniería que "Cache Rules Everything Around Me", y la misma regla aplica para los agentes.
Los productos agentivos de larga duración como Claude Code son posibles gracias al prompt caching, que nos permite reutilizar el cómputo de rondas 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 ecosistema alrededor del prompt caching. Una alta tasa de aciertos de caché de prompt reduce costos y nos ayuda a crear límites de tarifa más generosos para nuestros planes de suscripción, por lo que monitoreamos nuestra tasa de aciertos de caché y declaramos SEVs si son demasiado bajas.
Estas son las lecciones (a menudo contraintuitivas) que hemos aprendido al optimizar el prompt caching a gran escala.
Organiza tu Prompt para el Caché
El prompt caching funciona mediante la coincidencia de prefijos: la API guarda 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 la mayor cantidad posible de tus solicitudes compartan un prefijo.
La mejor manera de hacerlo es contenido estático primero, contenido dinámico al final. Para Claude Code, esto se ve así:
- Prompt del sistema estático y herramientas (en caché global)
- Claude.MD (en caché dentro de un proyecto)
- Contexto de la sesión (en caché dentro de una sesión)
- Mensajes de la conversación
De esta forma 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 prompt del sistema estático, barajar las definiciones de las herramientas de manera no determinista, actualizar los parámetros de las herramientas (por ejemplo, qué agentes puede llamar AgentTool), etc.
Usa Mensajes para las Actualizaciones
Puede haber ocasiones en que la información que pones en tu prompt quede desactualizada, 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 la siguiente interacción. En Claude Code, agregamos una etiqueta <system-reminder> en el siguiente mensaje del usuario o resultado de la herramienta con la información actualizada para el modelo (por ejemplo, ahora es miércoles), lo que ayuda a preservar el caché.
No Cambies de Modelo a Mitad de una Sesión
Los cachés de prompt son exclusivos de cada modelo, y esto puede hacer que la matemática del prompt caching sea bastante contraintuitiva.
Si llevas 100k tokens en una conversación con Opus y quieres hacer una pregunta que es bastante fácil de responder, en realidad sería más costoso cambiar a Haiku que dejar que Opus responda, porque tendríamos que reconstruir el caché de prompt 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 Agregues o Elimines Herramientas a Mitad de una Sesión
Cambiar el conjunto de herramientas en medio de una conversación es una de las formas más comunes en que la gente rompe 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 almacenado en caché, agregar o eliminar una herramienta invalida el caché de toda la conversación.
Modo Plan — Diseña Alrededor del Caché
El modo Plan es un gran ejemplo de cómo diseñar funciones teniendo en cuenta las limitaciones del caché. El enfoque intuitivo sería: cuando el usuario entra al modo Plan, intercambiar el conjunto de herramientas para incluir solo herramientas de solo lectura. Pero eso rompería el 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 las 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 al modo Plan de forma autónoma cuando detecta un problema difícil, sin romper el 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 la conversación rompería el 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" mediante 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 almacenado en caché: los mismos stubs están siempre presentes en el mismo orden.
Afortunadamente, puedes usar la herramienta de búsqueda a través de nuestra API para simplificar esto.
Bifurcación de Contexto — Compactación
La compactación ocurre cuando te quedas sin espacio en la ventana de contexto. Resumimos la conversación hasta el momento 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 contraintuitivos.
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 prompt del sistema diferente y sin herramientas (que es la implementación simple), el prefijo almacenado 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 el Caché
Cuando ejecutamos la compactación, usamos exactamente el mismo prompt del sistema, contexto de usuario, contexto del sistema y definiciones de herramientas que la conversación principal. Anteponemos los mensajes de la conversación principal y 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 de la conversación principal — mismo prefijo, mismas herramientas, mismo historial — por lo que el prefijo almacenado en caché se reutiliza. Los únicos tokens nuevos son el propio prompt de compactación.
Esto significa, sin embargo, que necesitamos guardar un "búfer de compactación" para tener suficiente espacio en la ventana de contexto e incluir el mensaje compactado y los tokens de salida del resumen.
La compactación es complicada, pero afortunadamente no necesitas aprender estas lecciones por tu cuenta — basándonos en lo que aprendimos con Claude Code, incorporamos la compactación 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 bien, la mayor parte del almacenamiento en caché funciona solo.
- Usa mensajes en lugar de cambios en el prompt del sistema. Puede ser tentador editar el prompt del sistema para hacer cosas como entrar al modo Plan, cambiar la fecha, etc., pero en realidad es mejor insertar estos cambios en los mensajes durante la conversación.
- No cambies herramientas ni modelos a mitad de la conversación. Usa herramientas para modelar transiciones de estado (como el modo Plan) en lugar de cambiar el conjunto de herramientas. Diferencia la carga de herramientas en lugar de eliminarlas.
- Monitorea tu tasa de aciertos de caché como si monitorearas el tiempo de actividad. Alertamos sobre las rupturas 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 deben compartir el prefijo de la conversación principal. Si necesitas ejecutar un cómputo secundario (compactación, resumen, ejecución de habilidades), usa parámetros idénticos y seguros para el caché para obtener aciertos de caché en el prefijo de la conversación principal.
Claude Code se construyó alrededor del prompt caching desde el primer día; deberías hacer lo mismo si estás construyendo un agente.
