Uso de ferramentas com cache de prompt

Esta página cobre o "prompt caching" (cache de prompt) para definições de ferramentas: onde colocar 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 faz cache de todo o prefixo de definições de ferramentas, desde a 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.



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 intocado, 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), 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 de gramática para o modo estrito. A gramática é construída a partir do toolset completo 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 prefixo (tools → system → messages), então uma mudança 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 solicitação tem cache de prompt habilitado e Claude usa uma ferramenta de servidor como busca na web, busca de páginas web ou execução de código, a API coloca 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 solicitação leiam o prefixo crescente 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, 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 solicitação já tem pelo menos um marcador cache_control. Solicitações sem cache de prompt não recebem o breakpoint automático.



Tabela de interação por ferramenta



Próximos passos