Uso de ferramentas com cache de prompt

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



cache_control em definições de ferramentas

Posicione cache_control: {"type": "ephemeral"} na última ferramenta do seu array tools. Isso armazena em cache todo o prefixo de definições de ferramentas, desde a 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 de cache_control é aplicado à última ferramenta do conjunto. Você não controla a ordem das ferramentas dentro de um conjunto de ferramentas MCP, então posicione o ponto de interrupção na própria entrada mcp_toolset e a API o aplicará à última ferramenta expandida.



defer_loading e preservação do cache

Ferramentas com carregamento adiado 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, então 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), permitir que o modelo descubra 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 conjunto completo de ferramentas, independentemente de quais ferramentas estão adiadas, então 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 prefixos (tools → system → messages), então uma alteração em um nível invalida esse nível e tudo que vem depois dele:



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

Quando sua requisição tem cache de prompt habilitado e Claude usa uma ferramenta de servidor, como busca na web, busca de conteúdo web ou execução de código, a API posiciona automaticamente um ponto de interrupção 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 ponto de interrupção 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 campo usage da resposta, essas gravações aparecem em cache_creation.ephemeral_5m_input_tokens, então você pode ver gravações de cache de 5 minutos mesmo quando todos os cache_control que você definiu usam um TTL de 1 hora.

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



Tabela de interação por ferramenta



Próximos passos