Uso degli strumenti con la cache dei prompt

Questa pagina tratta il "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 memorizza nella 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 viene applicato all'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 applica all'ultimo strumento espanso.

Le voci dei toolset computer use e browser use seguono la stessa regola: posiziona cache_control sulla voce del toolset stessa, e il breakpoint viene applicato dopo la definizione del toolset. Non è accettato all'interno della voce configs di un membro, perché i membri del toolset vengono caricati come un'unica definizione. All'interno di una azione batch, un marcatore cache_control su uno qualsiasi dei blocchi tool_use o tool_result dei membri del turno è accettato e ha effetto alla fine di quel batch, quindi più marcatori in un unico batch agiscono come un singolo breakpoint. Ogni marcatore conta comunque ai fini del limite di quattro breakpoint per richiesta, quindi usane uno per turno.

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 degli 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.

Ciò significa che aggiungere strumenti dinamicamente tramite la ricerca degli strumenti non invalida la tua cache. Puoi iniziare una conversazione con un piccolo set di strumenti sempre caricati (memorizzati nella cache), lasciare che il modello scopra strumenti aggiuntivi secondo necessità e mantenere lo stesso cache hit in ogni turno.

defer_loading agisce inoltre indipendentemente dalla costruzione della grammatica per la modalità strict. La grammatica viene costruita a partire dal toolset completo indipendentemente da quali strumenti siano 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 memorizzati nella 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 della 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 crescente dalla cache invece di rielaborarlo.

Questo breakpoint automatico usa sempre il TTL predefinito di 5 minuti, indipendentemente da qualsiasi TTL impostato sui tuoi marcatori cache_control. Nel campo usage della risposta, queste scritture compaiono sotto cache_creation.ephemeral_5m_input_tokens, quindi potresti vedere scritture nella cache da 5 minuti anche quando ogni cache_control che imposti 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