Uso degli strumenti con la cache dei prompt

Questa pagina tratta la 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 informazioni generali sulla cache dei prompt, 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 puoi controllare 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 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 avviare 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 in modo indipendente dalla costruzione della grammatica per la modalità strict. La grammatica viene costruita dal toolset completo indipendentemente da quali strumenti sono differiti, quindi sia la cache dei prompt che 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 utilizza 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 utilizza sempre il TTL predefinito di 5 minuti, indipendentemente da qualsiasi TTL impostato sui tuoi marcatori cache_control. Nel campo usage della risposta, queste scritture appaiono sotto cache_creation.ephemeral_5m_input_tokens, quindi potresti vedere scritture nella cache da 5 minuti anche quando ogni cache_control che hai impostato utilizza 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



Passaggi successivi