Você construiu o loop agêntico. As tools são chamadas, os resultados voltam, o modelo raciocina sobre o próximo passo — tudo funciona como um pequeno cérebro autônomo. Aí você abre o dashboard de uso da Anthropic depois de um dia de testes. Aquele número não é um erro de digitação. É o custo de reenviar o mesmo system prompt e os mesmos tool schemas em cada iteração, pelo preço cheio, para uma API stateless que não faz a menor ideia do que você mandou três segundos atrás.

E se você atualizou para o Opus 4.7 em 16 de abril de 2026 — e provavelmente atualizou — o Simon Willison mediu que o novo tokenizer produz 1,46× mais tokens para system prompts idênticos. Seus custos subiram 35-40% da noite pro dia pelo mesmo texto de sempre. A análise da Finout (27 de abril de 2026) confirma o padrão em diversos workloads.

Por que "só otimizar os prompts" não resolve

A resposta óbvia: encurtar os prompts. Claro, corte a gordura. Mas num loop agêntico real, o prefixo estático — o system prompt, as definições de tools (schemas que dizem ao modelo quais tools ele pode chamar e quais parâmetros elas aceitam), e o histórico acumulado da conversa — facilmente bate 10.000+ tokens. Com 6 tools e um system prompt decente, são ~11.000 tokens de conteúdo idêntico reenviados a cada turno.

Em 10 iterações, são 110.000 tokens de pura repetição a $5/MTok no Opus 4.7. Isso dá $0,55 só em custos de input — apenas por bytes que o servidor já viu. Escale para 50 turnos e você está queimando dólares numa conversa só.

Nenhuma quantidade de corte em prompt resolve um protocolo fundamentalmente stateless. Você precisa que o servidor lembre.

A solução: prompt caching

A API de prompt caching da Anthropic (GA desde 17 de dezembro de 2024) permite marcar blocos de mensagem com um breakpoint cache_control — um marcador que diz ao servidor "armazene tudo até este ponto". Nas requisições seguintes, se os bytes baterem exatamente, o servidor lê do cache e cobra 10% do preço normal de input. Segundo a documentação da Anthropic, o cache de 5 minutos (padrão) custa 1,25× na escrita inicial; o cache de 1 hora custa 2×.

A matemática é simples: pague 25% a mais uma vez, ganhe 90% de desconto em cada hit seguinte. Num loop de 10 turnos, é 1 write + 9 reads. Se paga no primeiro cache hit.

Passo 1: Cache no system prompt

O system prompt é o conteúdo mais estável do seu loop. Ele nunca muda entre iterações. Torne-o cacheável:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    system=[{
        "type": "text",
        "text": "Seu system prompt longo com instruções...",
        "cache_control": {"type": "ephemeral"},  # TTL de 5 min
    }],
    messages=[...],
)

O detalhe crucial: no Opus 4.7 (e Opus 4.5, Haiku 4.5), o bloco mínimo cacheável é 4.096 tokens. Se seu system prompt for menor que isso, a Anthropic ignora silenciosamente o marcador cache_control — sem erro, sem cache, só intenção desperdiçada. No Sonnet, o mínimo é 1.024 tokens.

/faion é a skill guarda-chuva do faion-network — ela puxa metodologia relevante de 12 domínios especialistas para a conversa, então antes de desenhar sua estratégia de cache, pergunte:

/faion
Estou implementando prompt caching da Anthropic para um loop agêntico multi-tool.
Qual a melhor estratégia para posicionar breakpoints de cache_control quando tenho
um system prompt, 6 tool schemas e um histórico de conversa crescendo?

Passo 2: Cache nas definições de tools

Tool schemas — as descrições JSON do nome, parâmetros e propósito de cada tool — ficam no array tools e são processados antes do system prompt na hierarquia de cache. Coloque o cache_control na última tool do array para cachear todas em um único breakpoint:

tools = [
    {"name": "search_web", "description": "...", "input_schema": {...}},
    {"name": "read_file", "description": "...", "input_schema": {...}},
    {"name": "run_code", "description": "...", "input_schema": {...}},
    {"name": "write_file", "description": "...", "input_schema": {...}},
    {"name": "list_dir", "description": "...", "input_schema": {...}},
    {"name": "submit_result", "description": "...", "input_schema": {...},
     "cache_control": {"type": "ephemeral"}},  # cacheia TODAS as tools acima
]

Regra crítica: a hierarquia de cache é tools → system → messages. Mudar qualquer definição de tool entre iterações (adicionar uma tool, renomear um parâmetro) invalida o cache de tools, system E messages. No loop agêntico, mantenha seu conjunto de tools congelado.

Passo 3: Cache no prefixo do histórico

Conforme a conversa cresce, mensagens antigas se tornam estáticas — não vão mudar. Coloque um breakpoint na última mensagem da porção "estável":

messages = [
    {"role": "user", "content": "Tarefa inicial..."},
    {"role": "assistant", "content": "Vou começar por..."},
    {"role": "user", "content": [{  # última mensagem estável
        "type": "text",
        "text": "Resultado da tool do passo 3...",
        "cache_control": {"type": "ephemeral"},
    }]},
    {"role": "assistant", "content": "Agora processando..."},  # novo, sem cache
]

Agora você tem 3 breakpoints (tools, system, histórico). A API permite no máximo 4. Guarde o último slot para casos extremos.

Passo 4: O truque da realocação

Esse vem do time de engenharia da ProjectDiscovery, que publicou seus resultados em 10 de abril de 2026. Eles rodam um scanner de segurança agêntico de 26 passos e 40 chamadas de tool. A taxa de cache hit inicial era patética: 7%.

O problema: o system prompt deles continha timestamps, working memory e variáveis de runtime que mudavam a cada chamada. O cache matching exige igualdade exata de bytes — um caractere diferente e o bloco inteiro dá miss.

A solução: mover todo o conteúdo dinâmico para fora do system prompt e jogar numa mensagem com role user no final da conversa. O system prompt se torna byte-idêntico entre chamadas. A taxa de cache hit pulou de 7% para 74% da noite pro dia, eventualmente chegando a 84% com mais ajustes — uma redução de 70% nos custos.

/faion
Como devo separar conteúdo estático vs. dinâmico num system prompt
agêntico para maximizar cache hit rates? Que padrões existem para o
split static-system-prompt + dynamic-user-reminder?

Passo 5: Verifique se está realmente funcionando

Cache hits são invisíveis se você não olhar. A maioria dos SDK wrappers e frameworks de logging não exibem métricas de cache. Você precisa verificar explicitamente:

usage = response.usage
print(f"Cache escrito:  {usage.cache_creation_input_tokens}")
print(f"Cache lido:     {usage.cache_read_input_tokens}")
print(f"Sem cache:      {usage.input_tokens}")

hit_rate = usage.cache_read_input_tokens / (
    usage.cache_read_input_tokens +
    usage.cache_creation_input_tokens +
    usage.input_tokens
) * 100
print(f"Cache hit rate: {hit_rate:.1f}%")

Na segunda iteração do loop, cache_read_input_tokens deveria ser grande. Se for zero, algo está invalidando seu cache — verifique diferenças no nível de bytes no seu conteúdo "estático".

Armadilhas que vão comer seu dinheiro

1. O abismo dos 5 minutos. O TTL padrão (time-to-live — por quanto tempo o servidor lembra do seu conteúdo cacheado) é 5 minutos. Se uma chamada de tool leva 6 minutos (timeout de API externa, computação longa), o cache expira. Você paga o premium de escrita de novo. Solução: use "ttl": "1h" para workflows lentos, mas saiba que custa 2× em vez de 1,25× na escrita. E TTLs mais longos devem aparecer antes dos mais curtos na requisição — o inverso dá erro.

2. Ordem das chaves JSON. Algumas linguagens randomizam a ordem das chaves JSON na serialização. Ordem diferente = bytes diferentes = cache miss. Fixe a ordem de serialização ou use sort_keys=True.

3. O lookback de 20 blocos. O sistema busca no máximo 20 blocos de conteúdo para trás procurando entradas cacheadas. Em conversas longas (>20 blocos), breakpoints antigos ficam fora da janela de busca. Adicione breakpoints novos a cada ~18 blocos. O estudo da PwC de janeiro de 2026 descobriu que é aqui que a maioria dos "cache misses misteriosos" acontecem.

4. Cachear conteúdo curto custa mais. A PwC mediu que prompts com menos de 500 tokens apresentam 10-18% pior latência com caching por causa do overhead. Não cache seu system prompt de 200 tokens. No Opus ele precisa ter no mínimo 4.096 tokens de qualquer forma.

O que você pode fazer agora

Você tem três breakpoints — tools, system, prefixo do histórico — e um padrão de monitoramento. O mesmo loop agêntico que queimava $0,55 por conversa de 10 turnos no Opus 4.7 agora custa ~$0,12. Isso não é erro de arredondamento; é a diferença entre um protótipo que você mostra uma vez e um sistema que você realmente coloca em produção. A taxa de 35% do tokenizer do Opus 4.7? Continua lá, mas você paga uma vez por cache write em vez de cada turno. Bem-vindo à parte onde a página de billing para de dar medo.