Cache de prompt

O cache de prompt é um recurso poderoso que otimiza o uso da sua API permitindo retomar a partir de prefixos específicos em seus prompts. Esta abordagem reduz significativamente o tempo de processamento e os custos para tarefas repetitivas ou prompts com elementos consistentes.

Aqui está um exemplo de como implementar o cache de prompt com a API Messages usando um bloco cache_control:

Shell

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Você é um assistente de IA encarregado de analisar obras literárias. Seu objetivo é fornecer comentários perspicazes sobre temas, personagens e estilo de escrita.\n"
      },
      {
        "type": "text",
        "text": "<todo o conteúdo de Orgulho e Preconceito>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analise os principais temas em Orgulho e Preconceito."
      }
    ]
  }'

# Chame o modelo novamente com as mesmas entradas até o ponto de verificação do cache
curl https://api.anthropic.com/v1/messages # resto da entrada

JSON

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Neste exemplo, todo o texto de “Orgulho e Preconceito” é armazenado em cache usando o parâmetro cache_control. Isso permite a reutilização deste texto grande em múltiplas chamadas da API sem reprocessá-lo a cada vez. Alterar apenas a mensagem do usuário permite que você faça várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, levando a respostas mais rápidas e maior eficiência.

---

Como funciona o cache de prompt

Quando você envia uma solicitação com cache de prompt habilitado:

1. O sistema verifica se um prefixo de prompt, até um ponto de interrupção de cache especificado, já está em cache de uma consulta recente.
2. Se encontrado, ele usa a versão em cache, reduzindo o tempo de processamento e os custos.
3. Caso contrário, ele processa o prompt completo e armazena o prefixo em cache assim que a resposta começa.

Isso é especialmente útil para:

• Prompts com muitos exemplos
• Grandes quantidades de contexto ou informações de fundo
• Tarefas repetitivas com instruções consistentes
• Conversas longas de múltiplas rodadas

Por padrão, o cache tem uma duração de 5 minutos. O cache é atualizado sem custo adicional cada vez que o conteúdo em cache é usado.

Se você achar que 5 minutos é muito pouco, a Anthropic também oferece uma duração de cache de 1 hora.

Para mais informações, veja Duração de cache de 1 hora.

O cache de prompt armazena o prefixo completo

O cache de prompt referencia todo o prompt - tools, system e messages (nesta ordem) até e incluindo o bloco designado com cache_control.

---

Preços

O cache de prompt introduz uma nova estrutura de preços. A tabela abaixo mostra o preço por milhão de tokens para cada modelo suportado:

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.5 (deprecated)	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Haiku 3.5	$0.80 / MTok	$1 / MTok	$1.6 / MTok	$0.08 / MTok	$4 / MTok
Claude Opus 3 (deprecated)	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Haiku 3	$0.25 / MTok	$0.30 / MTok	$0.50 / MTok	$0.03 / MTok	$1.25 / MTok

A tabela acima reflete os seguintes multiplicadores de preços para cache de prompt:

• Tokens de escrita de cache de 5 minutos são 1,25 vezes o preço base dos tokens de entrada
• Tokens de escrita de cache de 1 hora são 2 vezes o preço base dos tokens de entrada
• Tokens de leitura de cache são 0,1 vezes o preço base dos tokens de entrada

---

Como implementar o cache de prompt

Modelos suportados

O cache de prompt é atualmente suportado em:

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5 (descontinuado)
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (descontinuado)

Estruturando seu prompt

Coloque conteúdo estático (definições de ferramentas, instruções do sistema, contexto, exemplos) no início do seu prompt. Marque o final do conteúdo reutilizável para cache usando o parâmetro cache_control.

Os prefixos de cache são criados na seguinte ordem: tools, system, depois messages. Esta ordem forma uma hierarquia onde cada nível se baseia nos anteriores.

Como funciona a verificação automática de prefixo

Você pode usar apenas um ponto de interrupção de cache no final do seu conteúdo estático, e o sistema encontrará automaticamente o prefixo correspondente mais longo. Veja como funciona:

• Quando você adiciona um ponto de interrupção cache_control, o sistema verifica automaticamente por acertos de cache em todos os limites de blocos de conteúdo anteriores (até aproximadamente 20 blocos antes do seu ponto de interrupção explícito)
• Se qualquer uma dessas posições anteriores corresponder ao conteúdo em cache de solicitações anteriores, o sistema usa o prefixo correspondente mais longo
• Isso significa que você não precisa de múltiplos pontos de interrupção apenas para habilitar o cache - um no final é suficiente

Quando usar múltiplos pontos de interrupção

Você pode definir até 4 pontos de interrupção de cache se quiser:

• Armazenar em cache diferentes seções que mudam em frequências diferentes (por exemplo, ferramentas raramente mudam, mas o contexto é atualizado diariamente)
• Ter mais controle sobre exatamente o que é armazenado em cache
• Garantir cache para conteúdo mais de 20 blocos antes do seu ponto de interrupção final

Limitação importante: A verificação automática de prefixo só olha para trás aproximadamente 20 blocos de conteúdo de cada ponto de interrupção explícito. Se seu prompt tiver mais de 20 blocos de conteúdo antes do seu ponto de interrupção de cache, o conteúdo anterior a isso não será verificado para acertos de cache, a menos que você adicione pontos de interrupção adicionais.

Limitações do cache

O comprimento mínimo de prompt que pode ser armazenado em cache é:

• 1024 tokens para Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (descontinuado) e Claude Opus 3 (descontinuado)
• 2048 tokens para Claude Haiku 3.5 e Claude Haiku 3

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Qualquer solicitação para armazenar em cache menos que este número de tokens será processada sem cache. Para ver se um prompt foi armazenado em cache, veja os campos de uso da resposta.

Para solicitações concorrentes, note que uma entrada de cache só fica disponível após a primeira resposta começar. Se você precisar de acertos de cache para solicitações paralelas, aguarde a primeira resposta antes de enviar solicitações subsequentes.

Atualmente, “ephemeral” é o único tipo de cache suportado, que por padrão tem uma duração de 5 minutos.

Entendendo os custos dos pontos de interrupção de cache

Os pontos de interrupção de cache em si não adicionam nenhum custo. Você só é cobrado por:

• Escritas de cache: Quando novo conteúdo é escrito no cache (25% a mais que os tokens de entrada base para TTL de 5 minutos)
• Leituras de cache: Quando conteúdo em cache é usado (10% do preço base dos tokens de entrada)
• Tokens de entrada regulares: Para qualquer conteúdo não armazenado em cache

Adicionar mais pontos de interrupção cache_control não aumenta seus custos - você ainda paga a mesma quantia baseada no que o conteúdo é realmente armazenado em cache e lido. Os pontos de interrupção simplesmente dão controle sobre quais seções podem ser armazenadas em cache independentemente.

O que pode ser armazenado em cache

A maioria dos blocos na solicitação pode ser designada para cache com cache_control. Isso inclui:

• Ferramentas: Definições de ferramentas no array tools
• Mensagens do sistema: Blocos de conteúdo no array system
• Mensagens de texto: Blocos de conteúdo no array messages.content, para turnos tanto do usuário quanto do assistente
• Imagens e Documentos: Blocos de conteúdo no array messages.content, em turnos do usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, em turnos tanto do usuário quanto do assistente

Cada um desses elementos pode ser marcado com cache_control para habilitar o cache para essa parte da solicitação.

O que não pode ser armazenado em cache

Embora a maioria dos blocos de solicitação possa ser armazenada em cache, há algumas exceções:

• Blocos de pensamento não podem ser armazenados em cache diretamente com cache_control. No entanto, blocos de pensamento PODEM ser armazenados em cache junto com outro conteúdo quando aparecem em turnos anteriores do assistente. Quando armazenados em cache desta forma, eles CONTAM como tokens de entrada quando lidos do cache.

• Sub-blocos de conteúdo (como citações) em si não podem ser armazenados em cache diretamente. Em vez disso, armazene em cache o bloco de nível superior.

  No caso de citações, os blocos de conteúdo de documento de nível superior que servem como material fonte para citações podem ser armazenados em cache. Isso permite que você use cache de prompt com citações efetivamente armazenando em cache os documentos que as citações referenciarão.

• Blocos de texto vazios não podem ser armazenados em cache.

O que invalida o cache

Modificações no conteúdo em cache podem invalidar parte ou todo o cache.

Como descrito em Estruturando seu prompt, o cache segue a hierarquia: tools → system → messages. Mudanças em cada nível invalidam esse nível e todos os níveis subsequentes.

A tabela a seguir mostra quais partes do cache são invalidadas por diferentes tipos de mudanças. ✘ indica que o cache é invalidado, enquanto ✓ indica que o cache permanece válido.

O que muda	Cache de ferramentas	Cache do sistema	Cache de mensagens	Impacto
Definições de ferramentas	✘	✘	✘	Modificar definições de ferramentas (nomes, descrições, parâmetros) invalida todo o cache
Alternância de busca na web	✓	✘	✘	Habilitar/desabilitar busca na web modifica o prompt do sistema
Alternância de citações	✓	✘	✘	Habilitar/desabilitar citações modifica o prompt do sistema
Escolha de ferramenta	✓	✓	✘	Mudanças no parâmetro tool_choice afetam apenas blocos de mensagem
Imagens	✓	✓	✘	Adicionar/remover imagens em qualquer lugar do prompt afeta blocos de mensagem
Parâmetros de pensamento	✓	✓	✘	Mudanças nas configurações de pensamento estendido (habilitar/desabilitar, orçamento) afetam blocos de mensagem
Resultados não-ferramenta passados para solicitações de pensamento estendido	✓	✓	✘	Quando resultados não-ferramenta são passados em solicitações enquanto o pensamento estendido está habilitado, todos os blocos de pensamento previamente armazenados em cache são removidos do contexto, e quaisquer mensagens no contexto que seguem esses blocos de pensamento são removidas do cache. Para mais detalhes, veja Cache com blocos de pensamento.

Rastreando performance do cache

Monitore a performance do cache usando estes campos de resposta da API, dentro de usage na resposta (ou evento message_start se streaming):

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta solicitação.
• input_tokens: Número de tokens de entrada que não foram lidos ou usados para criar um cache.

Melhores práticas para cache efetivo

Para otimizar a performance do cache de prompt:

• Armazene em cache conteúdo estável e reutilizável como instruções do sistema, informações de fundo, contextos grandes ou definições de ferramentas frequentes.
• Coloque conteúdo em cache no início do prompt para melhor performance.
• Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo que podem ser armazenadas em cache.
• Analise regularmente as taxas de acerto de cache e ajuste sua estratégia conforme necessário.

Otimizando para diferentes casos de uso

Adapte sua estratégia de cache de prompt ao seu cenário:

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos carregados.
• Assistentes de codificação: Melhore o autocompletar e Q&A de base de código mantendo seções relevantes ou uma versão resumida da base de código no prompt.
• Processamento de documentos grandes: Incorpore material completo de longa duração incluindo imagens em seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores frequentemente incluem um ou dois exemplos no prompt, mas com cache de prompt você pode obter performance ainda melhor incluindo mais de 20 exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agênticas: Melhore a performance para cenários envolvendo múltiplas chamadas de ferramentas e mudanças iterativas de código, onde cada passo tipicamente requer uma nova chamada da API.
• Converse com livros, artigos, documentação, transcrições de podcast e outro conteúdo de longa duração: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt, e deixando os usuários fazerem perguntas.

Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Certifique-se de que as seções em cache são idênticas e marcadas com cache_control nos mesmos locais entre chamadas
• Verifique se as chamadas são feitas dentro da duração do cache (5 minutos por padrão)
• Verifique se tool_choice e uso de imagem permanecem consistentes entre chamadas
• Valide que você está armazenando em cache pelo menos o número mínimo de tokens
• O sistema verifica automaticamente por acertos de cache em limites de blocos de conteúdo anteriores (até ~20 blocos antes do seu ponto de interrupção). Para prompts com mais de 20 blocos de conteúdo, você pode precisar de parâmetros cache_control adicionais mais cedo no prompt para garantir que todo o conteúdo possa ser armazenado em cache

Mudanças em tool_choice ou a presença/ausência de imagens em qualquer lugar do prompt invalidarão o cache, exigindo que uma nova entrada de cache seja criada. Para mais detalhes sobre invalidação de cache, veja O que invalida o cache.

Cache com blocos de pensamento

Ao usar pensamento estendido com cache de prompt, blocos de pensamento têm comportamento especial:

Cache automático junto com outro conteúdo: Embora blocos de pensamento não possam ser explicitamente marcados com cache_control, eles são armazenados em cache como parte do conteúdo da solicitação quando você faz chamadas subsequentes da API com resultados de ferramentas. Isso comumente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada em suas métricas de uso. Isso é importante para cálculo de custo e orçamento de tokens.

Padrões de invalidação de cache:

• O cache permanece válido quando apenas resultados de ferramentas são fornecidos como mensagens do usuário
• O cache é invalidado quando conteúdo de usuário não-resultado-de-ferramenta é adicionado, causando a remoção de todos os blocos de pensamento anteriores
• Este comportamento de cache ocorre mesmo sem marcadores cache_control explícitos

Para mais detalhes sobre invalidação de cache, veja O que invalida o cache.

Exemplo com uso de ferramenta:

Solicitação 1: Usuário: "Qual é o clima em Paris?"
Resposta: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1]

Solicitação 2: 
Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True]
Resposta: [bloco_de_pensamento_2] + [bloco de texto 2]
# Solicitação 2 armazena em cache seu conteúdo de solicitação (não a resposta)
# O cache inclui: mensagem do usuário, bloco_de_pensamento_1, bloco de uso de ferramenta 1, e resultado_ferramenta_1

Solicitação 3:
Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True], 
Assistente: [bloco_de_pensamento_2] + [bloco de texto 2], 
Usuário: [Resposta de texto, cache=True]
# Bloco de usuário não-resultado-de-ferramenta causa todos os blocos de pensamento serem ignorados
# Esta solicitação é processada como se blocos de pensamento nunca estivessem presentes

Quando um bloco de usuário não-resultado-de-ferramenta é incluído, ele designa um novo loop do assistente e todos os blocos de pensamento anteriores são removidos do contexto.

Para informações mais detalhadas, veja a documentação de pensamento estendido.

---

Armazenamento e compartilhamento de cache

• Isolamento de Organização: Caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo se usarem prompts idênticos.

• Correspondência Exata: Acertos de cache requerem segmentos de prompt 100% idênticos, incluindo todo texto e imagens até e incluindo o bloco marcado com controle de cache.

• Geração de Tokens de Saída: O cache de prompt não tem efeito na geração de tokens de saída. A resposta que você recebe será idêntica ao que você obteria se o cache de prompt não fosse usado.

---

Duração de cache de 1 hora

Se você achar que 5 minutos é muito pouco, a Anthropic também oferece uma duração de cache de 1 hora.

Para usar o cache estendido, inclua ttl na definição cache_control assim:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

A resposta incluirá informações detalhadas de cache como o seguinte:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

Note que o campo atual cache_creation_input_tokens é igual à soma dos valores no objeto cache_creation.

Quando usar o cache de 1 hora

Se você tem prompts que são usados em uma cadência regular (ou seja, prompts do sistema que são usados mais frequentemente que a cada 5 minutos), continue a usar o cache de 5 minutos, já que este continuará a ser atualizado sem custo adicional.

O cache de 1 hora é melhor usado nos seguintes cenários:

• Quando você tem prompts que provavelmente são usados menos frequentemente que 5 minutos, mas mais frequentemente que a cada hora. Por exemplo, quando um agente lateral agêntico levará mais de 5 minutos, ou ao armazenar uma conversa de chat longa com um usuário e você geralmente espera que esse usuário possa não responder nos próximos 5 minutos.
• Quando a latência é importante e seus prompts de acompanhamento podem ser enviados além de 5 minutos.
• Quando você quer melhorar sua utilização de limite de taxa, já que acertos de cache não são deduzidos do seu limite de taxa.

O cache de 5 minutos e 1 hora se comportam da mesma forma com relação à latência. Você geralmente verá tempo melhorado até o primeiro token para documentos longos.

Misturando diferentes TTLs

Você pode usar controles de cache de 1 hora e 5 minutos na mesma solicitação, mas com uma restrição importante: Entradas de cache com TTL mais longo devem aparecer antes de TTLs mais curtos (ou seja, uma entrada de cache de 1 hora deve aparecer antes de qualquer entrada de cache de 5 minutos).

Ao misturar TTLs, determinamos três localizações de cobrança em seu prompt:

1. Posição A: A contagem de tokens no acerto de cache mais alto (ou 0 se não houver acertos).
2. Posição B: A contagem de tokens no bloco cache_control de 1 hora mais alto após A (ou igual a A se nenhum existir).
3. Posição C: A contagem de tokens no último bloco cache_control.

Se B e/ou C forem maiores que A, eles necessariamente serão falhas de cache, porque A é o acerto de cache mais alto.

Você será cobrado por:

1. Tokens de leitura de cache para A.
2. Tokens de escrita de cache de 1 hora para (B - A).
3. Tokens de escrita de cache de 5 minutos para (C - B).

Aqui estão 3 exemplos. Isso representa os tokens de entrada de 3 solicitações, cada uma das quais tem diferentes acertos e falhas de cache. Cada uma tem um preço calculado diferente, mostrado nas caixas coloridas, como resultado.

---

Exemplos de cache de prompt

Para ajudá-lo a começar com cache de prompt, preparamos um cookbook de cache de prompt com exemplos detalhados e melhores práticas.

Abaixo, incluímos vários trechos de código que mostram vários padrões de cache de prompt. Estes exemplos demonstram como implementar cache em diferentes cenários, ajudando você a entender as aplicações práticas deste recurso:

Exemplo de cache de contexto grande

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Você é um assistente de IA encarregado de analisar documentos legais."
        },
        {
            "type": "text",
            "text": "Aqui está o texto completo de um acordo legal complexo: [Insira o texto completo de um acordo legal de 50 páginas aqui]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Quais são os principais termos e condições neste acordo?"
        }
    ]
}'

Este exemplo demonstra o uso básico de cache de prompt, armazenando em cache o texto completo do acordo legal como um prefixo enquanto mantém a instrução do usuário não armazenada em cache.

Para a primeira solicitação:

• input_tokens: Número de tokens apenas na mensagem do usuário
• cache_creation_input_tokens: Número de tokens em toda a mensagem do sistema, incluindo o documento legal
• cache_read_input_tokens: 0 (nenhum acerto de cache na primeira solicitação)

Para solicitações subsequentes dentro da duração do cache:

• input_tokens: Número de tokens apenas na mensagem do usuário
• cache_creation_input_tokens: 0 (nenhuma nova criação de cache)
• cache_read_input_tokens: Número de tokens em toda a mensagem do sistema em cache

Cache de definições de ferramentas

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obter o clima atual em um local específico",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "A cidade e estado, ex. São Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "A unidade de temperatura, celsius ou fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # muitas mais ferramentas
        {
            "name": "get_time",
            "description": "Obter a hora atual em um fuso horário específico",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "O nome do fuso horário IANA, ex. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Qual é o clima e a hora em Nova York?"
        }
    ]
}'

Neste exemplo, demonstramos o cache de definições de ferramentas.

O parâmetro cache_control é colocado na ferramenta final (get_time) para designar todas as ferramentas como parte do prefixo estático.

Isso significa que todas as definições de ferramentas, incluindo get_weather e quaisquer outras ferramentas definidas antes de get_time, serão armazenadas em cache como um único prefixo.

Esta abordagem é útil quando você tem um conjunto consistente de ferramentas que deseja reutilizar em múltiplas solicitações sem reprocessá-las a cada vez.

Para a primeira solicitação:

• input_tokens: Número de tokens na mensagem do usuário
• cache_creation_input_tokens: Número de tokens em todas as definições de ferramentas e prompt do sistema
• cache_read_input_tokens: 0 (nenhum acerto de cache na primeira solicitação)

Para solicitações subsequentes dentro da duração do cache:

• input_tokens: Número de tokens na mensagem do usuário
• cache_creation_input_tokens: 0 (nenhuma nova criação de cache)
• cache_read_input_tokens: Número de tokens em todas as definições de ferramentas em cache e prompt do sistema

Continuando uma conversa de múltiplas rodadas

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...prompt longo do sistema",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Olá, você pode me contar mais sobre o sistema solar?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certamente! O sistema solar é a coleção de corpos celestes que orbitam nosso Sol. Consiste em oito planetas, numerosas luas, asteroides, cometas e outros objetos. Os planetas, em ordem do mais próximo ao mais distante do Sol, são: Mercúrio, Vênus, Terra, Marte, Júpiter, Saturno, Urano e Netuno. Cada planeta tem suas próprias características e recursos ún icos. Há algum aspecto específico do sistema solar sobre o qual você gostaria de saber mais?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Bom saber."
                },
                {
                    "type": "text",
                    "text": "Me conte mais sobre Marte.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Neste exemplo, demonstramos como usar cache de prompt em uma conversa de múltiplas rodadas.

Durante cada rodada, marcamos o bloco final da mensagem final com cache_control para que a conversa possa ser armazenada em cache incrementalmente. O sistema automaticamente procurará e usará o prefixo mais longo previamente armazenado em cache para mensagens de acompanhamento. Ou seja, blocos que foram previamente marcados com um bloco cache_control posteriormente não são marcados com isso, mas ainda serão considerados um acerto de cache (e também uma atualização de cache!) se forem atingidos dentro de 5 minutos.

Além disso, note que o parâmetro cache_control é colocado na mensagem do sistema. Isso é para garantir que se isso for removido do cache (após não ser usado por mais de 5 minutos), será adicionado de volta ao cache na próxima solicitação.

Esta abordagem é útil para manter contexto em conversas em andamento sem processar repetidamente a mesma informação.

Quando isso é configurado adequadamente, você deve ver o seguinte na resposta de uso de cada solicitação:

• input_tokens: Número de tokens na nova mensagem do usuário (será mínimo)
• cache_creation_input_tokens: Número de tokens nas novas rodadas do assistente e usuário
• cache_read_input_tokens: Número de tokens na conversa até a rodada anterior

Juntando tudo: Múltiplos pontos de interrupção de cache

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Pesquisar na base de conhecimento",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Consulta de pesquisa"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Recuperar um documento específico por ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "ID do documento"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Você é um assistente de pesquisa útil com acesso a uma base de conhecimento de documentos.\n\n# Instruções\n- Sempre pesquise por documentos relevantes antes de responder\n- Forneça citações para suas fontes\n- Seja objetivo e preciso em suas respostas\n- Se múltiplos documentos contêm informações relevantes, sintetize-os\n- Reconheça quando informações não estão disponíveis na base de conhecimento",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Contexto da Base de Conhecimento\n\nAqui estão os documentos relevantes para esta conversa:\n\n## Documento 1: Visão Geral do Sistema Solar\nO sistema solar consiste no Sol e todos os objetos que o orbitam...\n\n## Documento 2: Características Planetárias\nCada planeta tem características únicas. Mercúrio é o menor planeta...\n\n## Documento 3: Exploração de Marte\nMarte tem sido um alvo de exploração por décadas...\n\n[Documentos adicionais...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Você pode pesquisar informações sobre rovers de Marte?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "rovers de Marte"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Encontrados 3 documentos relevantes: Documento 3 (Exploração de Marte), Documento 7 (Tecnologia de Rover), Documento 9 (Histórico de Missões)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Encontrei 3 documentos relevantes sobre rovers de Marte. Deixe-me obter mais detalhes do documento de Exploração de Marte."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Sim, por favor me conte sobre o rover Perseverance especificamente.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Este exemplo abrangente demonstra como usar todos os 4 pontos de interrupção de cache disponíveis para otimizar diferentes partes do seu prompt:

1. Cache de ferramentas (ponto de interrupção de cache 1): O parâmetro cache_control na última definição de ferramenta armazena em cache todas as definições de ferramentas.

2. Cache de instruções reutilizáveis (ponto de interrupção de cache 2): As instruções estáticas no prompt do sistema são armazenadas em cache separadamente. Essas instruções raramente mudam entre solicitações.

3. Cache de contexto RAG (ponto de interrupção de cache 3): Os documentos da base de conhecimento são armazenados em cache independentemente, permitindo que você atualize os documentos RAG sem invalidar o cache de ferramentas ou instruções.

4. Cache de histórico de conversa (ponto de interrupção de cache 4): A resposta do assistente é marcada com cache_control para habilitar cache incremental da conversa conforme ela progride.

Esta abordagem fornece máxima flexibilidade:

• Se você atualizar apenas a mensagem final do usuário, todos os quatro segmentos de cache são reutilizados
• Se você atualizar os documentos RAG mas mantiver as mesmas ferramentas e instruções, os dois primeiros segmentos de cache são reutilizados
• Se você mudar a conversa mas mantiver as mesmas ferramentas, instruções e documentos, os três primeiros segmentos são reutilizados
• Cada ponto de interrupção de cache pode ser invalidado independentemente baseado no que muda em sua aplicação

Para a primeira solicitação:

• input_tokens: Tokens na mensagem final do usuário
• cache_creation_input_tokens: Tokens em todos os segmentos em cache (ferramentas + instruções + documentos RAG + histórico de conversa)
• cache_read_input_tokens: 0 (nenhum acerto de cache)

Para solicitações subsequentes com apenas uma nova mensagem do usuário:

• input_tokens: Tokens apenas na nova mensagem do usuário
• cache_creation_input_tokens: Quaisquer novos tokens adicionados ao histórico de conversa
• cache_read_input_tokens: Todos os tokens previamente armazenados em cache (ferramentas + instruções + documentos RAG + conversa anterior)

Este padrão é especialmente poderoso para:

• Aplicações RAG com contextos de documentos grandes
• Sistemas de agentes que usam múltiplas ferramentas
• Conversas de longa duração que precisam manter contexto
• Aplicações que precisam otimizar diferentes partes do prompt independentemente

---

FAQ

Preciso de múltiplos pontos de interrupção de cache ou um no final é suficiente?

Na maioria dos casos, um único ponto de interrupção de cache no final do seu conteúdo estático é suficiente. O sistema verifica automaticamente por acertos de cache em todos os limites de blocos de conteúdo anteriores (até 20 blocos antes do seu ponto de interrupção) e usa o prefixo correspondente mais longo.

Você só precisa de múltiplos pontos de interrupção se:

• Você tem mais de 20 blocos de conteúdo antes do seu ponto de cache desejado
• Você quer armazenar em cache seções que atualizam em frequências diferentes independentemente
• Você precisa de controle explícito sobre o que é armazenado em cache para otimização de custo

Exemplo: Se você tem instruções do sistema (raramente mudam) e contexto RAG (muda diariamente), você pode usar dois pontos de interrupção para armazená-los em cache separadamente.

Pontos de interrupção de cache adicionam custo extra?

Não, pontos de interrupção de cache em si são gratuitos. Você só paga por:

• Escrever conteúdo no cache (25% a mais que tokens de entrada base para TTL de 5 minutos)
• Ler do cache (10% do preço base dos tokens de entrada)
• Tokens de entrada regulares para conteúdo não armazenado em cache

O número de pontos de interrupção não afeta o preço - apenas a quantidade de conteúdo armazenado em cache e lido importa.

Qual é a duração do cache?

A duração mínima padrão do cache (TTL) é de 5 minutos. Esta duração é atualizada cada vez que o conteúdo em cache é usado.

Se você achar que 5 minutos é muito pouco, a Anthropic também oferece um TTL de cache de 1 hora.

Quantos pontos de interrupção de cache posso usar?

Você pode definir até 4 pontos de interrupção de cache (usando parâmetros cache_control) em seu prompt.

O cache de prompt está disponível para todos os modelos?

Não, o cache de prompt está atualmente disponível apenas para Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (descontinuado), Claude Haiku 3.5, Claude Haiku 3, e Claude Opus 3 (descontinuado).

Como o cache de prompt funciona com pensamento estendido?

Prompts do sistema e ferramentas em cache serão reutilizados quando parâmetros de pensamento mudarem. No entanto, mudanças de pensamento (habilitar/desabilitar ou mudanças de orçamento) invalidarão prefixos de prompt previamente armazenados em cache com conteúdo de mensagens.

Para mais detalhes sobre invalidação de cache, veja O que invalida o cache.

Para mais sobre pensamento estendido, incluindo sua interação com uso de ferramentas e cache de prompt, veja a documentação de pensamento estendido.

Como habilito o cache de prompt?

Para habilitar o cache de prompt, inclua pelo menos um ponto de interrupção cache_control em sua solicitação da API.

Posso usar cache de prompt com outros recursos da API?

Sim, o cache de prompt pode ser usado junto com outros recursos da API como uso de ferramentas e capacidades de visão. No entanto, mudar se há imagens em um prompt ou modificar configurações de uso de ferramentas quebrará o cache.

Para mais detalhes sobre invalidação de cache, veja O que invalida o cache.

Como o cache de prompt afeta o preço?

O cache de prompt introduz uma nova estrutura de preços onde escritas de cache custam 25% a mais que tokens de entrada base, enquanto acertos de cache custam apenas 10% do preço base dos tokens de entrada.

Posso limpar manualmente o cache?

Atualmente, não há como limpar manualmente o cache. Prefixos em cache expiram automaticamente após um mínimo de 5 minutos de inatividade.

Como posso rastrear a efetividade da minha estratégia de cache?

Você pode monitorar a performance do cache usando os campos cache_creation_input_tokens e cache_read_input_tokens na resposta da API.

O que pode quebrar o cache?

Veja O que invalida o cache para mais detalhes sobre invalidação de cache, incluindo uma lista de mudanças que requerem criar uma nova entrada de cache.

Como o cache de prompt lida com privacidade e separação de dados?

O cache de prompt é projetado com medidas fortes de privacidade e separação de dados:

1. Chaves de cache são geradas usando um hash criptográfico dos prompts até o ponto de controle de cache. Isso significa que apenas solicitações com prompts idênticos podem acessar um cache específico.

2. Caches são específicos da organização. Usuários dentro da mesma organização podem acessar o mesmo cache se usarem prompts idênticos, mas caches não são compartilhados entre organizações diferentes, mesmo para prompts idênticos.

3. O mecanismo de cache é projetado para manter a integridade e privacidade de cada conversa ou contexto único.

4. É seguro usar cache_control em qualquer lugar em seus prompts. Para eficiência de custo, é melhor excluir partes altamente variáveis (ex., entrada arbitrária do usuário) do cache.

Essas medidas garantem que o cache de prompt mantenha privacidade e segurança de dados enquanto oferece benefícios de performance.

Posso usar cache de prompt com a API Batches?

Sim, é possível usar cache de prompt com suas solicitações da API Batches. No entanto, porque solicitações de lote assíncronas podem ser processadas concorrentemente e em qualquer ordem, acertos de cache são fornecidos com base no melhor esforço.

O cache de 1 hora pode ajudar a melhorar seus acertos de cache. A maneira mais eficiente em termos de custo de usá-lo é a seguinte:

• Colete um conjunto de solicitações de mensagem que têm um prefixo compartilhado.
• Envie uma solicitação de lote com apenas uma única solicitação que tem esse prefixo compartilhado e um bloco de cache de 1 hora. Isso será escrito no cache de 1 hora.
• Assim que isso estiver completo, envie o resto das solicitações. Você terá que monitorar o trabalho para saber quando ele é concluído.

Isso é tipicamente melhor que usar o cache de 5 minutos simplesmente porque é comum que solicitações de lote levem entre 5 minutos e 1 hora para completar. Estamos considerando maneiras de melhorar essas taxas de acerto de cache e tornar esse processo mais direto.

Por que estou vendo o erro `AttributeError: 'Beta' object has no attribute 'prompt_caching'` em Python?

Este erro tipicamente aparece quando você atualizou seu SDK ou está usando exemplos de código desatualizados. O cache de prompt agora está geralmente disponível, então você não precisa mais do prefixo beta. Em vez de:

Python

python client.beta.prompt_caching.messages.create(...)

Simplesmente use:

Python

python client.messages.create(...)

Por que estou vendo 'TypeError: Cannot read properties of undefined (reading 'messages')'?

Este erro tipicamente aparece quando você atualizou seu SDK ou está usando exemplos de código desatualizados. O cache de prompt agora está geralmente disponível, então você não precisa mais do prefixo beta. Em vez de:

TypeScript

client.beta.promptCaching.messages.create(...)

Simplesmente use:

client.messages.create(...)