Uso de herramientas con almacenamiento en caché de prompts

Esta página cubre el "prompt caching" (almacenamiento en caché de prompts) para definiciones de herramientas: dónde colocar los puntos de interrupción cache_control, cómo defer_loading preserva tu caché y qué lo invalida. Para el almacenamiento en caché de prompts en general, 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 cache_control recae 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 herramienta final expandida.



defer_loading y preservación del 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 (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 gramática para el modo estricto. La gramática se construye a partir del conjunto completo de herramientas sin importar qué herramientas 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é

El 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 le sigue:



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

Cuando tu solicitud tiene el almacenamiento en caché de prompts habilitado y Claude usa una herramienta del servidor como la búsqueda web, la obtención web o la 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 el 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 cache_control. En el usage de la respuesta, estas escrituras aparecen bajo cache_creation.ephemeral_5m_input_tokens, por lo que puedes ver escrituras de caché de 5 minutos incluso cuando cada cache_control que estableces usa un TTL de 1 hora.

Este comportamiento solo se aplica cuando tu solicitud ya tiene al menos un marcador 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