Prompt caching em agentes é frágil e afetado por mudanças triviais

O problema central

Agentes de código enviam ao modelo, a cada turno, praticamente todo o contexto anterior (system prompt, definições de ferramentas, histórico de conversa, resultados de tools) mais um pequeno incremento. O prompt caching evita recalcular esse prefixo repetido, mas é frágil: mudanças triviais - uma ferramenta adicionada, uma troca de modelo, uma pausa longa - podem invalidar o cache e forçar o reprocessamento de dezenas de milhares de tokens ao preço cheio de input.

Como o KV cache funciona

Um transformer tem duas fases: prefill (processa os tokens de entrada e computa o estado de atenção) e decode (gera novos tokens). Os pares chave-valor (K/V) de cada token processado são retidos para que tokens futuros possam "atender" a tudo que veio antes sem recomputar. O prompt caching estende a vida útil desse estado entre requisições: se o próximo request começa com os mesmos tokens, o sistema reusa o trabalho armazenado e faz prefill apenas do sufixo novo.

Onde o cache vive

Duas abordagens principais: afinidade de sessão (o KV cache fica na GPU que o computou e o roteador envia o próximo request ao mesmo worker - rápido, mas restringe scheduling) e cache distribuído (blocos KV são armazenados em outra camada de memória e compartilhados entre workers - mais flexível, mas complexo de implementar).

Por que tool loadouts destroem o cache

Definições de ferramentas aparecem antes da conversa. Adicionar, remover ou reordenar uma ferramenta move o primeiro mismatch para o início do prompt, invalidando todo o histórico subsequente. Carregar ferramentas dinamicamente (estilo MCP) parece eficiente, mas na prática pode custar mais do que enviar todas desde o início. Modelos mais novos suportam carregamento aditivo (a ferramenta é ancorada num tool result específico, preservando o prefixo), e o Pi usa isso quando disponível.

TTLs e interrupções

O cache padrão da Anthropic expira em 5 minutos - menos que muitas pausas naturais (build, teste, café). Voltar após 10 minutos e enviar "continue" pode custar mais do que o esperado, pois o prefixo inteiro é reprocessado. O Claude Code, para assinantes, estende o TTL para 1 hora. O Pi permite optar por retenção longa via PI_CACHE_RETENTION=long, mas não pode forçar o provedor a manter a entrada.

O custo de um miss

Numa sessão com 100k tokens de histórico, um cache hit cobra quase tudo a preço de leitura (descontado). Um miss reprocessa tudo a preço de input e pode ainda cobrar a escrita. Gateways e revendedores podem ter incentivos desalinhados: faturam mais com misses, mesmo que isso não gere mais lucro.

Por que o Pi não faz pruning agressivo

Deletar conteúdo do meio do histórico muda o prefixo no ponto da edição e pode custar mais (rewrite imediato) do que economiza (tokens futuros mais baratos). O Pi prefere um transcript estável e append-oriented, com compactação apenas quando a pressão de contexto justifica - tratada como reset de cache, não como falha.

Visibilidade

O Pi mostra métricas de cache no footer (R, W, CH) e no comando /session (tokens cached/uncached, hit rate acumulado, custo re-faturado por misses significativos). É possível ativar notificações de miss em tempo real.