Colocando Breakpoints de cache_control em Prompts de Sistema e Ferramentas

Um breakpoint de cache_control apenas armazena em cache o que vem antes dele, na ordem exata em que Claude monta a requisição: ferramentas primeiro, depois o prompt do sistema e, por último, o array de mensagens.

Se essa ordem estiver errada, os breakpoints armazenarão em cache muito pouco para ter efeito, ou serão invalidados por conteúdo que nunca deveria ter estado no prefixo em cache.

Esta página explica onde colocar breakpoints, por que a ordem é importante e como sobrepor mais de um para um cache mais granular.

Resumo

Cada requisição da API Claude tem três seções lógicas que participam do prefixo em cache, sempre na mesma ordem: tools (ferramentas), depois system (sistema) e, por último, messages (mensagens).

Um breakpoint marca o fim do conteúdo que você deseja armazenar em cache, então um breakpoint na última ferramenta armazena em cache apenas as ferramentas, enquanto um breakpoint no prompt do sistema armazena em cache as ferramentas mais o sistema juntos.

O conteúdo colocado após o breakpoint final – quase sempre o final de messages – nunca é armazenado em cache e é reprocessado a cada chamada.

Acertar isso significa colocar seu conteúdo mais estável primeiro e seu conteúdo mais volátil por último, e então colocar breakpoints nas junções naturais entre eles.

Esta página mostra a estrutura da requisição, as regras de ordenação e exemplos práticos com um breakpoint e com dois breakpoints sobrepostos.

Receita

Cartão de receita de referência rápida – pronto para copiar e colar.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=500,
    tools=[
        {
            "name": "search_docs",
            "description": "Busca na base de conhecimento interna por um tópico.",
            "input_schema": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
            "cache_control": {"type": "ephemeral"},
        }
    ],
    system=[
        {
            "type": "text",
            "text": "Você é o assistente de suporte da Acme Corp. Siga o guia de tom abaixo.\n" + ("...texto do guia de tom..." * 100),
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)

Quando usar isso:

• Sua requisição inclui um prompt de sistema ou um catálogo de ferramentas que permanece o mesmo em muitas chamadas.
• Você deseja armazenar em cache ferramentas e o sistema de forma independente, porque um muda com mais frequência que o outro.
• Você está vendo cache_read_input_tokens inesperadamente baixo e suspeita da colocação do breakpoint, e não da derivação de conteúdo.
• Você está combinando o uso de ferramentas com um conjunto longo de instruções e deseja controlar exatamente o que é elegível para cache.

Exemplo Prático

import anthropic
 
client = anthropic.Anthropic()
 
REFERENCE_DOCS = "Catálogo de produtos e detalhes da política de devolução...\n" * 400
TOOL_DESCRIPTION = "Busca o pedido de um cliente por ID do pedido." * 15
 
def build_request(user_question: str) -> dict:
    """Constrói uma requisição com dois breakpoints de cache independentes:
    um após o catálogo de ferramentas, outro após o prompt do sistema.
    """
    return {
        "model": "claude-sonnet-5",
        "max_tokens": 500,
        "tools": [
            {
                "name": "lookup_order",
                "description": TOOL_DESCRIPTION,
                "input_schema": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string"}},
                    "required": ["order_id"],
                },
                # Breakpoint 1: armazena em cache apenas o catálogo de ferramentas.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        "system": [
            {
                "type": "text",
                "text": (
                    "Você é o assistente de suporte da Acme Corp.\n"
                    "Material de referência:\n" + REFERENCE_DOCS
                ),
                # Breakpoint 2: armazena em cache ferramentas + sistema juntos.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        # Tudo aqui é por requisição e nunca é armazenado em cache.
        "messages": [{"role": "user", "content": user_question}],
    }
 
client = anthropic.Anthropic()
 
r1 = client.messages.create(**build_request("Qual é a sua janela de reembolso?"))
print("chamada 1:", r1.usage.cache_creation_input_tokens, r1.usage.cache_read_input_tokens)
 
r2 = client.messages.create(**build_request("Posso rastrear o pedido nº 4471?"))
print("chamada 2:", r2.usage.cache_creation_input_tokens, r2.usage.cache_read_input_tokens)

O que isso demonstra:

• Dois breakpoints em uma única requisição: um logo após a lista de ferramentas, outro logo após o prompt do sistema.
• tools, system e messages são construídos por uma única função para que o conteúdo em cache seja garantidamente idêntico byte a byte entre as chamadas.
• Apenas a pergunta final do usuário muda entre r1 e r2, e ela corretamente fica após ambos os breakpoints, em messages.
• A segunda chamada mostra cache_read_input_tokens diferente de zero porque o prefixo de ferramentas+sistema correspondeu exatamente.

Análise Detalhada

Como Funciona

• Claude monta o prefixo efetivo em uma ordem fixa: tools (ferramentas), depois system (sistema), depois messages (mensagens), independentemente da ordem em que os argumentos de palavra-chave aparecem em sua chamada Python.
• Um bloco cache_control colocado no último elemento de tools armazena em cache tudo em tools até e incluindo esse elemento.
• Um bloco cache_control colocado em um bloco de conteúdo system armazena em cache tools (se em cache) mais system até aquele ponto, como um segmento combinado.
• Você pode marcar mais de um breakpoint em uma única requisição; cada um fecha um segmento, permitindo que você obtenha crédito de cache parcial mesmo quando apenas o segmento posterior mudou.
• Qualquer coisa após o último breakpoint – quase sempre o final de messages – é reprocessada a cada vez e nunca contribui para cache_read_input_tokens.

Onde os Breakpoints Comumente Vão

Notas de Python

# system pode ser uma string simples OU uma lista de blocos de conteúdo.
# cache_control só pode ser definido quando system é a forma de LISTA.
 
# NÃO armazenará em cache - system é uma string bruta, cache_control não é possível:
system = "Você é um assistente prestativo."
 
# ARMAZENARÁ em cache - system é uma lista de um bloco de conteúdo com cache_control:
system = [
    {"type": "text", "text": "Você é um assistente prestativo.", "cache_control": {"type": "ephemeral"}}
]

Parâmetros e Valores de Retorno

Armadilhas

• Colocar cache_control em um system de string bruta. Uma string simples system="..." não tem onde anexar cache_control. Correção: sempre use a forma de lista-de-blocos-de-conteúdo de system quando quiser cache.
• Assumir que a ordem dos argumentos em Python controla a ordem em cache. Escrever messages= antes de tools= em sua chamada de função não tem efeito na ordem lógica da requisição. Correção: lembre-se que Claude sempre avalia tools -> system -> messages, independentemente da ordem das palavras-chave em seu código.
• Colocar texto específico do usuário dentro do bloco de sistema em cache. Interpolar um nome de usuário ou ID de sessão no texto do prompt do sistema antes do breakpoint invalida o cache em cada solicitação individual. Correção: mantenha o bloco do sistema estático; coloque qualquer coisa por usuário ou por sessão em messages, após o breakpoint.
• Marcar cada ferramenta individualmente em vez de apenas a última. cache_control só precisa ir na última ferramenta da lista – ele armazena em cache tudo desde o início de tools até essa entrada. Correção: marque um breakpoint por segmento que você deseja, não um por item.
• Recriar o dicionário de esquema da ferramenta do zero a cada chamada. Mesmo dicionários Python semanticamente idênticos podem serializar de forma diferente se a ordem de inserção das chaves variar. Correção: construa o conteúdo das ferramentas e do sistema a partir de uma única constante ou função compartilhada, não de literais inline espalhados pela base de código.
• Esquecer que uma alteração no esquema da ferramenta invalida um breakpoint posterior do sistema também. Como as ferramentas vêm antes do sistema no prefixo, uma alteração no esquema da ferramenta quebra o cache em nível de sistema, mesmo que o texto do sistema em si nunca tenha mudado. Correção: trate as alterações no esquema da ferramenta como eventos que afetam o cache, não apenas alterações de texto do prompt.

Alternativas

FAQs

Relacionados

• Como o Prefix Match do Prompt Caching Realmente Funciona - o mecanismo subjacente de correspondência exata em que essa ordenação depende.
• Noções Básicas de Prompt Caching - um primeiro breakpoint de cache_control de ponta a ponta.
• Depurando Invalidadores Silenciosos de Cache em Prompts Longos - encontre o que está quebrando um breakpoint que você já colocou.
• Definindo Esquemas de Ferramentas com name, description e input_schema - como os esquemas de ferramentas são estruturados antes de você armazená-los em cache.

Versões do Stack: Escrito contra a linha de modelos Claude atual em ~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 (última versão 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.