É muito comum na engenharia dizer que "Cache Rules Everything Around Me" (Cache Rege Tudo ao Meu Redor), e a mesma regra vale para agentes.
Produtos agentivos de longa duração como o Claude Code são viabilizados pelo prompt caching, que nos permite reutilizar a computação de interações 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 cache automático.
No Claude Code, construímos toda a nossa estrutura em torno do prompt caching. Uma alta taxa de acertos no cache de prompts reduz custos e nos ajuda a criar limites de taxa mais generosos para nossos planos de assinatura. Por isso, monitoramos nossa taxa de acertos e declaramos SEVs (incidentes críticos) quando ela está muito baixa.
Estas são as lições (muitas vezes contraintuitivas) que aprendemos ao otimizar o prompt caching em escala.
Organize seu Prompt para o Cache
O prompt caching funciona por correspondência de prefixo (prefix matching) — 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 é extremamente importante; você quer que o maior número possível de suas requisições compartilhe um prefixo.
A melhor maneira de fazer isso é colocar o conteúdo estático primeiro e o conteúdo dinâmico por último. No Claude Code, isso se parece com:
- System prompt estático e Ferramentas (armazenados 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 acertos de cache.
Mas isso pode ser surpreendentemente frágil! Exemplos de razões pelas quais já quebramos essa ordenação incluem: colocar um timestamp detalhado no system prompt estático, embaralhar a ordem das definições das ferramentas de forma não determinística, atualizar parâmetros das ferramentas (como 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 se tornam 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 uma falha de cache (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 interação. No Claude Code, adicionamos uma tag <system-reminder> na próxima mensagem do usuário ou no resultado da 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 específicos para cada modelo, e isso pode tornar a matemática do prompt caching bastante contraintuitiva.
Se você está 100 mil tokens em uma conversa com o Opus e quer fazer uma pergunta relativamente fácil de responder, na verdade seria mais caro mudar para o Haiku do que deixar o Opus responder, porque precisaríamos reconstruir o cache de prompt para o Haiku.
Se você precisar mudar de modelo, 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 feita. 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 naquele momento. Mas como as ferramentas fazem parte do prefixo armazenado em cache, adicionar ou remover uma ferramenta invalida o cache de toda a conversa.
Modo de Planejamento (*Plan Mode*) — Projetado em Torno do Cache
O Plan Mode é um ótimo exemplo de como projetar recursos em torno das restrições de cache. A abordagem intuitiva seria: quando o usuário entra no Plan Mode, 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 em si. Quando o usuário ativa o Plan Mode, o agente recebe uma mensagem do sistema explicando que está no Plan Mode 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 próprio modelo pode chamar, ele pode entrar automaticamente no Plan Mode quando detectar um problema difícil, sem quebrar o cache.
Pesquisa de Ferramentas (*Tool Search*) — 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 incluir todas elas em todas as requisições seria caro. Mas removê-las no meio da conversa quebraria o cache.
Nossa solução: defer_loading (carregamento adiado). 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ão carregados apenas quando o modelo as 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 de pesquisa por meio da nossa API para simplificar isso.
Bifurcação de Contexto (*Forking*) — Compatação
A compatação (compaction) é 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 compatação tem muitos casos extremos com prompt caching que podem ser contraintuitivos.
Em particular, quando compactamos, precisamos enviar toda a conversa para o modelo gerar um resumo. Se esta for uma chamada de API separada com um system prompt diferente e sem ferramentas (que é a implementação simples), o prefixo em cache da conversa principal não corresponde em nada. Você paga o preço total por todos aqueles tokens de entrada, aumentando drasticamente o custo para o usuário.
A Solução — Bifurcação Segura para Cache (*Cache-Safe Forking*)
Quando executamos a compatação, usamos exatamente o mesmo system prompt, contexto de usuário, contexto de sistema e definições de ferramentas da conversa pai. Preparamos as mensagens da conversa pai e depois anexamos o prompt de compatação como uma nova mensagem do usuário no final.
Da perspectiva da API, esta requisição parece quase idêntica à última requisição da conversa pai — mesmo prefixo, mesmas ferramentas, mesmo histórico — portanto, o prefixo em cache é reutilizado. Os únicos tokens novos são o próprio prompt de compatação.
Isso significa, no entanto, que precisamos salvar um "buffer de compatação" para ter espaço suficiente na janela de contexto para incluir a mensagem compactada e os tokens de saída do resumo.
A compatação é complicada, mas felizmente você não precisa aprender essas lições por conta própria — com base no que aprendemos com o Claude Code, incorporamos a compatação diretamente na API, para que você possa aplicar esses padrões em seus próprios aplicativos.
Lições Aprendidas
- Prompt caching é uma correspondência de prefixo. Qualquer alteração em qualquer lugar do prefixo invalida tudo o que vem depois. Projete todo o seu sistema em torno dessa restrição. Acertar a ordem faz a maior parte do cache funcionar sem esforço adicional.
- Use mensagens em vez de alterações no system prompt. Você pode ficar tentado a editar o system prompt para coisas como entrar no Modo de Planejamento, mudar a data etc., mas na verdade é melhor inserir essas informações em mensagens durante a conversa.
- Não mude de 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 acertos de cache como você monitora o tempo de atividade (*uptime*). Nós alertamos sobre quebras de cache e as tratamos como incidentes. Alguns pontos percentuais de taxa de falha de cache podem afetar drasticamente o custo e a latência.
- Operações de bifurcação precisam compartilhar o prefixo da conversa pai. Se você precisar executar uma computação paralela (compatação, sumarização, execução de habilidade), use parâmetros idênticos e seguros para cache para obter acertos de cache no prefixo da conversa 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.
