Custo de contexto de agentes de IA: como medir prompts e chamadas de ferramentas repetidos

Ao desenvolver agentes de IA (Claude Code, Cline, Roo Code ou pipelines próprios de várias etapas), o uso da API pode crescer à medida que o contexto se acumula. A composição exata de cada solicitação depende do cliente: ela pode incluir o prompt do sistema, os esquemas das ferramentas disponíveis, o histórico de mensagens e os resultados de chamadas de função.

Para controlar o orçamento sem perder funcionalidade, estabeleça uma baseline para uma tarefa fixa, localize a principal fonte de tokens em excesso e otimize o ambiente do agente mudando uma variável por vez.

Anatomia do contexto de um agente de IA: pelo que os tokens são cobrados em cada etapa

Para medir, divida o contexto enviado ao modelo em quatro componentes observáveis:

1. Instruções e regras do sistema (System Prompt): requisitos básicos de estilo, limites de segurança e contexto do repositório.
2. Esquemas de ferramentas (Tool Schemas): descrições JSON de funções conectadas, parâmetros e tipos de dados, quando o cliente os inclui em uma solicitação.
3. Histórico de mensagens (Message History): mensagens anteriores do usuário e respostas do agente que se acumulam durante a tarefa.
4. Resultados de ferramentas (Tool Outputs): conteúdo de arquivos lidos, logs de comandos de terminal e dumps de API.

Não multiplique cegamente o tamanho da primeira solicitação pelo número de etapas. Exporte o usage de cada chamada: o histórico pode crescer, o cliente pode truncar dados e o provedor pode contabilizar cached tokens separadamente.

Tabela comparativa das fontes de contexto e suas otimizações

Componente de contexto	O que medir	Principal risco de gasto excessivo	Mudança para um teste isolado
Tool Schemas	Tamanho da lista realmente enviada	Ferramentas não usadas no conjunto compartilhado	Manter apenas as tools necessárias à tarefa
Tool Outputs	Tamanho de cada resultado	Ler arquivos inteiros em vez de trechos precisos	Limitar intervalos de linhas e volume de logs
Histórico de etapas	Crescimento do input de chamada a chamada	Acúmulo de resultados que já não são necessários	Verificar a redução de histórico suportada pelo cliente
System Prompt	Tamanho e estabilidade do prefixo	Instruções repetidas	Remover duplicação, preservando as regras obrigatórias

Guia passo a passo: como medir a baseline e reduzir gastos

Primeiro, registre as tarifas atuais do modelo. Para calcular a baseline, use os preços atuais da BetterToken, e não valores de exemplos antigos. Ver preços atuais da BetterToken

Para uma otimização objetiva, use a metodologia de medição com uma variável por vez:

Passo 1. Fixar uma tarefa de controle para o teste

Escolha um cenário de engenharia reproduzível, por exemplo: “encontrar uma função de validação no repositório, adicionar o tratamento de um caso extremo e executar testes unitários”. A tarefa deve ter um critério claro de conclusão, como código de saída 0 em pytest ou bun test.

Passo 2. Medir a baseline (Input, Output, Cache)

Execute a tarefa na configuração padrão do agente. Registre nos logs ou em um painel de monitoramento:

• número de etapas executadas;
• volume total de input tokens;
• volume total de output tokens;
• volume de tokens em cache (cached tokens);
• custo financeiro pelas tarifas atuais.

Confira as tarifas atuais do modelo escolhido na página de preços da BetterToken. No Workspace, para uma solicitação aceita você pode verificar modelo, horário e status, input/output tokens, cached tokens quando o modelo os suporta e o custo da chamada. Se uma etapa do agente criar várias solicitações, não trate um registro por solicitação como uma divisão pronta por etapa: correlacione-os por hora e pelos dados do seu próprio cliente.

Passo 3. Alterar uma variável de contexto

Faça testes isolados, modificando estritamente um parâmetro a cada iteração:

• Experimento A (Tool Filtering): mantenha apenas as ferramentas necessárias para a tarefa de controle e meça a diferença de input tokens.
• Experimento B (Output Truncation): limite a saída do terminal às primeiras 50 linhas de um erro, em vez de um dump completo de 2.000 linhas.
• Experimento C (Prefix Stability): se o modelo e o endpoint suportarem prompt caching, mantenha inalterada a ordem do prompt do sistema e dos esquemas de ferramentas; depois verifique os dados reais de cached tokens.

Passo 4. Avaliar a economia e a qualidade da solução

Compare as métricas finais com a baseline original. Mantenha uma alteração somente se a tarefa de controle continuar atendendo ao mesmo critério de qualidade e se o tempo ou gasto medido melhorar no seu conjunto de execuções.

Recomendações para configurar ambientes de agentes

1. Reduza o conjunto de ferramentas por papel: um agente de leitura não precisa de funções de escrita; verifique se isso reduz o input real sem prejudicar o resultado.
2. Mantenha um prefixo estável: se caching for suportado, não altere sem necessidade a ordem das regras comuns e verifique cached tokens em vez de pressupor um desconto.
3. Limite o ciclo: defina um número finito de tentativas e uma condição explícita de parada apropriada para a tarefa específica.

Casos de borda e erros comuns

• Erro: desativar esquemas de validação críticos. Se a descrição de um esquema de ferramenta for reduzida demais, o modelo pode enviar JSON inválido e provocar uma sequência de solicitações repetidas.
• Erro: confiar cegamente em promessas de economia nas redes sociais. O efeito da otimização de contexto depende da estrutura do seu repositório e do tamanho médio dos arquivos.
• Erro: falta de telemetria transparente. Se o endpoint não retornar estatísticas separadas de input/cache tokens, não estime o uso de cache com base em suposições; marque o valor como desconhecido.