Um estudo de caso de como o Claude alcança 92% de taxa de acerto de cache
Toda vez que um agente de IA executa uma etapa, ele paga um imposto.
Ele relê tudo 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 de contexto. E, para fluxos de trabalho agentivos de longa duração, muitas vezes é o item de custo mais caro em toda a sua infraestrutura de IA.
Aqui está a matemática: um prompt de sistema com 20.000 tokens executados ao longo de 50 turnos significa 1 milhão de tokens de computação redundante cobrada a preço cheio, produzindo valor novo zero.
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 todos os turnos 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 recombinação por completo. 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.
Toda requisição de inferência de LLM tem duas fases:
Fase 1: Preenchimento (Prefill)
É aqui que o modelo processa todo o prompt de entrada. É limitado por computação, ou seja, 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 previamente computado, em vez de executar cálculos pesados.
Durante a fase de preenchimento, o transformer constrói três vetores para cada token: uma Query, uma Key e um Value. O mecanismo de atenção usa esses vetores para descobrir como cada token se relaciona com todos os outros tokens na sequência.
Aqui está a percepção crítica: os vetores Key e Value 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 Key-Value 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, isso é uma redução enorme.
A Economia
Entender a estrutura de preços é o que torna essa decisão arquitetural tão significativa.
Aqui está 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
- Escritas 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 de como isso se parece na prática.
Claude Code: Um Tour de Sessão de 30 Minutos
O 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
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 "olhe o módulo de autenticação e sugira melhorias."
O Claude Code despacha um Subagente de Exploração. 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 base 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 Pesado
O Subagente de Planejamento recebe as descobertas do Subagente de Exploração. Em vez de passar os resultados brutos na íntegra (o que aumentaria a cauda dinâmica desnecessariamente), o 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 o Claude Code começa a fazer as 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. O 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 base de 20.000 tokens foi lida do cache a cada turno.
Minuto 28: Executando /cost
Sem cache, uma sessão como esta facilmente ultrapassa 2 milhões de tokens. Nas taxas do Sonnet 4.5, isso custa cerca de $6,00.
Com o 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 algo na faixa de uma redução de custo de 80%+ em uma única tarefa. Agora multiplique isso por cada usuário, todos os dias.
Para resumir, aqui está como o layout do prompt do sistema se parece conforme 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 falha de cache.
A infraestrutura hasheia o prompt. O hash é um identificador para criptografia. O hash muda se qualquer 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. Alterar as ferramentas torna tudo o que vem depois inútil.
- Nunca troque de modelos no meio da sessão. Os 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 alterar o estado. Em vez disso, o 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 o Claude Code lida com o cache. As mesmas regras se aplicam se você estiver fazendo seu próprio agente.
É assim que você deve estruturar seus prompts:
- No topo, estão as instruções do sistema e regras. Não mude no meio.
- Carregue todas as ferramentas que você precisará com antecedência. Não as adicione ou remova.
- Contexto recuperado e documentos depois disso. Estático durante a duração.
- Na parte inferior, o histórico da conversa e as saídas da ferramenta.
Com o cache automático ativado, o ponto de interrupção avança automaticamente conforme a conversa continua.
O Claude Code é responsável por seu próprio cache. A Anthropic acabou de adicionar cache automático à sua API, para que você possa fazer o mesmo para seu próprio agente.
Sem o cache automático, você precisava lembrar onde estavam os limites dos tokens. Um limite errado significava não acessar o cache.
Use fork seguro para cache para compactar até o limite de contexto. Use o mesmo prompt de sistema, ferramentas e conversa, e então adicione a compactação como uma nova mensagem.
A chamada de compactação parece quase exatamente com a anterior. O prefixo em cache é usado novamente. A única coisa cobrada como nova é a instrução de compactação.
Para verificar 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 comparado ao número de tokens criados. Fique de olho nisso da mesma forma que você fica de olho no tempo de atividade.
Principais Conclusões
O cache de prompt não é um recurso que você ativa. É uma disciplina arquitetural em torno da qual você constrói.
O Claude Code é o melhor exemplo de como esse campo 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.
