Como Reduzir Custos de Tokens de Agentes via CLI (Guia 2026)

Um agente de codificação CLI se sente livre até a fatura chegar. Você aponta Claude Code ou Codex para um repositório, pede para refatorar um módulo, e dez minutos depois ele leu quarenta arquivos, executou o pacote de testes três vezes e queimou seis dígitos de tokens em contexto que você nunca precisou que ele visse. Multiplique isso por uma equipe de oito engenheiros executando agentes o dia todo, e a conta deixa de ser um erro de arredondamento. O gasto com tokens em agentes de codificação é principalmente desperdício, e a maior parte desse desperdício pode ser corrigida pela linha de comando sem mudar modelos ou aceitar uma saída pior.

TL;DR

Reduza os custos de tokens do agente cortando o contexto antes que ele chegue ao modelo: defina o conjunto de trabalho, mantenha os arquivos de memória curtos e compacte sessões longas. Ative o cache de prompts para prefixos estáveis (cerca de 90% de desconto em leituras repetidas). Encaminhe subtarefas baratas para um modelo pequeno. Limite a saída da ferramenta. Meça o custo por execução para saber o que realmente mudou.

Introdução

A dor aparece de duas formas. Ou você atinge uma parede no meio da tarefa porque estourou um limite semanal ou de sessão, ou a fatura mensal da API chega e alguém pergunta por que um “assistente de IA” custa mais do que um contratado júnior. Ambos vêm da mesma causa raiz: agentes CLI são famintos por tokens por padrão. Eles leem arquivos inteiros quando precisam de dez linhas, repetem a conversa inteira a cada turno, despejam a saída bruta do comando de volta ao contexto e reenviam o mesmo prompt do sistema e mapa do repositório milhares de vezes por dia.

Nada disso é inerente ao trabalho. Uma refatoração que realmente precisa raciocinar sobre 2.000 tokens de código não precisa de 180.000 tokens de contexto para fazê-lo. A lacuna entre esses dois números é sua economia, e quase tudo é recuperável com flags, arquivos de configuração e hábitos que você pode adotar hoje.

Este guia detalha onde os tokens realmente vão em uma execução de agente CLI, e então oferece táticas concretas para cortar cada parte: higiene do contexto e arquivos de memória, cache de prompts, roteamento de modelos, corte de saída e recuperação de ferramentas, e medição do custo por execução para que as economias sejam reais e não um palpite. Os exemplos assumem Claude Code e Codex, mas a mecânica se aplica a qualquer agente que se comunica com uma API cobrada por tokens.

Um custo adjacente que vale a pena mencionar cedo: muito do gasto de tokens do agente é depuração. Um agente que chama uma API interna instável tentará novamente, lerá corpos de erro, relerá documentos e entrará em loop, com cada iteração pagando o preço total em tokens.

Para onde os tokens realmente vão em uma execução de agente CLI

Antes de otimizar, você precisa de um modelo mental da conta. Uma única "virada" do agente envia uma carga de entrada para o modelo e recebe uma carga de saída de volta. Você paga por ambos, e na maioria dos provedores, a saída custa de três a seis vezes mais por token do que a entrada. Para uma família de modelos de ponta em meados de 2026, a entrada custa cerca de US$ 3 por milhão de tokens e a saída cerca de US$ 15; um modelo mais barato da mesma família custa aproximadamente US$ 1 de entrada e US$ 5 de saída. Considere esses valores como ilustrativos, não como cotações; verifique as páginas de preços atuais, pois os provedores os revisam. O ponto estrutural se mantém independentemente dos números exatos: a saída é cara, e o volume de entrada é o que inflaciona.

Aqui está o que preenche a carga de entrada em uma execução típica:

• Prompt do sistema e definições de ferramentas. As instruções do agente mais o esquema JSON de cada ferramenta. Fixo por turno, frequentemente de 5.000 a 15.000 tokens, reenviado a cada turno.
• Arquivos de memória e projeto. Coisas como CLAUDE.md, convenções de repositório e instruções persistentes. Carregados a cada turno, sejam relevantes ou não.
• Histórico da conversa. Cada mensagem anterior do usuário, resposta do modelo, chamada de ferramenta e resultado da ferramenta, reproduzidos na íntegra a cada turno. Isso cresce sem limites e geralmente é o maior item em uma sessão longa.
• Conteúdo de arquivo recuperado. Arquivos que o agente leu. Uma única leitura (Read) de um arquivo de 1.200 linhas equivale a aproximadamente 12.000 a 18.000 tokens, e os agentes adoram ler arquivos inteiros.
• Saída da ferramenta. Logs do executor de testes, ruído de npm install, git diff de um arquivo lock gerado, rastreamentos de pilha. Bruto e verboso por padrão.

A carga de saída é o raciocínio, edições de código e explicações do modelo. Menor que a entrada na maioria das execuções, mas com o preço mais alto por token, então um comportamento verboso como "deixe-me explicar meu plano em seis parágrafos" é custoso.

O fato mais importante: o histórico da conversa é reproduzido a cada turno. Uma sessão de 30 turnos não custa 30 vezes um turno. É mais próximo da soma de um prefixo crescente, então os turnos posteriores carregam o peso total de tudo o que veio antes deles. É por isso que uma sessão longa e divagante é a coisa mais cara que você pode fazer, e por que as táticas abaixo visam desproporcionalmente o contexto que é reenviado.

Se você quiser uma análise mais aprofundada de como o registro de sessão e limite funciona na prática, a explicação em como a janela de tokens do Claude Code é reiniciada é um companheiro útil para esta seção; ela explica por que uma sessão que "parece curta" ainda pode esgotar um orçamento.

Higiene do contexto e arquivos de memória

O token mais barato é aquele que você nunca envia. A higiene do contexto é o hábito de maior impacto porque reduz a carga de entrada em cada turno para o restante da sessão.

Defina o conjunto de trabalho antes de começar. Não abra um agente na raiz do repositório e diga "refatore a lógica de faturamento". Ele se arrastará. Em vez disso, diga exatamente quais arquivos importam:

# Em vez de um prompt vago que dispara uma exploração ampla:
claude "refatorar a lógica de repetição para usar retrocesso exponencial,
apenas em src/payments/retry.ts e seu arquivo de teste"

Nomear os arquivos impede que o agente leia vinte candidatos para encontrar os dois que importam. Se você precisa deixá-lo explorar, aponte-o para um diretório, não para a raiz.

Mantenha os arquivos de memória curtos e estáveis. Um arquivo CLAUDE.md (ou arquivo de memória de projeto equivalente) é carregado no contexto a cada turno. As equipes o tratam como uma wiki e o deixam crescer para 4.000 tokens de prosa de integração. Com, digamos, 50 turnos por dia em 8 engenheiros, um arquivo de memória inchado é reenviado centenas de vezes diariamente sem nenhum benefício marginal. Audite-o:

# Verificação aproximada de tokens em seu arquivo de memória (chars / 4 é uma estimativa decente):
wc -c CLAUDE.md | awk '{print "≈", int($1/4), "tokens por turno"}'

Procure um arquivo conciso: comandos de build/teste, convenções rígidas e ponteiros para onde a documentação mais detalhada reside, não os próprios documentos. Se uma seção é relevante apenas para uma tarefa por mês, ela não pertence ao arquivo sempre carregado. Mova-a para um documento que o agente lê sob demanda.

Compacte ou redefina sessões longas. Quando uma sessão já cumpriu seu propósito e você está se movendo para uma tarefa não relacionada, não continue digitando no mesmo contexto. Cada novo turno agora arrasta toda a transcrição antiga. Use o comando de compactação ou limpeza do agente:

# No Claude Code, quando a conversa fica longa:
/compact     # resume o histórico em um digest curto, descarta a transcrição bruta
# ou, para uma quebra limpa em uma nova tarefa:
/clear       # começa do zero; o contexto antigo não é mais reenviado

/compact normalmente substitui dezenas de milhares de tokens de histórico bruto por um resumo de um décimo do tamanho, e esse prefixo menor é então o que cada turno subsequente carrega. A disciplina é simples: uma tarefa lógica por sessão, compactar ou limpar entre as tarefas. Os padrões de fluxo de trabalho em Fluxos de trabalho do Claude Code dependem fortemente desse hábito de escopo, e vale a pena adotá-lo por completo.

Use um arquivo de ignorar projeto. Mantenha artefatos gerados, arquivos lock, saída de build e dependências empacotadas fora do alcance do agente. Se o agente nunca vê dist/ ou node_modules/, ele nunca gasta tokens lendo ou comparando-os. A maioria dos agentes respeita um arquivo de ignorar; configure-o uma vez e as economias serão permanentes.

Cache de prompts: pare de pagar o preço total pelo mesmo prefixo

Esta é a maior alavanca para execuções repetidas, e é mecânica em vez de comportamental. O cache de prompts permite que o provedor armazene um prefixo da sua solicitação (ferramentas, prompt do sistema, contexto estável) para que solicitações subsequentes que compartilham esse prefixo o leiam de volta com um desconto acentuado, em vez de reprocessá-lo.

A economia, conforme a documentação de cache de prompts da Anthropic: uma gravação de cache custa mais do que um token de entrada normal (cerca de 1,25x da entrada base para o cache padrão de 5 minutos, cerca de 2x para um cache de 1 hora), mas uma leitura de cache custa aproximadamente 0,1x da entrada base; isso é cerca de 90% de desconto na porção em cache. Como o prêmio de gravação é pequeno e o desconto de leitura é grande, o cache se paga após um único acerto de cache no cache de curta duração, e após cerca de dois acertos no de longa duração. A vida útil padrão do cache é curta (cerca de 5 minutos, atualizada a cada acerto), com uma opção de 1 hora disponível. Há um tamanho mínimo que pode ser armazenado em cache; modelos pequenos e os maiores modelos precisam de alguns milhares de tokens antes que um prefixo seja elegível, então o cache ajuda mais exatamente onde importa: prefixos grandes e estáveis.

A regra estrutural é colocar o conteúdo estável primeiro e o conteúdo volátil por último, e então cachear a fronteira. A ordem é `ferramentas → sistema → mensagens`, e qualquer alteração invalida aquele nível e tudo que vem depois. Então, você quer que carimbos de data/hora, a mensagem de entrada do usuário e o conteúdo de arquivos recém-recuperados venham depois do seu ponto de interrupção de cache, não antes.

Se você aciona um modelo diretamente do seu próprio wrapper CLI, defina isso explicitamente:

# Armazena em cache o prefixo estável (sistema + definições de ferramentas + convenções de repositório).
# O turno volátil do usuário vem depois e NÃO faz parte do prefixo em cache.
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,   # estável em todas as execuções
            "cache_control": {"type": "ephemeral"},       # ponto de quebra de cache aqui
        }
    ],
    messages=[{"role": "user", "content": user_task}],     # muda a cada execução
)

# Inspecione o que realmente foi armazenado em cache:
u = response.usage
print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)   # esses tokens são cobrados ~10%
print("fresh input:", u.input_tokens)

Um agente de refatoração diária que executa o mesmo prompt de sistema e o mesmo bloco de convenção de repositório de 8.000 tokens em 60 invocações por dia é o caso de livro. Sem cache, você paga o preço total de entrada por esse bloco de 8.000 tokens 60 vezes. Com cache, você paga o prêmio de gravação uma vez (ou uma vez por expiração de cache) e o preço de leitura de ~10% nas outras vezes. Somente no bloco de convenção, isso é uma redução de quase 90%, e se acumula com todas as outras táticas aqui.

Duas notas operacionais. Primeiro, mantenha seu prefixo byte-estável; um único caractere alterado antes do ponto de interrupção invalida o cache e você paga uma nova gravação. Fixe seu prompt do sistema e suas convenções; não interpole um carimbo de data/hora neles. Segundo, o cache é de curta duração por padrão, então agrupar execuções relacionadas próximas umas das outras (em vez de espalhá-las ao longo do dia) mantém você atingindo um cache "quente". A API da OpenAI aplica um desconto semelhante à entrada em cache automaticamente em modelos suportados; o princípio é idêntico, embora os controles sejam diferentes. Os truques de nível gratuito e roteamento em executando GPT-5.5 gratuitamente através do Codex são um complemento útil quando o cache sozinho não é suficiente.

Roteamento de modelos: modelo barato para trabalho barato

Nem toda ação de agente precisa de um modelo de ponta. Renomear uma variável em três arquivos, escrever uma mensagem de commit, resumir um diff ou gerar um teste boilerplate não exige o mesmo modelo que projeta uma arquitetura. No entanto, o comportamento padrão da maioria dos agentes CLI é executar tudo através de um modelo caro para toda a sessão.

Roteamento significa enviar deliberadamente subtarefas de baixo risco para um modelo menor e mais barato, e reservar o modelo caro para raciocínio genuíno. A diferença de preço é grande: um modelo pequeno em uma determinada família pode ser de três a cinco vezes mais barato por token do que o carro-chefe, e para tarefas mecânicas, a diferença na qualidade da saída é insignificante.

Maneiras práticas de rotear da CLI:

# 1. Escolha o modelo por invocação com base na tarefa.
claude --model haiku   "escreva uma mensagem de commit convencional para o diff preparado"
claude --model sonnet  "redesenhe a camada de cache para o serviço de pagamentos"

# 2. Use um modelo barato para o loop de alta frequência e baixo risco
#    (mensagens de commit, entradas de changelog, explicações rápidas de lint)
#    e um modelo forte apenas quando você invoca explicitamente a tarefa difícil.

Defina o modelo mais barato como padrão e escale conscientemente, em vez de usar o modelo caro por padrão e nunca descer. A maioria das equipes tem a polaridade invertida: eles executam o carro-chefe para tudo "para ser seguro" e pagam cinco vezes mais por mensagens de commit.

Um segundo eixo de roteamento são os subagentes. Se sua estrutura de agente suporta a delegação de uma subtarefa estreita a um agente filho, dê a esse filho um modelo barato e um contexto minúsculo. O filho faz o trabalho pesado (pesquisar, resumir, rascunhar) com pouco custo e relata um resultado curto de volta ao pai caro, em vez de o pai caro fazer o trabalho pesado ele mesmo a preço total com contexto completo. Os padrões de loop autônomo em o comando de objetivo entre Codex e Claude Code mostram como estruturar essa delegação para que o modelo caro veja apenas resultados destilados.

Uma nota sobre limites, não apenas dólares. Se você está em um plano com limite de uso, em vez de um puro pay-as-you-go, o roteamento também estica o quão longe sua permissão vai. Gastar seu orçamento de modelo premium em mensagens de commit é como as equipes atingem um limite até quinta-feira. O recente aumento do limite semanal do Claude Code ajuda, mas o roteamento ainda é o que faz a permissão durar.

Aparando a saída da ferramenta e recuperação

A saída da ferramenta é a assassina silenciosa do orçamento porque é invisível até que você olhe. Cada comando que um agente executa retorna texto, e esse texto vai direto para o contexto, onde é então reproduzido em cada turno subsequente. Um único npm install pode retornar milhares de linhas. Uma execução de teste com log verboso pode retornar dezenas de milhares de tokens. Um git diff que inclui um arquivo lock regenerado pode ser enorme. O agente raramente precisa de tudo; ele precisa do sucesso/falha e da falha relevante.

Táticas que cortam isso de forma limpa:

Torne os comandos silenciosos na origem. O agente paga por tudo o que o comando imprime. Configure as ferramentas para serem concisas:

# Barulhento (agente paga por cada linha):
npm test

# Silencioso (apenas falhas e um resumo retornam):
npm test --silent -- --reporter=dot

# Barulhento:
npm install

# Silencioso:
npm install --silent --no-audit --no-fund

Filtre antes que o agente veja. Quando você controla o comando que o agente executa, desvie o ruído para que apenas o sinal retorne:

# Apenas as linhas que importam retornam ao contexto:
pytest -q 2>&1 | tail -n 30

# Estatísticas de diff em vez de um diff completo de 4.000 linhas:
git diff --stat

# Grep pela falha em vez de despejar todo o log:
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20

Prefira leituras direcionadas a leituras de arquivos inteiros. Ler um arquivo de 1.500 linhas para alterar uma função é puro desperdício. Incentive o agente a procurar pelo símbolo e ler uma janela ao redor dele, não o arquivo inteiro. Muitos agentes fazem isso quando o prompt os estimula ("encontre e leia apenas a função que lida com tentativas, não o arquivo inteiro"). Em um arquivo grande, essa é a diferença entre ~18.000 tokens e ~800.

Restrinja o escopo de recuperação. Se seu agente faz busca de código ou RAG sobre documentos, limite quantos blocos ele puxa e quão grandes eles são. Dez trechos de 200 tokens que respondem à pergunta são melhores que cinquenta trechos de 800 tokens que a enterram; você paga por cada token recuperado, use o modelo ou não.

Essas mudanças são principalmente configurações únicas (relatores de teste, flags de instalação, um arquivo de ignorar) e rendem em todas as execuções para sempre, o que as torna algumas das melhores em termos de retorno sobre o esforço nesta lista.

Medindo e atribuindo o custo por execução

Você não pode gerenciar o que não mede, e "a conta diminuiu" não é medição. Para saber se uma tática funcionou, você precisa do custo atribuído a uma execução, idealmente a uma tarefa.

Comece com os dados que a API já fornece. Cada resposta inclui um objeto de uso. Capture-o:

u = response.usage
# Custo aproximado em dólares; substitua as taxas atuais para o seu modelo.
INPUT_RATE  = 3.00 / 1_000_000     # entrada base $/token (ilustrativo)
OUTPUT_RATE = 15.00 / 1_000_000    # saída $/token (ilustrativo)
CACHE_READ  = 0.30 / 1_000_000     # ~10% da entrada base
CACHE_WRITE = 3.75 / 1_000_000     # ~1.25x da entrada base (cache de 5 minutos)

cost = (
    u.input_tokens          * INPUT_RATE  +
    u.output_tokens         * OUTPUT_RATE +
    u.cache_read_input_tokens  * CACHE_READ +
    u.cache_creation_input_tokens * CACHE_WRITE
)
print(f"run cost ≈ ${cost:.4f}  "
      f"(in={u.input_tokens} out={u.output_tokens} "
      f"cr={u.cache_read_input_tokens})")

Se você usa a CLI do agente em vez do seu próprio wrapper, três abordagens funcionam:

# 1. A maioria das CLIs de agente expõe um comando de uso/custo para a sessão.
#    Verifique-o após uma tarefa representativa e anote o número.
claude /cost

# 2. Consoles de provedores relatam gastos por chave de API. Emita uma chave de API
#    dedicada por agente ou por projeto para que o gasto seja atribuível
#    em vez de agrupado em um total indetectável.

# 3. Marque as execuções. Envolva a invocação do agente em um script que registra
#    carimbo de data/hora, rótulo da tarefa e as contagens de tokens relatadas em um CSV.
#    Uma semana desse CSV informa quais tarefas são caras.

Estime antes de executar qualquer coisa grande. Cole o prompt e os arquivos que você pretende incluir em um tokenizador (o tokenizador público da OpenAI é uma maneira rápida de verificar o tamanho) e olhe a contagem. Se "incluir o módulo inteiro" for 90.000 tokens e a versão direcionada for 6.000, você acabou de ver a decisão antes de pagar por ela.

Acompanhe um número por tarefa representativa ao longo do tempo: custo por "execução de refatoração diária", custo por "execução de revisão de PR". Quando você ativa o cache ou alterna uma subtarefa para um modelo barato, esse número deve mudar. Se não mudar, a tática não está fazendo o que você pensa, e você aprendeu isso pelo preço de uma execução em vez de um mês de contas.

Comparativo de Táticas

Os intervalos de economia são ilustrativos e se acumulam multiplicativamente; o ganho de qualquer tática depende do seu desperdício inicial.

Conclusão

Os custos de tokens do agente são principalmente auto-infligidos, e a linha de comando é onde você os corrige. O desperdício reside no contexto que você reenvia, na saída que você não lê e nos modelos que são muito caros para a tarefa em questão. Aborde esses pontos e a conta diminui sem afetar a qualidade do trabalho.

Faça os itens de baixo esforço primeiro; delimitar o escopo, a saída silenciosa e um arquivo de memória enxuto não custam nada e rendem em todas as execuções a partir de agora. Adicione o cache e o roteamento, e a diferença será do tipo que você pode incluir no orçamento.