Uso de ferramentas com cache de prompt

Esta página aborda o "prompt caching" (cache de prompt) para definições de ferramentas: onde posicionar breakpoints de cache_control, como defer_loading preserva seu cache e o que o invalida. Para cache de prompt em geral, consulte Cache de prompt.



cache_control em definições de ferramentas

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

As entradas de toolset de uso de computador e uso de navegador seguem a mesma regra: coloque cache_control na própria entrada do toolset, e o breakpoint recai após a definição do toolset. Ele não é aceito dentro da entrada configs de um membro, porque os membros do toolset são carregados como uma única definição. Dentro de uma ação em lote, um marcador cache_control em qualquer um dos blocos tool_use ou tool_result dos membros do turno é aceito e entra em vigor ao final desse lote, de modo que vários marcadores em um lote atuam como um único breakpoint. Cada marcador ainda conta para o limite da requisição de quatro breakpoints, então use um por turno.



defer_loading e preservação do cache

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

Isso significa que adicionar ferramentas dinamicamente por meio 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 todos os turnos.

defer_loading também atua de forma independente da construção da gramática para o modo estrito. A gramática é construída a partir do toolset completo, independentemente de quais ferramentas estão adiadas, portanto tanto o cache de prompt quanto o cache de gramática são preservados quando as ferramentas são carregadas dinamicamente.



O que invalida seu cache

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



Resultados de ferramentas de servidor são armazenados em cache automaticamente

Quando sua requisição tem o cache de prompt habilitado e o Claude usa uma ferramenta de servidor, como busca na web, web fetch ou execução de código, a API posiciona automaticamente um breakpoint de cache no resultado da ferramenta de servidor antes de executar a próxima iteração do loop agêntico. Isso permite que iterações posteriores dentro da mesma requisição leiam o prefixo crescente a partir do cache em vez de reprocessá-lo.

Esse breakpoint automático sempre usa o TTL padrão de 5 minutos, independentemente de qualquer TTL que você defina em seus próprios marcadores cache_control. No usage da resposta, essas gravações aparecem em cache_creation.ephemeral_5m_input_tokens, portanto você pode ver gravações de cache de 5 minutos mesmo quando todo cache_control que você define usa um TTL de 1 hora.

Esse comportamento só se aplica quando sua requisição já possui pelo menos um marcador cache_control. Requisições sem cache de prompt não recebem o breakpoint automático.



Tabela de interação por ferramenta



Próximos passos