Costuma-se dizer na engenharia que "Cache Rules Everything Around Me", e a mesma regra vale para agentes.
Produtos de agentes de longa execução, como o Claude Code, são viabilizados pelo prompt caching, que nos permite reutilizar a computação de viagens de ida e volta anteriores e reduzir significativamente a latência e o custo.
O que é prompt caching, como funciona e como implementá-lo tecnicamente? Leia mais no artigo de @RLanceMartin sobre prompt caching e nosso novo lançamento de auto-caching.
No Claude Code, construímos toda a nossa estrutura em torno do prompt caching. Uma alta taxa de hits no cache de prompt reduz custos e nos ajuda a criar limites de taxa mais generosos para nossos planos de assinatura, por isso monitoramos nossa taxa de hits no cache de prompt e declaramos SEVs (incidentes graves) se estiverem muito baixas.
Estas são as lições (muitas vezes contra-intuitivas) que aprendemos ao otimizar o prompt caching em escala.
Estruture seu Prompt para Caching
O prompt caching funciona por correspondência de prefixo — a API armazena em cache tudo desde o início da requisição até cada ponto de interrupção do cache_control. Isso significa que a ordem em que você coloca as coisas importa enormemente; você quer que o maior número possível de suas requisições compartilhe um prefixo.
A melhor maneira de fazer isso é conteúdo estático primeiro, conteúdo dinâmico por último. Para o Claude Code, fica assim:
- Prompt de sistema estático e Ferramentas (armazenado em cache globalmente)
- Claude.MD (armazenado em cache dentro de um projeto)
- Contexto da sessão (armazenado em cache dentro de uma sessão)
- Mensagens da conversa
Dessa forma, maximizamos quantas sessões compartilham hits de cache.
Mas isso pode ser surpreendentemente frágil! Exemplos de razões pelas quais já quebramos essa ordem incluem: colocar um timestamp detalhado no prompt de sistema estático, embaralhar as definições de ordem das ferramentas de forma não determinística, atualizar parâmetros de ferramentas (por exemplo, quais agentes o AgentTool pode chamar), etc.
Use Mensagens para Atualizações
Pode haver momentos em que as informações que você coloca no seu prompt ficam desatualizadas, por exemplo, se você tiver a hora ou se o usuário alterar um arquivo. Pode ser tentador atualizar o prompt, mas isso resultaria em um cache miss e poderia acabar sendo bastante caro para o usuário.
Considere se você pode passar essas informações por meio de mensagens na próxima rodada. No Claude Code, adicionamos uma tag <system-reminder> na próxima mensagem do usuário ou resultado de ferramenta com as informações atualizadas para o modelo (por exemplo, agora é quarta-feira), o que ajuda a preservar o cache.
Não Mude de Modelos no Meio da Sessão
Os caches de prompt são exclusivos para cada modelo, e isso pode tornar a matemática do prompt caching bastante contra-intuitiva.
Se você estiver com 100 mil tokens em uma conversa com o Opus e quiser fazer uma pergunta relativamente fácil de responder, na verdade seria mais caro mudar para o Haiku do que deixar o Opus responder, pois precisaríamos reconstruir o cache de prompt para o Haiku.
Se você precisar trocar de modelos, a melhor maneira de fazer isso é com subagentes, onde o Opus prepararia uma mensagem de "handoff" para outro modelo sobre a tarefa que precisa ser realizada. Fazemos isso frequentemente com os agentes Explore no Claude Code, que usam o Haiku.
Nunca Adicione ou Remova Ferramentas no Meio da Sessão
Alterar o conjunto de ferramentas no meio de uma conversa é uma das maneiras mais comuns de quebrar o prompt caching. Parece intuitivo — você deve dar ao modelo apenas as ferramentas que acha que ele precisa no momento. Mas como as ferramentas fazem parte do prefixo em cache, adicionar ou remover uma ferramenta invalida o cache de toda a conversa.
Modo de Planejamento — Projetado em Torno do Cache
O modo de planejamento é um ótimo exemplo de design de recursos em torno das restrições de cache. A abordagem intuitiva seria: quando o usuário entra no modo de planejamento, trocar o conjunto de ferramentas para incluir apenas ferramentas somente leitura. Mas isso quebraria o cache.
Em vez disso, mantemos todas as ferramentas na requisição o tempo todo e usamos EnterPlanMode e ExitPlanMode como ferramentas. Quando o usuário ativa o modo de planejamento, o agente recebe uma mensagem de sistema explicando que está no modo de planejamento e quais são as instruções — explorar a base de código, não editar arquivos, chamar ExitPlanMode quando o plano estiver completo. As definições das ferramentas nunca mudam.
Isso tem um benefício extra: como EnterPlanMode é uma ferramenta que o modelo pode chamar por conta própria, ele pode entrar autonomamente no modo de planejamento quando detectar um problema difícil, sem quebrar o cache.
Pesquisa de Ferramentas — Adie em Vez de Remover
O mesmo princípio se aplica ao nosso recurso de pesquisa de ferramentas. O Claude Code pode ter dezenas de ferramentas MCP carregadas, e incluí-las todas em cada requisição seria caro. Mas removê-las no meio da conversa quebraria o cache.
Nossa solução: defer_loading. Em vez de remover ferramentas, enviamos stubs leves — apenas o nome da ferramenta, com defer_loading: true — que o modelo pode "descobrir" por meio de uma ferramenta ToolSearch quando necessário. Os esquemas completos das ferramentas só são carregados quando o modelo os seleciona. Isso mantém o prefixo em cache estável: os mesmos stubs estão sempre presentes na mesma ordem.
Felizmente, você pode usar a ferramenta tool search através da nossa API para simplificar isso.
Bifurcação de Contexto — Compactação
Compactação é o que acontece quando você fica sem espaço na janela de contexto. Resumimos a conversa até o momento e continuamos uma nova sessão com esse resumo.
Surpreendentemente, a compactação tem muitos casos extremos com o prompt caching que podem ser contra-intuitivos.
Em particular, quando compactamos, precisamos enviar toda a conversa para o modelo para gerar um resumo. Se isso for uma chamada de API separada com um prompt de sistema diferente e sem ferramentas (que é a implementação simples), o prefixo em cache da conversa principal não corresponde de forma alguma. Você paga o preço total por todos esses tokens de entrada, aumentando drasticamente o custo para o usuário.
A Solução — Bifurcação Segura para Cache
Quando executamos a compactação, usamos o exato mesmo prompt de sistema, contexto do usuário, contexto do sistema e definições de ferramentas da conversa pai. Precedemos as mensagens da conversa pai e depois anexamos o prompt de compactação como uma nova mensagem do usuário no final.
Da perspectiva da API, esta requisição parece quase idêntica à última requisição do pai — mesmo prefixo, mesmas ferramentas, mesmo histórico — então o prefixo em cache é reutilizado. Os únicos tokens novos são o próprio prompt de compactação.
Isso significa, no entanto, que precisamos salvar um "buffer de compactação" para ter espaço suficiente na janela de contexto para incluir a mensagem compactada e os tokens de saída do resumo.
A compactação é complicada, mas felizmente você não precisa aprender essas lições sozinho — com base em nossos aprendizados com o Claude Code, incorporamos a compactação diretamente na API, para que você possa aplicar esses padrões em suas próprias aplicações.
Lições Aprendidas
- O prompt caching é uma correspondência de prefixo. Qualquer alteração em qualquer lugar do prefixo invalida tudo depois dele. Projete todo o seu sistema em torno dessa restrição. Acertar a ordem e a maior parte do cache funciona de graça.
- Use mensagens em vez de alterações no prompt de sistema. Você pode ficar tentado a editar o prompt de sistema para fazer coisas como entrar no modo de planejamento, alterar a data, etc., mas na verdade seria melhor inserir isso em mensagens durante a conversa.
- Não altere ferramentas ou modelos no meio da conversa. Use ferramentas para modelar transições de estado (como o modo de planejamento) em vez de alterar o conjunto de ferramentas. Adie o carregamento de ferramentas em vez de removê-las.
- Monitore sua taxa de hits de cache como monitora o uptime. Alertamos sobre quebras de cache e as tratamos como incidentes. Alguns pontos percentuais de taxa de cache miss podem afetar drasticamente o custo e a latência.
- Operações de bifurcação precisam compartilhar o prefixo do pai. Se você precisar executar uma computação lateral (compactação, sumarização, execução de habilidade), use parâmetros idênticos e seguros para cache para obter hits de cache no prefixo do pai.
O Claude Code foi construído em torno do prompt caching desde o primeiro dia; você deveria fazer o mesmo se estiver construindo um agente.
