Uso de ferramentas com cache de prompt

Esta página aborda o cache de prompt para definições de ferramentas: onde colocar pontos de interrupção cache_control, como defer_loading preserva seu cache e o que o invalida. Para cache de prompt geral, consulte Cache de prompt.

cache_control em definições de ferramentas

Coloque cache_control: {"type": "ephemeral"} na última ferramenta em seu array tools. Isso armazena em cache todo o prefixo de definições de ferramentas, da primeira ferramenta até o ponto de interrupção 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, o ponto de interrupção cache_control fica na última ferramenta do conjunto. Você não controla a ordem das ferramentas dentro de um toolset MCP, então coloque o ponto de interrupção na entrada mcp_toolset em si e a API o aplica à ferramenta final expandida.

defer_loading e preservação de cache

Ferramentas adiadas não são incluídas no prefixo do prompt do sistema. Quando o modelo descobre uma ferramenta adiada através da busca de ferramentas, a definição é anexada inline como um bloco tool_reference no histórico de conversas. O prefixo permanece intocado, então o cache de prompt é preservado.

Isso significa que adicionar ferramentas dinamicamente através da busca de ferramentas não quebra seu cache. Você pode iniciar uma conversa com um pequeno conjunto de ferramentas sempre carregadas (em cache), deixar o modelo descobrir ferramentas adicionais conforme necessário e manter o mesmo acerto de cache em cada turno.

defer_loading também atua independentemente da construção de gramática para modo estrito. A gramática é construída a partir do conjunto completo de ferramentas independentemente de quais ferramentas são adiadas, então o cache de prompt e o cache de gramática são ambos preservados quando as ferramentas carregam dinamicamente.

O que invalida seu cache

O cache segue uma hierarquia de prefixo (tools → system → messages), então uma mudança em um nível invalida esse nível e tudo depois dele:

Tabela de interação por ferramenta

Próximos passos