6 de mar. de 2026

Estratégias de Cache para Agentes de IA: Reduzindo Custos Sem Abrir Mão da Qualidade

Estratégias de Cache para Agentes de IA: Reduzindo Custos Sem Abrir Mão da Qualidade

Seu agente de pesquisa executa 50 tarefas por dia. Cada tarefa começa com o mesmo prompt de sistema de 3.000 tokens, as mesmas definições de ferramentas de 2.500 tokens e a mesma base de conhecimento de 5.000 tokens. São 10.500 tokens repetidos 50 vezes — 525.000 tokens por dia que o modelo lê de forma idêntica a cada vez. Com o preço padrão, você está pagando para processar o mesmo conteúdo repetidamente.

Cache é a otimização de menor esforço e maior impacto para agentes em produção. Somente o cache de prompts pode reduzir os custos de tokens de entrada em 90% para conteúdo cacheado. Combinado com o cache de resultados de ferramentas, você pode frequentemente cortar os custos totais do agente pela metade — sem sacrificar qualidade, precisão ou flexibilidade.

Neste artigo, você aprenderá três camadas de cache para agentes — cache de prompts, cache de resultados de ferramentas e memoização de respostas — com padrões de implementação usando a API da Claude e uma análise de custos clara para orientar suas decisões.

Seção 1: Anatomia dos Custos de um Agente

Antes de otimizar, você precisa entender onde seus tokens realmente estão sendo consumidos. Vamos detalhar um fluxo de trabalho agêntico típico.

Distribuição de Tokens por Turno

Em uma arquitetura de agente padrão, cada chamada de API ao modelo inclui:

Componente	Tokens Aprox.	Repetido?
Prompt de sistema	~1.500	A cada turno
Definições de ferramentas	~2.000	A cada turno
Base de conhecimento / contexto	~3.000	A cada turno
Histórico de conversa	Crescente	Acumula
Resultados de ferramentas	~500 médio	Por chamada de ferramenta

A sobrecarga estática — prompt de sistema, definições de ferramentas e base de conhecimento — totaliza aproximadamente 6.500 tokens por turno, e é idêntica em todas as chamadas.

O Problema do Custo Composto

Agentes não fazem uma única chamada de API. Eles executam em loop. Uma execução típica de agente com 15 etapas se parece com isso:

Sem cache:

Cada uma das 15 etapas envia o contexto completo. Assumindo que o histórico de conversa cresce em ~300 tokens por etapa em média:

Tokens estáticos por etapa: 6.500
Total de tokens estáticos em 15 etapas: 97.500
Tokens de histórico de conversa (cumulativo): ~33.750
Tokens de resultados de ferramentas: ~7.500
Total de tokens de entrada: ~138.750

Com o preço de entrada do Claude Sonnet de $3 por milhão de tokens, isso equivale a aproximadamente $0,42 por tarefa. Execute 50 tarefas por dia e você terá $21/dia — apenas em tokens de entrada.

Com cache de prompts:

Os tokens cacheados são cobrados a $0,30 por milhão para leituras de cache (90% de desconto). Se você cachear os 6.500 tokens estáticos:

Leituras de tokens cacheados em 15 etapas: 97.500 tokens × $0,30/M = $0,029
Tokens não cacheados permanecem no preço padrão: ~41.250 × $3/M = $0,124
Gravação no cache (primeira etapa): 6.500 × $3,75/M = $0,024
Custo total de entrada: ~$0,18 por tarefa

Isso representa uma redução de 57% apenas com cache. Em 50 tarefas por dia, você economiza mais de $12/dia — aproximadamente $360/mês — com mudanças mínimas no código.

Seção 2: Cache de Prompts com Claude

A API de cache de prompts da Claude é a otimização de maior impacto que você pode aplicar a fluxos de trabalho agênticos. Ela permite que você diga à API “essa parte do meu prompt não mudou — reutilize a computação cacheada.”

Como Funciona o Cache de Prompts

Quando você envia uma requisição com cache habilitado, a infraestrutura da Anthropic:

Verifica se existe uma versão cacheada do prefixo marcado
Em caso de cache miss: Processa o prompt completo, cacheia o prefixo e cobra uma taxa de gravação no cache (25% acima do preço padrão de entrada)
Em caso de cache hit: Reutiliza a computação cacheada, cobrando apenas a taxa de leitura do cache (90% de desconto em relação ao preço padrão de entrada)

O cache tem um TTL de 5 minutos (Time to Live — a duração antes de os dados cacheados expirarem). Cada cache hit reinicia o TTL, então agentes ativos mantêm seu cache ativo naturalmente. Processos em lote com intervalos superiores a 5 minutos entre chamadas incorrerão em custos de gravação no cache com mais frequência.

O Que Cachear

Nem tudo pode ou deve ser cacheado. Cachei prefixos estáveis e repetidos:

Prompts de sistema — Quase sempre idênticos entre execuções. Cachei estes primeiro.
Definições de ferramentas — Seus esquemas de ferramentas raramente mudam entre chamadas.
Bases de conhecimento estáticas — Documentos de referência, diretrizes, políticas.
Prefixos de conversa — Para conversas com múltiplos turnos, cachei os turnos anteriores que não mudarão.

Restrições importantes:

O cache é baseado em prefixo — você só pode cachear conteúdo a partir do início do prompt, em ordem. Você não pode cachear uma seção no meio enquanto deixa seções anteriores sem cache.
Há um comprimento mínimo cacheável de 1.024 tokens para Claude Sonnet e Haiku (2.048 para Opus).
Você pode definir até 4 pontos de interrupção de cache em uma única requisição.

Implementação

Aqui está um exemplo completo mostrando a configuração de um agente com cache de prompts:

Antes (sem cache):

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a research assistant specializing in market analysis.
You have access to tools for searching databases, reading files, and performing
calculations. Always cite your sources and provide confidence levels for your
findings. [... detailed instructions totaling ~1,500 tokens ...]"""

TOOLS = [
    {
        "name": "search_database",
        "description": "Search the company database for market data, competitor info, or financial records.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "database": {"type": "string", "enum": ["market", "competitors", "financial"]},
                "limit": {"type": "integer", "description": "Max results", "default": 10}
            },
            "required": ["query", "database"]
        }
    },
    {
        "name": "read_file",
        "description": "Read the contents of a research file.",
        "input_schema": {
            "type": "object",
            "properties": {
                "file_path": {"type": "string", "description": "Path to the file"}
            },
            "required": ["file_path"]
        }
    },
    # ... more tools totaling ~2,000 tokens in definitions
]

KNOWLEDGE_BASE = """## Company Policies and Guidelines
[... reference material totaling ~3,000 tokens ...]"""

def run_agent(user_query: str):
    messages = [{"role": "user", "content": user_query}]

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        system=f"{SYSTEM_PROMPT}\n\n{KNOWLEDGE_BASE}",
        tools=TOOLS,
        messages=messages,
    )
    # Log token usage
    print(f"Input tokens: {response.usage.input_tokens}")
    return response

Depois (com cache de prompts):

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a research assistant specializing in market analysis.
You have access to tools for searching databases, reading files, and performing
calculations. Always cite your sources and provide confidence levels for your
findings. [... detailed instructions totaling ~1,500 tokens ...]"""

KNOWLEDGE_BASE = """## Company Policies and Guidelines
[... reference material totaling ~3,000 tokens ...]"""

TOOLS = [
    {
        "name": "search_database",
        "description": "Search the company database for market data, competitor info, or financial records.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "database": {"type": "string", "enum": ["market", "competitors", "financial"]},
                "limit": {"type": "integer", "description": "Max results", "default": 10}
            },
            "required": ["query", "database"]
        }
    },
    {
        "name": "read_file",
        "description": "Read the contents of a research file.",
        "input_schema": {
            "type": "object",
            "properties": {
                "file_path": {"type": "string", "description": "Path to the file"}
            },
            "required": ["file_path"]
        },
        "cache_control": {"type": "ephemeral"}  # Cache breakpoint after tools
    },
]

def run_agent_cached(user_query: str):
    messages = [{"role": "user", "content": user_query}]

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        system=[
            {
                "type": "text",
                "text": SYSTEM_PROMPT,
            },
            {
                "type": "text",
                "text": KNOWLEDGE_BASE,
                "cache_control": {"type": "ephemeral"},  # Cache breakpoint
            },
        ],
        tools=TOOLS,
        messages=messages,
    )
    # Log token usage — now includes cache metrics
    usage = response.usage
    print(f"Input tokens: {usage.input_tokens}")
    print(f"Cache read tokens: {usage.cache_read_input_tokens}")
    print(f"Cache creation tokens: {usage.cache_creation_input_tokens}")
    return response

As principais mudanças:

O parâmetro system torna-se uma lista de blocos de conteúdo (em vez de uma string simples) para que você possa anexar cache_control a blocos específicos.
Adicione "cache_control": {"type": "ephemeral"} nos pontos de interrupção desejados.
A última definição de ferramenta recebe um bloco cache_control para cachear também todas as definições de ferramentas.
Monitore os novos campos cache_read_input_tokens e cache_creation_input_tokens

Estratégias de Cache para Agentes de IA: Reduzindo Custos Sem Abrir Mão da Qualidade

Estratégias de Cache para Agentes de IA: Reduzindo Custos Sem Abrir Mão da Qualidade

Seção 1: Anatomia dos Custos de um Agente

Distribuição de Tokens por Turno

O Problema do Custo Composto

Seção 2: Cache de Prompts com Claude

Como Funciona o Cache de Prompts

O Que Cachear

Implementação

Artigos Relacionados