--- title: Uso de ferramentas com cache de prompt url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching description: Armazene definições de ferramentas em cache entre turnos e entenda o que invalida seu cache. --- Esta página aborda o "prompt caching" (cache de prompt) para definições de ferramentas: onde posicionar os breakpoints 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching). ## 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, desde a primeira ferramenta até o breakpoint marcado: ```json { "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 aplicará à última ferramenta expandida. As entradas de toolset de [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) e [uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) seguem a mesma regra: coloque `cache_control` na própria entrada do toolset, e o breakpoint recairá 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions), 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 mesmo lote atuam como um único breakpoint. Cada marcador ainda conta para o limite de [quatro breakpoints](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#when-to-use-multiple-breakpoints) da requisição, 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use). 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 prefixos (`tools` → `system` → `messages`), portanto uma alteração em um nível invalida esse nível e tudo o que vem depois dele: | Alteração | Invalida | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Modificar definições de ferramentas | Todo o cache (tools, system, messages) | | Ativar ou desativar busca na web ou citações | Caches de system e messages | | Alterar `tool_choice` | Cache de messages | | Alterar `disable_parallel_tool_use` | Cache de messages | | Alternar presença/ausência de imagens | Cache de messages | | Alterar parâmetros de pensamento | Cache de messages sempre; caches de tools e system também em modelos que renderizam a configuração de pensamento antes deles ([detalhes](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching)) | | Alterar `output_config.effort` | Igual aos parâmetros de pensamento; definir explicitamente o padrão do modelo é equivalente a omiti-lo | Se você precisar variar `tool_choice` no meio da conversa, considere posicionar breakpoints de cache antes do ponto de variação. ## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools), 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ê definiu 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 | Ferramenta | Considerações de cache | | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Busca na web](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool) | Habilitar ou desabilitar invalida os caches de system e messages | | [Web fetch](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool) | Habilitar ou desabilitar invalida os caches de system e messages | | [Execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) | O estado do contêiner é independente do cache de prompt | | [Busca de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool) | Ferramentas descobertas são carregadas como blocos `tool_reference`, preservando o cache de prefixo | | [Uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) | A presença de capturas de tela afeta o cache de messages; `cache_control` vai na entrada do toolset (consulte [cache\_control em definições de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)) | | [Uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) | A presença de capturas de tela afeta o cache de messages; `cache_control` vai na entrada do toolset (consulte [cache\_control em definições de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching#cache-control-on-tool-definitions)) | | [Editor de texto](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool) | Ferramenta de cliente padrão, sem interação especial com o cache | | [Bash](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool) | Ferramenta de cliente padrão, sem interação especial com o cache | | [Memória](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool) | Ferramenta de cliente padrão, sem interação especial com o cache | ## Próximos passos Conheça o modelo completo de cache de prompt, incluindo TTLs e preços. Carregue ferramentas sob demanda sem quebrar seu cache. Navegue por todas as ferramentas disponíveis e seus parâmetros.