Noções Básicas de Cache de Prompt

8 exemplos para você começar com o cache de prompt - 5 básicos e 3 intermediários.

Pré-requisitos

• Instale o SDK: pip install anthropic
• Defina sua chave de API no ambiente: export ANTHROPIC_API_KEY=sk-ant-...
• Todos os exemplos abaixo usam anthropic.Anthropic(), que lê essa variável de ambiente automaticamente.

Exemplos Básicos

1. Adicionar um Único Breakpoint cache_control

Marque o final de um prompt do sistema longo como cacheável.

import anthropic
 
client = anthropic.Anthropic()
 
long_policy_text = "Você é o assistente de suporte da Acme Corp. " * 300
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)
print(response.content[0].text)

• cache_control é definido no bloco de conteúdo do sistema, não na solicitação como um todo.
• Tudo até e incluindo este bloco torna-se elegível para cache.
• A primeira chamada sempre grava o cache; ainda não pode ser um acerto.
• {"type": "ephemeral"} usa o TTL padrão de 5 minutos.

Relacionado: Como o Match de Prefixo do Cache de Prompt Realmente Funciona - por que isso tem que ser idêntico em bytes para acertar.

2. Verificar usage.cache_creation_input_tokens na Primeira Chamada

Confirme se a primeira solicitação gravou uma entrada de cache.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)
print("tokens de criação de cache:", response.usage.cache_creation_input_tokens)
print("tokens de leitura de cache:", response.usage.cache_read_input_tokens)

• cache_creation_input_tokens deve ser diferente de zero aqui - essa é a gravação do cache.
• cache_read_input_tokens deve ser 0 nesta primeira chamada, pois nada existia para ler ainda.
• Esses campos residem em response.usage, ao lado dos input_tokens e output_tokens normais.

3. Repetir a Mesma Solicitação e Confirmar um Acerto de Cache

Envie um prefixo idêntico novamente dentro da janela TTL.

response_2 = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Você envia internacionalmente?"}],
)
print("tokens de leitura de cache:", response_2.usage.cache_read_input_tokens)

• O bloco system é idêntico em bytes ao exemplo 1, portanto, o prefixo corresponde.
• Apenas a mensagem final do usuário foi alterada, e ela fica após o breakpoint.
• cache_read_input_tokens agora deve ser diferente de zero - este é o acerto de cache.
• A resposta ainda responde à nova pergunta corretamente; o cache apenas evita o reprocessamento do prefixo compartilhado.

4. Definir um TTL Explícito

Escolha a janela de cache de 1 hora em vez do padrão de 5 minutos.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral", "ttl": "1h"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)

• "ttl": "1h" estende por quanto tempo a entrada sobrevive antes de precisar ser regravada.
• O TTL de 1 hora tem um multiplicador de custo de gravação de cache mais alto do que o padrão de 5 minutos.
• Omitir ttl é o mesmo que "5m".
• Escolha 1 hora para sessões que provavelmente abrangerão mais de alguns minutos entre as chamadas.

Relacionado: Opções de TTL de Cache e Referência de Preços - comparação completa das duas janelas.

5. Cachear Definições de Ferramentas em Vez do Prompt do Sistema

Coloque o breakpoint em um esquema de ferramenta grande.

tools = [
    {
        "name": "search_docs",
        "description": "Pesquise a base de conhecimento interna." * 20,
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
        "cache_control": {"type": "ephemeral"},
    }
]
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    tools=tools,
    messages=[{"role": "user", "content": "Encontre nossa política de férias."}],
)

• cache_control pode ir na última ferramenta em uma lista tools, não apenas em system.
• As ferramentas são avaliadas antes do prompt do sistema no prefixo efetivo.
• Isso vale a pena fazer quando você tem muitos ou grandes esquemas de ferramentas que raramente mudam.
• Um catálogo de ferramentas estável emparelhado com um prompt de sistema em mudança ainda pode armazenar as ferramentas em cache separadamente.

Exemplos Intermediários

6. Camada de Dois Breakpoints: Ferramentas e Sistema

Armazene em cache ferramentas e o prompt do sistema como dois segmentos separados e independentemente atualizáveis.

tools = [
    {
        "name": "search_docs",
        "description": "Pesquise a base de conhecimento interna." * 20,
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
        "cache_control": {"type": "ephemeral"},
    }
]
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    tools=tools,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)
print(response.usage.cache_read_input_tokens, response.usage.cache_creation_input_tokens)

• O breakpoint das ferramentas armazena em cache os esquemas das ferramentas como seu próprio segmento de prefixo.
• O breakpoint do sistema, então, armazena em cache as ferramentas + sistema como um segundo segmento, mais longo.
• Se apenas o prompt do sistema mudar, o segmento de ferramentas ainda pode acertar enquanto o segmento do sistema é regravado.
• Dois breakpoints são o teto prático para a maioria dos prompts do dia a dia - mais do que isso adiciona contabilidade sem muito benefício extra.

Relacionado: Colocando Breakpoints cache_control em Prompts do Sistema e Ferramentas - as regras completas de ordenação.

7. Criar um Pequeno Auxiliar que Registra a Eficácia do Cache

Envolva uma chamada para que cada solicitação relate sua taxa de acerto de cache.

def call_with_cache_report(client, **kwargs):
    response = client.messages.create(**kwargs)
    usage = response.usage
    total_prefix = usage.cache_read_input_tokens + usage.cache_creation_input_tokens
    hit_rate = (
        usage.cache_read_input_tokens / total_prefix if total_prefix else 0.0
    )
    print(
        f"leitura={usage.cache_read_input_tokens} "
        f"escrita={usage.cache_creation_input_tokens} "
        f"taxa_acerto={hit_rate:.0%}"
    )
    return response
 
call_with_cache_report(
    client,
    model="claude-sonnet-5",
    max_tokens=200,
    system=[
        {
            "type": "text",
            "text": long_policy_text,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)

• Centralizar essa verificação em um auxiliar torna as regressões de cache visíveis nos logs em vez de enterradas em objetos de resposta individuais.
• Uma hit_rate que cai para 0% inesperadamente é o primeiro sinal de que algo upstream mudou o prefixo.
• Este padrão escala de forma limpa para envolver todas as chamadas messages.create em uma aplicação maior.
• Considere emitir esses números para o seu sistema de métricas em vez de apenas imprimi-los.

Relacionado: Verificando Acertos de Cache com cache_read_input_tokens - uma análise mais aprofundada da criação desse tipo de verificação.

8. Combinar um Prompt do Sistema Cacheado com uma Conversa Crescente

Mantenha o prompt do sistema em cache enquanto o array de mensagens cresce turno a turno.

conversation = [{"role": "user", "content": "Qual é a sua janela de reembolso?"}]
 
def cached_turn(client, conversation, user_text):
    if user_text:
        conversation.append({"role": "user", "content": user_text})
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=300,
        system=[
            {
                "type": "text",
                "text": long_policy_text,
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=conversation,
    )
    conversation.append({"role": "assistant", "content": response.content[0].text})
    return response
 
r1 = cached_turn(client, conversation, None)
r2 = cached_turn(client, conversation, "E para itens abertos?")
print(r2.usage.cache_read_input_tokens)

• O breakpoint do prompt do sistema permanece idêntico entre os turnos, portanto, ele continua acertando o cache mesmo enquanto conversation cresce.
• Apenas o array de mensagens - que fica após o breakpoint - muda entre os turnos.
• Este é o padrão inicial para cache de agente multi-turno, coberto com mais detalhes em outra parte desta seção.
• Observe o crescimento do contexto: uma conversa de longa duração eventualmente precisa ser cortada, independentemente do cache.

Relacionado: Estratégia de Cache para Conversas de Agente Multi-Turno - posicionamento de breakpoint por turno para conversas crescentes.

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (último lançamento 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.