Colocación de puntos de interrupción de cache_control en prompts del sistema y herramientas

Un punto de interrupción de cache_control solo almacena en caché lo que viene antes de él, en el orden exacto en que Claude ensambla la solicitud: primero las herramientas, luego el prompt del sistema y finalmente el array de mensajes.

Si se equivoca en ese orden, los puntos de interrupción almacenarán en caché muy poco para ser útiles, o se invalidarán por contenido que nunca debió estar en el prefijo almacenado en caché.

Esta página explica dónde colocar los puntos de interrupción, por qué el orden importa y cómo superponer más de uno para un almacenamiento en caché más granular.

Resumen

Cada solicitud a la API de Claude tiene tres secciones lógicas que participan en el prefijo almacenado en caché, siempre en el mismo orden: tools (herramientas), luego system (sistema), luego messages (mensajes).

Un punto de interrupción marca el final del contenido que desea almacenar en caché, por lo que un punto de interrupción en la última herramienta almacena en caché solo las herramientas, mientras que un punto de interrupción en el prompt del sistema almacena en caché las herramientas más el sistema juntos.

El contenido colocado después del último punto de interrupción, casi siempre la cola de messages, nunca se almacena en caché y se reprocesa en cada llamada.

Hacer esto bien significa colocar su contenido más estable primero y su contenido más volátil al final, y luego colocar los puntos de interrupción en las uniones naturales entre ellos.

Esta página muestra la estructura de la solicitud, las reglas de ordenación y ejemplos prácticos con un punto de interrupción y con dos puntos de interrupción superpuestos.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=500,
    tools=[
        {
            "name": "search_docs",
            "description": "Busca en la base de conocimiento interna un tema.",
            "input_schema": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
            "cache_control": {"type": "ephemeral"},
        }
    ],
    system=[
        {
            "type": "text",
            "text": "Eres el asistente de soporte de Acme Corp. Sigue la guía de tono a continuación.\n" + ("...texto de la guía de tono..." * 100),
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "¿Cuál es tu plazo de reembolso?"}],
)

Cuándo usar esto:

• Su solicitud incluye un prompt del sistema o un catálogo de herramientas que permanece igual en muchas llamadas.
• Desea almacenar en caché las herramientas y el sistema de forma independiente, porque uno cambia con más frecuencia que el otro.
• Está viendo cache_read_input_tokens inesperadamente bajos y sospecha de la colocación del punto de interrupción, no de la deriva del contenido.
• Está combinando el uso de herramientas con un conjunto largo de instrucciones y desea controlar exactamente qué es elegible para el almacenamiento en caché.

Ejemplo Práctico

import anthropic
 
client = anthropic.Anthropic()
 
REFERENCE_DOCS = "Detalles del catálogo de productos y política de devoluciones...\n" * 400
TOOL_DESCRIPTION = "Busca el pedido de un cliente por ID de pedido." * 15
 
def build_request(user_question: str) -> dict:
    """Construye una solicitud con dos puntos de interrupción de caché independientes:
    uno después del catálogo de herramientas, otro después del prompt del sistema.
    """
    return {
        "model": "claude-sonnet-5",
        "max_tokens": 500,
        "tools": [
            {
                "name": "lookup_order",
                "description": TOOL_DESCRIPTION,
                "input_schema": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string"}},
                    "required": ["order_id"],
                },
                # Punto de interrupción 1: almacena en caché solo el catálogo de herramientas.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        "system": [
            {
                "type": "text",
                "text": (
                    "Eres el asistente de soporte de Acme Corp.\n"
                    "Material de referencia:\n" + REFERENCE_DOCS
                ),
                # Punto de interrupción 2: almacena en caché herramientas + sistema juntos.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        # Todo aquí es por solicitud y nunca se almacena en caché.
        "messages": [{"role": "user", "content": user_question}],
    }
 
client = anthropic.Anthropic()
 
r1 = client.messages.create(**build_request("¿Cuál es tu plazo de reembolso?"))
print("llamada 1:", r1.usage.cache_creation_input_tokens, r1.usage.cache_read_input_tokens)
 
r2 = client.messages.create(**build_request("¿Puedo rastrear el pedido n.º 4471?"))
print("llamada 2:", r2.usage.cache_creation_input_tokens, r2.usage.cache_read_input_tokens)

Lo que esto demuestra:

• Dos puntos de interrupción en una sola solicitud: uno justo después de la lista de herramientas, otro justo después del prompt del sistema.
• tools, system y messages son construidos por una sola función para que el contenido almacenado en caché esté garantizado como idéntico byte a byte entre llamadas.
• Solo la pregunta final del usuario cambia entre r1 y r2, y se encuentra correctamente después de ambos puntos de interrupción, en messages.
• La segunda llamada muestra cache_read_input_tokens distinto de cero porque el prefijo de herramientas + sistema coincidió exactamente.

Análisis Profundo

Cómo Funciona

• Claude ensambla el prefijo efectivo en un orden fijo: tools, luego system, luego messages, independientemente del orden en que aparezcan los argumentos de palabra clave en su llamada de Python.
• Un bloque cache_control colocado en el último elemento de tools almacena en caché todo en tools hasta e incluyendo ese elemento.
• Un bloque cache_control colocado en un bloque de contenido de system almacena en caché tools (si se marcó) más system hasta ese punto, como un solo segmento combinado.
• Puede marcar más de un punto de interrupción en una sola solicitud; cada uno cierra un segmento, lo que le permite obtener crédito de caché parcial incluso cuando solo cambió el segmento posterior.
• Cualquier cosa después del último punto de interrupción, casi siempre la cola de messages, se reprocesa cada vez y nunca contribuye a cache_read_input_tokens.

Dónde Suelen Ir los Puntos de Interrupción

Notas de Python

# system puede ser una cadena simple O una lista de bloques de contenido.
# cache_control solo se puede establecer cuando system es la forma de LISTA.
 
# NO almacenará en caché - system es una cadena desnuda, no es posible cache_control:
system = "Eres un asistente útil."
 
# SÍ almacenará en caché - system es una lista de un bloque de contenido que lleva cache_control:
system = [
    {"type": "text", "text": "Eres un asistente útil.", "cache_control": {"type": "ephemeral"}}
]

Parámetros y Valores de Retorno

Trampas

• Colocar cache_control en una cadena desnuda system. Una cadena simple system="..." no tiene dónde adjuntar cache_control. Solución: use siempre la forma de lista-de-bloques-de-contenido de system cuando desee almacenamiento en caché.
• Asumir que el orden de los argumentos en Python controla el orden almacenado en caché. Escribir messages= antes de tools= en su llamada de función no tiene ningún efecto en el orden lógico de la solicitud. Solución: recuerde que Claude siempre evalúa tools -> system -> messages, independientemente del orden de las palabras clave en su código.
• Colocar texto específico del usuario dentro del bloque del sistema almacenado en caché. Interpolar un nombre de usuario o un ID de sesión en el texto del prompt del sistema antes del punto de interrupción invalida la caché en cada solicitud individual. Solución: mantenga el bloque del sistema estático; coloque cualquier cosa por usuario o por sesión en messages, después del punto de interrupción.
• Marcar cada herramienta individualmente en lugar de solo la última. cache_control solo necesita ir en la última herramienta de la lista; almacena en caché todo desde el inicio de tools hasta esa entrada. Solución: marque un punto de interrupción por segmento que desee, no uno por elemento.
• Reconstruir el diccionario del esquema de herramientas desde cero en cada llamada. Incluso los diccionarios de Python semánticamente idénticos pueden serializarse de manera diferente si el orden de inserción de las claves varía. Solución: construya el contenido de las herramientas y el sistema a partir de una única constante o función compartida, no de literales en línea dispersos por la base de código.
• Olvidar que un esquema de herramienta modificado también invalida un punto de interrupción del sistema posterior. Debido a que las herramientas vienen antes del sistema en el prefijo, un cambio en el esquema de la herramienta rompe la caché a nivel del sistema, incluso si el texto del sistema en sí nunca cambió. Solución: trate los cambios en el esquema de herramientas como eventos que afectan la caché, no solo como cambios en el texto del prompt.

Alternativas

Preguntas Frecuentes

Relacionado

• Cómo Funciona Realmente la Coincidencia de Prefijos del Almacenamiento en Caché de Prompts - el mecanismo subyacente de coincidencia exacta en el que se basa este orden.
• Conceptos Básicos del Almacenamiento en Caché de Prompts - un primer punto de interrupción de cache_control de principio a fin.
• Depuración de Invalidadores Silenciosos de Caché en Prompts Largos - encuentra qué está rompiendo un punto de interrupción que ya has colocado.
• Definición de Esquemas de Herramientas con name, description e input_schema - cómo se estructuran los esquemas de herramientas antes de almacenarlos en caché.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.