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 de cache_control, cómo defer_loading preserva tu caché y qué la 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 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.

Las entradas de conjunto de herramientas de uso de computadora y uso de navegador siguen la misma regla: coloca cache_control en la entrada del conjunto de herramientas misma, y el punto de interrupción se ubica después de la definición del conjunto de herramientas. No se acepta dentro de la entrada configs de un miembro, porque los miembros del conjunto de herramientas se cargan como una sola definición. Dentro de una acción por lotes, un marcador cache_control en cualquiera de los bloques tool_use o tool_result de los miembros del turno se acepta y surte efecto al final de ese lote, por lo que varios marcadores en un lote actúan como un único punto de interrupción. Cada marcador sigue contando para el límite de la solicitud de cuatro puntos de interrupción, así que usa uno por turno.



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 mediante 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 mediante la búsqueda de herramientas no rompe tu caché. Puedes iniciar una conversación con un pequeño conjunto 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 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 le sigue:



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

Cuando tu solicitud tiene habilitado el almacenamiento en caché de prompts y Claude usa una herramienta de 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 de 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 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 establezcas use 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