Uso degli strumenti con la cache dei prompt

Questa pagina tratta la "prompt caching" (cache dei prompt) per le definizioni degli strumenti: dove posizionare i breakpoint cache_control, come defer_loading preserva la tua cache e cosa la invalida. Per la cache dei prompt in generale, consulta Cache dei prompt.



cache_control sulle definizioni degli strumenti

Posiziona cache_control: {"type": "ephemeral"} sull'ultimo strumento nel tuo array tools. Questo mette in cache l'intero prefisso delle definizioni degli strumenti, dal primo strumento fino al breakpoint contrassegnato:

{
  "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" }
    }
  ]
}

Per mcp_toolset, il breakpoint cache_control ricade sull'ultimo strumento del set. Non controlli l'ordine degli strumenti all'interno di un toolset MCP, quindi posiziona il breakpoint sulla voce mcp_toolset stessa e l'API lo applicherà all'ultimo strumento espanso.



defer_loading e preservazione della cache

Gli strumenti differiti non sono inclusi nel prefisso del prompt di sistema. Quando il modello scopre uno strumento differito tramite la ricerca di strumenti, la definizione viene aggiunta inline come blocco tool_reference nella cronologia della conversazione. Il prefisso rimane intatto, quindi la cache dei prompt viene preservata.

Questo significa che aggiungere strumenti dinamicamente tramite la ricerca di strumenti non interrompe la tua cache. Puoi iniziare una conversazione con un piccolo insieme di strumenti sempre caricati (in cache), lasciare che il modello scopra strumenti aggiuntivi secondo necessità e mantenere lo stesso cache hit a ogni turno.

defer_loading agisce anche in modo indipendente dalla costruzione della grammatica per la modalità strict. La grammatica viene costruita dall'intero toolset indipendentemente da quali strumenti sono differiti, quindi sia la cache dei prompt sia la cache della grammatica vengono preservate quando gli strumenti vengono caricati dinamicamente.



Cosa invalida la tua cache

La cache segue una gerarchia di prefissi (tools → system → messages), quindi una modifica a un livello invalida quel livello e tutto ciò che segue:



I risultati degli strumenti server vengono messi in cache automaticamente

Quando la tua richiesta ha la cache dei prompt abilitata e Claude usa uno strumento server come la ricerca web, il web fetch o l'esecuzione di codice, l'API posiziona automaticamente un breakpoint di cache sul risultato dello strumento server prima di eseguire l'iterazione successiva del ciclo agentico. Questo consente alle iterazioni successive all'interno della stessa richiesta di leggere il prefisso in crescita dalla cache invece di rielaborarlo.

Questo breakpoint automatico usa sempre il TTL predefinito di 5 minuti, indipendentemente da qualsiasi TTL tu abbia impostato sui tuoi marcatori cache_control. Nella risposta usage, queste scritture appaiono sotto cache_creation.ephemeral_5m_input_tokens, quindi potresti vedere scritture in cache da 5 minuti anche quando ogni cache_control che hai impostato usa un TTL di 1 ora.

Questo comportamento si applica solo quando la tua richiesta ha già almeno un marcatore cache_control. Le richieste senza cache dei prompt non ricevono il breakpoint automatico.



Tabella delle interazioni per strumento



Prossimi passi