Uso de herramientas con almacenamiento en caché de prompts

Esta página cubre el almacenamiento en caché de prompts para definiciones de herramientas: dónde colocar los puntos de interrupción de cache_control, cómo defer_loading preserva tu caché y qué la invalida. Para información general sobre el almacenamiento en caché de prompts, consulta Almacenamiento en caché de prompts.



cache_control en definiciones de herramientas

Coloca cache_control: {"type": "ephemeral"} en la última herramienta de tu arreglo tools. Esto almacena en caché todo el prefijo de definiciones de herramientas, desde la primera herramienta hasta el punto de interrupción marcado:

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": {
          "timezone": { "type": "string" }
        },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

Para mcp_toolset, el punto de interrupción de cache_control se ubica en la última herramienta del conjunto. No controlas el orden de las herramientas dentro de un conjunto de herramientas MCP, así que coloca el punto de interrupción en la entrada mcp_toolset misma y la API lo aplica a la última herramienta expandida.



defer_loading y preservación de la caché

Las herramientas diferidas no se incluyen en el prefijo de la indicación del sistema. Cuando el modelo descubre una herramienta diferida a través de la búsqueda de herramientas, la definición se agrega en línea como un bloque tool_reference en el historial de la conversación. El prefijo permanece intacto, por lo que el almacenamiento en caché de prompts se preserva.

Esto significa que agregar herramientas dinámicamente a través de la búsqueda de herramientas no rompe tu caché. Puedes iniciar una conversación con un conjunto pequeño de herramientas siempre cargadas (almacenadas en caché), dejar que el modelo descubra herramientas adicionales según sea necesario y mantener el mismo acierto de caché en cada turno.

defer_loading también actúa de forma independiente de la construcción de la gramática para el modo estricto. La gramática se construye a partir del conjunto completo de herramientas sin importar cuáles estén diferidas, por lo que tanto el almacenamiento en caché de prompts como el almacenamiento en caché de la gramática se preservan cuando las herramientas se cargan dinámicamente.



Qué invalida tu caché

La caché sigue una jerarquía de prefijos (tools → system → messages), por lo que un cambio en un nivel invalida ese nivel y todo lo que viene después:



Los resultados de herramientas del servidor se almacenan en caché automáticamente

Cuando tu solicitud tiene habilitado el almacenamiento en caché de prompts y Claude usa una herramienta del servidor como búsqueda web, obtención web o ejecución de código, la API coloca automáticamente un punto de interrupción de caché en el resultado de la herramienta del servidor antes de ejecutar la siguiente iteración del bucle agéntico. Esto permite que las iteraciones posteriores dentro de la misma solicitud lean el prefijo creciente desde la caché en lugar de reprocesarlo.

Este punto de interrupción automático siempre usa el TTL predeterminado de 5 minutos, independientemente de cualquier TTL que establezcas en tus propios marcadores de cache_control. En el usage de la respuesta, estas escrituras aparecen bajo cache_creation.ephemeral_5m_input_tokens, por lo que podrías ver escrituras de caché de 5 minutos incluso cuando cada cache_control que estableces usa un TTL de 1 hora.

Este comportamiento solo aplica cuando tu solicitud ya tiene al menos un marcador de cache_control. Las solicitudes sin almacenamiento en caché de prompts no reciben el punto de interrupción automático.



Tabla de interacción por herramienta



Próximos pasos