Cada paso de un agente con herramientas suele reenviar las mismas definiciones de tools, el mismo system prompt y el historial que ya existía. Sin caché de prefijo, el proveedor procesa ese bloque como input nuevo. Con caché, reutiliza el tramo idéntico y cobra (y procesa) sobre todo lo que cambió: el tool result, el turno del asistente y la siguiente pregunta.
Prompt caching es la reutilización de un prefijo idéntico entre solicitudes de la API. En un bucle de agentes, no es solo un detalle de facturación. Es un contrato de layout: lo que se mantiene igual va al principio; lo que cambia en cada paso va al final; y el harness registra si el hit ocurrió de verdad.
Si todavía estás recortando tokens del harness, empieza por el coste invisible del contexto en agentes de código. El presupuesto decide qué entra. El caching decide cuántas veces vuelves a pagar ese bloque estable en cada tool step.
Resultado práctico
- Prefijo estable: tools + system + ejemplos fijos al inicio.
- Cola dinámica: tool results, timestamps y la petición actual al final.
- Medición: registrar tokens leídos y escritos en caché en cada paso.
- Fallo habitual: timestamp, lista de tools reordenada o system mutable en el prefijo.
¿Qué reutiliza el prompt caching en el bucle del agente?
En los proveedores actuales, la caché opera sobre un prefijo exacto. OpenAI describe el comportamiento como coincidencia de prefijo idéntico al inicio del prompt, con caching automático para prompts elegibles a partir de unos 1.024 tokens, y con tools, mensajes y structured outputs pudiendo formar parte de ese prefijo (OpenAI, "Prompt caching", consultado el 06/08/2026).
Anthropic documenta la misma idea con un orden fijo de construcción del prefijo: tools, luego system, luego messages, hasta el bloque marcado con cache_control. La documentación incluye el uso agentic con varias tool calls como escenario en el que la caché reduce coste y latencia, porque cada paso suele ser una nueva llamada a la API (Anthropic, "Prompt caching", consultado el 06/08/2026).
En términos de sistema, el bucle típico es:
- Enviar tools + system + tarea.
- Recibir
tool_use. - Ejecutar la herramienta en tu runtime.
- Reenviar el historial con el
tool_result. - Repetir hasta la respuesta final o el límite de pasos.
El paso 4 es donde la caché importa. Si tools y system son idénticos byte a byte al paso anterior, el prefijo puede leerse de la caché. Si cambia cualquier parte estable, el hit desaparece y vuelves a pagar el prefijo completo.
Esto complementa el context engineering para agentes de código: allí reduces lo que entra; aquí reutilizas lo que debe permanecer.
¿Cómo estructurar tools, system e historial para acertar el hit?
Trata el prompt como dos zonas.
Zona estable (prefijo): nombres y schemas de herramientas, system prompt, políticas, ejemplos fijos, documentos de referencia que no cambian en cada paso. Colócala al inicio y evita interpolar fecha, id de request, contador de turnos o JSON con orden aleatorio de claves.
Zona dinámica (cola): el mensaje del usuario, los tool_results, el estado de la tarea y cualquier telemetría que cambie. Déjala al final.
La documentación de OpenAI recomienda contenido estático al principio y contenido variable al final, y observa que tools e imágenes también deben ser idénticas entre solicitudes para que el prefijo coincida (OpenAI, "Prompt caching", consultado el 06/08/2026). Anthropic refuerza el mismo layout y advierte que cambiar definiciones de tools invalida la caché de tools, system y messages (Anthropic, "Prompt caching", consultado el 06/08/2026).
// Ilustrativo: layout de prefijo estable + cola dinámica.
// No es un cliente de producción completo.
type ToolDef = {
name: string;
description: string;
input_schema: Record<string, unknown>;
};
type Message =
| { role: "user" | "assistant"; content: string }
| {
role: "user";
content: Array<{
type: "tool_result";
tool_use_id: string;
content: string;
}>;
};
const STABLE_TOOLS: ToolDef[] = [
{
name: "search_orders",
description: "Busca pedidos por customerId.",
input_schema: {
type: "object",
properties: {
customerId: { type: "string" },
},
required: ["customerId"],
},
},
];
const STABLE_SYSTEM = [
"Eres un agente de soporte con herramientas.",
"Llama como máximo a una herramienta por paso.",
"No inventes un customerId.",
].join("\n");
function buildRequest(history: Message[]) {
return {
model: "claude-sonnet-4-5",
max_tokens: 1024,
// Anthropic: marca el final del bloque reutilizable.
system: [
{
type: "text",
text: STABLE_SYSTEM,
cache_control: { type: "ephemeral" },
},
],
tools: STABLE_TOOLS,
messages: history,
};
}Dos detalles de implementación importan más que el nombre del modelo:
- Serialización estable. En algunos lenguajes, el orden de las claves en el JSON de tools cambia entre procesos. Anthropic enumera el orden inestable de claves en
tool_usecomo causa de miss (Anthropic, "Prompt caching", consultado el 06/08/2026). - Superficie de tools fija durante el bucle. Si el harness añade o quita tools a mitad de la tarea, el prefijo cambia y cae la caché de tools. Prefiere un conjunto fijo por tipo de tarea y deja la elección de herramienta al modelo, con validación de tool calls en runtime.
Cuando orquesto bucles largos en Claude Code, Codex o un harness propio, uso RemoteCode como mi capa para empujar el trabajo con menos desperdicio de contexto. Es la herramienta del autor de este blog: no sustituye el layout del prefijo, la medición de cache hits ni la revisión humana.
¿Cómo medir el cache hit en cada tool step?
Sin métrica, "activamos caching" es fe. Los dos proveedores exponen contadores en el objeto de uso de la respuesta.
En Anthropic, el recorte útil es:
cache_read_input_tokens: tokens leídos de la cachécache_creation_input_tokens: tokens escritos en la caché en esta respuestainput_tokens: tokens después del último breakpoint (la cola no elegible)
La documentación define el total de input como la suma de esos tres campos (Anthropic, "Prompt caching", consultado el 06/08/2026).
En OpenAI, el campo equivalente en el detalle de input es cached_tokens. En familias más nuevas, la documentación también describe cache_write_tokens y el parámetro prompt_cache_key para mejorar el enrutado de solicitudes que comparten el mismo prefijo (OpenAI, "Prompt caching", consultado el 06/08/2026).
// Ilustrativo: registrar hit ratio por paso del bucle.
type UsageLike = {
input_tokens?: number;
cache_read_input_tokens?: number;
cache_creation_input_tokens?: number;
prompt_tokens_details?: {
cached_tokens?: number;
cache_write_tokens?: number;
};
};
function summarizeCache(step: number, usage: UsageLike) {
const read =
usage.cache_read_input_tokens ??
usage.prompt_tokens_details?.cached_tokens ??
0;
const written =
usage.cache_creation_input_tokens ??
usage.prompt_tokens_details?.cache_write_tokens ??
0;
const uncached = usage.input_tokens ?? 0;
return {
step,
read,
written,
uncached,
// Hit de prefijo: hubo lectura de caché en este paso.
hit: read > 0,
};
}Guarda esos números junto al nombre de la tool, la latencia y el coste. La observabilidad de agentes de código es el lugar natural para ese evento: sin él, un miss de caché solo parece "la API se puso cara".
Los precios cambian por modelo y por política de retención. A 06/08/2026, la tabla de Anthropic muestra lecturas de caché a 0,1× el precio de input base y escrituras de caché de 5 minutos a 1,25× el input base, con opción de TTL de 1 hora a mayor coste de escritura (Anthropic, "Prompt caching"). Usa la tabla actual del proveedor al proyectar ahorro; no fijas un porcentaje en el código.
¿Qué invalida la caché a mitad del bucle?
Los misses más caros en agentes suelen ser autoinfligidos.
1. Timestamp o id en el system. Un Ahora: 2026-08-06T12:01:03Z al inicio del system reescribe el prefijo cada segundo. Mueve reloj e id de request a la cola, u omítelos si el agente no los necesita.
2. Tools regeneradas en cada paso. Generar el array de tools desde un Map sin orden, o inyectar datos de sesión en las descripciones, rompe el match. Materializa la lista una vez por tipo de tarea.
3. System prompt montado con estado de la tarea. Cliente actual: ACME en el system parece cómodo y destruye el reuso entre tenants y entre pasos. Prefiere un mensaje de usuario o un bloque después del breakpoint.
4. TTL agotado. La caché efímera de Anthropic tiene una vida útil por defecto de 5 minutos, renovada en cada hit; existe un TTL de 1 hora con escritura más cara (Anthropic, "Prompt caching", consultado el 06/08/2026). Si el agente espera 20 minutos una aprobación humana y dependes del TTL de 5 minutos, el siguiente paso reescribe el prefijo.
5. Esperar que la caché cambie la respuesta. Ambos proveedores afirman que el caching no altera la generación de tokens de salida; reutiliza el procesamiento del prefijo (OpenAI, "Prompt caching"; Anthropic, "Prompt caching", consultados el 06/08/2026). Si la salida cambió, la causa está en sampling, tools, historial o modelo, no en "la caché alucinó".
Checklist de verificación en el harness
Usa esta secuencia antes de dar por cerrado el trabajo:
- Ejecuta dos pasos consecutivos del mismo agente con el mismo conjunto de tools.
- En el segundo paso, confirma
cache_read_input_tokensocached_tokens> 0. - Introduce a propósito un timestamp en el system y confirma el miss.
- Quita el timestamp y confirma que el hit vuelve.
- Mantén el conjunto de tools estable durante el bucle; valida argumentos en el borde.
- Registra read/write/uncached por step en un artefacto de CI o log estructurado.
- Si el volumen es multi-tenant en OpenAI, usa un
prompt_cache_keyestable por prefijo compartido, según la documentación actual.
Límites de este artículo
El texto no promete un porcentaje fijo de ahorro: eso depende del tamaño del prefijo, del número de pasos, del TTL, del modelo y de la tasa de invalidación. Tampoco sustituye la reducción de contexto. Un prefijo de 40 mil tokens con 90% de hit sigue siendo un prefijo grande; el presupuesto sigue siendo necesario.
No cubre almacenamiento semántico de respuestas (caché de salida por similitud). El prompt caching es reutilización de prefijo en el proveedor, no un Redis de respuestas. No cubre la política de retención de datos de tu organización: lee la guía de datos del proveedor cuando importen ZDR o residencia.
Por último, el ejemplo TypeScript es ilustrativo. Los nombres de modelos y los campos de usage cambian; trata la documentación oficial como fuente de verdad en la fecha del deploy.
Preguntas frecuentes sobre prompt caching en agentes
¿El prompt caching cambia la respuesta del modelo?
No. OpenAI y Anthropic describen la función como reutilización del procesamiento del prefijo. La generación de tokens de salida sigue siendo una computación nueva a partir de ese prefijo. No uses la caché como si fuera memorización de la respuesta final.
¿Necesito marcar cache_control en todo proveedor?
No. OpenAI documenta caching automático para requests elegibles y, en familias más nuevas, breakpoints explícitos y prompt_cache_key. Anthropic ofrece caching automático en el nivel superior de la request y breakpoints explícitos por bloque. El layout estable importa en ambos; la API de marcado cambia.
¿Cuál es el tamaño mínimo del prefijo?
Depende del modelo y de la plataforma. OpenAI indica unos 1.024 tokens como referencia para prefijos cacheables. Anthropic publica mínimos por modelo (por ejemplo 1.024 tokens en varios Sonnet/Opus recientes, con otros mínimos mayores en modelos específicos). Si read y creation llegan a cero, el prefijo probablemente quedó por debajo del mínimo o el breakpoint está en el bloque equivocado.
¿Compensa cachear un agente de un solo paso?
Solo si el mismo prefijo se repite entre usuarios o entre jobs cercanos en el tiempo. En un bucle con varias tool calls, el beneficio suele aparecer a partir del segundo paso. En un one-shot con system corto, la ganancia puede ser cero y la escritura de caché aún cuesta en los planes que cobran write.
