Um estudo de caso sobre como a Claude atinge 92% de taxa de acerto de cache
Toda vez que um agente de IA dá um passo, ele paga um imposto.
Ele rele tu do zero.
As instruções do sistema. As definições das ferramentas. O contexto do projeto que já carregou há três turnos. Tudo isso. A cada turno.
Esse é o imposto do contexto. E, para fluxos de trabalho agentivos de longa duração, é frequentemente o item mais caro em toda a sua infraestrutura de IA.
Aqui está a matemática: um prompt de sistema com 20.000 tokens rodando por 50 turnos significa 1 milhão de tokens de computação redundante cobrados a preço cheio, produzindo zero valor novo.
A solução é o cache de prompt. Mas, para usá-lo bem, você precisa entender o que realmente está acontecendo nos bastidores.
Comece com o que muda e o que não muda
Antes de otimizar qualquer coisa, você precisa pensar claramente sobre a estrutura do prompt (contexto) de um agente.
Cada requisição que seu agente envia tem duas partes fundamentalmente diferentes:
O prefixo estático: inclui instruções do sistema, definições de ferramentas, contexto do projeto, diretrizes comportamentais. Este conteúdo é idêntico em cada turno de uma sessão.
A cauda dinâmica: mensagens do usuário, saídas de ferramentas, observações do terminal. Isso é único para cada requisição e cresce à medida que a conversa avança.
Essa distinção é tudo. O prefixo estático é a parte cara que você fica recomputando sem motivo. A cauda dinâmica é a única parte que realmente precisa de computação nova.
O cache de prompt funciona armazenando o estado matemático do prefixo estático para que requisições futuras possam pular sua recomputação completamente. Você paga para processar aquele prefixo uma vez. Cada turno subsequente lê da memória.
Por que isso funciona: o que um Transformer realmente faz
Para realmente entender por que o cache é tão eficaz, você precisa entender o que acontece dentro do modelo quando ele lê seu prompt.
Cada requisição de inferência de LLM tem duas fases:
Fase 1: Preenchimento (Prefill)
É aqui que o modelo processa seu prompt de entrada completo. É limitado por computação, o que significa que executa multiplicações densas de matrizes em cada token do seu contexto. O modelo lê tudo e constrói uma representação disso. Esta é a fase lenta e cara.
Fase 2: Decodificação (Decode)
É aqui que o modelo gera tokens de saída, um de cada vez. É limitado por memória, em vez de computação, porque o modelo passa a maior parte do tempo lendo o estado computado anteriormente, em vez de executar cálculos pesados.
Durante a fase de preenchimento, o transformer constrói três vetores para cada token: uma Consulta, uma Chave e um Valor. O mecanismo de atenção usa estes para descobrir como cada token se relaciona com todos os outros tokens na sequência.
Aqui está a percepção crítica: os vetores de Chave e Valor dependem apenas dos tokens que vieram antes deles. Uma vez calculados para um determinado prefixo, eles nunca precisam mudar.
A ilustração abaixo explica visualmente o que acabamos de discutir:
Sem cache, esses tensores de Chave-Valor são descartados no momento em que uma requisição termina. A próxima requisição começa do zero e os recalcula para todos os 20.000 tokens novamente.
O cache KV resolve isso armazenando esses tensores. A infraestrutura os mantém nos servidores de inferência, indexados por um hash criptográfico do texto de entrada. Quando uma nova requisição chega com o mesmo prefixo, o hash corresponde, os tensores são recuperados imediatamente e o modelo pula toda aquela computação.
Isso reduz a complexidade computacional de O(n²) por token gerado para O(n). Para um prefixo de 20.000 tokens repetido em 50 turnos, é uma redução enorme.
A Economia
Entender a estrutura de preços é o que torna essa decisão arquitetônica tão consequente.
Veja como a Anthropic precifica o cache em suas famílias de modelos:
Três números para internalizar:
- Leituras de cache custam 10% do preço de entrada base, um desconto de 90% em cada token lido do cache
- Gravações de cache custam 25% a mais que o preço de entrada base, um pequeno prêmio para armazenar os tensores KV
- Cache estendido de 1 hora custa 2x o preço base
A matemática só funciona se sua taxa de acerto de cache permanecer alta. O que nos leva ao melhor exemplo real do que isso parece na prática.
Claude Code: Um Passo a Passo de Sessão de 30 Minutos
Claude Code é construído inteiramente em torno de um objetivo: manter o cache aquecido.
Para entender o que isso significa concretamente, vamos percorrer como é uma sessão típica de codificação de 30 minutos e rastrear exatamente o que é cobrado e o que não é.
Minuto 0: Início da Sessão
Claude Code carrega seu prompt de sistema e definições de ferramentas. Ele também lê o arquivo CLAUDE.md na raiz do seu projeto, que descreve o código e as convenções. Essa carga útil regularmente excede 20.000 tokens.
Este é o momento mais caro de toda a sessão. Cada token é novo. Mas você paga esse custo apenas uma vez.
Minutos 1 a 5: Primeiros Comandos
Você digita sua primeira instrução, algo como "veja o módulo de autenticação e sugira melhorias."
Claude Code despacha um Subagente Explorador. Ele navega pelo código, abre arquivos, executa comandos grep e constrói uma imagem do código relevante. Tudo isso é anexado à cauda dinâmica.
A fundação estática de 20.000 tokens? Já está em cache. Sendo lida de volta a $0,30/MTok em vez de $3,00/MTok. Você está pagando apenas pelas novas saídas de ferramentas e sua mensagem.
Minutos 6 a 15: Trabalho Profundo
O Subagente Planejador recebe as descobertas do Subagente Explorador. Em vez de passar os resultados brutos literalmente (o que inflaria desnecessariamente a cauda dinâmica), Claude Code passa um resumo conciso. Isso mantém o sufixo gerenciável e o cache eficiente.
O planejador produz um plano de implementação estruturado. Você o revisa, aprova e Claude Code começa a fazer alterações. Cada turno neste loop lê o prefixo de 20.000 tokens do cache. Cada acerto de cache redefine o TTL, mantendo o cache aquecido para turnos futuros.
Minutos 16 a 25: Iteração
Você pede ajustes. Claude Code revisa sua abordagem. Mais chamadas de ferramentas, mais saída de terminal. A cauda dinâmica está crescendo, mas representa apenas o conteúdo novo e único nesta sessão.
Neste ponto, a sessão processou centenas de milhares de tokens no total. Mas a fundação de 20.000 tokens foi lida do cache em cada turno.
Minuto 28: Executando /cost
Sem cache, uma sessão como essa facilmente ultrapassa 2 milhões de tokens. Nas taxas do Sonnet 4.5, isso fica em torno de $6,00.
Com cache operando em alta eficiência:
- A grande maioria dos tokens é lida do cache a $0,30/MTok
- Apenas os novos tokens da cauda dinâmica são computados do zero
Na prática, você esperaria uma redução de custo de 80%+ em uma única tarefa. Agora multiplique isso por cada usuário, a cada dia.
Para resumir, veja como o layout do prompt de sistema se parece à medida que a sessão continua:
A Regra que Quebra Tudo
Aqui está a coisa mais contraintuitiva sobre cache de prompt.
1 + 2 = 3. Mas 2 + 1 é uma perda de cache.
A infraestrutura hasheia o prompt. O hash é um identificador para criptografia. O hash muda se alguma coisa nessa ordem mudar, mesmo que dois elementos estejam em uma ordem diferente. O cache está vazio. O prefixo inteiro é recalculado a preço cheio.
Três regras que decorrem disso:
- Não adicione ou remova ferramentas durante uma sessão. O prefixo em cache inclui ferramentas. Mudar as ferramentas torna tudo que vem depois inútil.
- Nunca troque de modelo no meio da sessão. Caches são específicos do modelo. Mudar para um modelo mais barato no meio da conversa exige reconstruir todo o cache.
- Nunca mude o prefixo para mudar o estado. Em vez disso, Claude Code adiciona uma tag à próxima mensagem do usuário que lembra o sistema. O prefixo nunca muda.
O Que Isso Significa para Você
Tudo acima explica como Claude Code lida com o cache. As mesmas regras se aplicam se você está criando seu próprio agente.
É assim que você deve estruturar seus prompts:
- No topo, instruções do sistema e regras. Não mude no meio.
- Carregue todas as ferramentas que você precisará com antecedência. Não adicione ou remova.
- Contexto e documentos recuperados depois disso. Estáticos durante a duração.
- No final, o histórico da conversa e as saídas da ferramenta.
Com o cache automático ativado, o ponto de ruptura avança automaticamente à medida que a conversa continua.
Claude Code é responsável por seu próprio cache. A Anthropic acabou de adicionar cache automático à sua API, então você pode fazer o mesmo para seu próprio agente.
Sem cache automático, você tinha que lembrar onde estavam os limites dos tokens. Um limite errado significava não acessar o cache.
Use bifurcação segura de cache para compactar o limite de contexto. Use o mesmo prompt de sistema, ferramentas e conversa, depois adicione a compactação como uma nova mensagem.
A chamada de compactação parece quase exatamente com a última. O prefixo em cache é usado novamente. A única coisa que é cobrada como nova é a instrução de compactação.
Para ver se uma API está funcionando, fique de olho nestes três campos em cada resposta:
- cache_creation_input_tokens: tokens colocados na memória
- cache_read_input_tokens: tokens lidos da memória
- input_tokens: tokens processados normalmente
Sua pontuação de eficiência de cache é o número de tokens lidos em comparação com o número de tokens criados. Fique de olho nisso da mesma forma que fica de olho no tempo de atividade.
Principais Conclusões
Cache de prompt não é um recurso que você ativa. É uma disciplina arquitetônica em torno da qual você constrói.
Claude Code é o melhor exemplo de como isso se parece quando é feito em grande escala.
Uma taxa de acerto de cache de 92%. Uma redução de custos de 81%.
Este é o modelo se você está criando agentes. Você não pode ignorar o imposto; ele existe. A única coisa que importa é se você está pagando por ele ou se livrando dele.
