Custo de contexto de agentes de IA: como medir prompts e chamadas de ferramentas
Guia prático para medir e otimizar os custos de contexto em agentes de IA multi-etapas: perfis de esquemas de ferramentas, medição de baseline e validação.
Ao desenvolver agentes autônomos de IA (Claude Code, Cline, Roo Code ou pipelines próprios de múltiplas etapas), as equipes frequentemente enfrentam um aumento abrupto nas despesas de API. O motivo central é a propagação cumulativa de contexto: a cada passo do ciclo de raciocínio, o modelo lê novamente o prompt de sistema, todas as definições de ferramentas (tool schemas), o histórico da conversa e os resultados brutos das funções executadas.
Para gerenciar o orçamento sem comprometer a qualidade do código, é necessário medir uma linha de base (baseline) em uma tarefa controlada e otimizar o ambiente alterando uma variável de cada vez.
Anatomia do contexto de um agente de IA: onde os tokens são consumidos
Em cada iteração, a janela de contexto de um agente é composta por quatro camadas:
- Instruções e diretrizes de sistema (System Prompt): Regras de codificação, restrições de segurança e convenções do repositório.
- Esquemas de ferramentas (Tool Schemas): Definições JSON de todas as funções disponíveis. Ao fornecer 20 ferramentas, seus esquemas são reenviados a cada chamada, consumindo de 3.000 a 15.000 tokens de entrada repetidamente.
- Histórico de mensagens: Registro acumulado das interações do desenvolvedor e respostas prévias do agente.
- Saídas de ferramentas (Tool Outputs): Conteúdo integral de arquivos lidos, logs de terminal e retornos de APIs.
Em uma tarefa de 10 passos, um contexto base de 15.000 tokens será cobrado 10 vezes como input tokens caso o prompt caching não seja aproveitado.
Matriz comparativa de componentes de contexto e otimização
Guia passo a passo: como medir a baseline e reduzir despesas
Adote esta metodologia de teste com variável única para sua infraestrutura:
Passo 1. Definir uma tarefa de controle reproduzível
Escolha uma tarefa de desenvolvimento representativa com critério objetivo de conclusão (por exemplo: «localizar uma função no projeto, adicionar tratamento de caso de borda e executar os testes unitários com sucesso»).
Passo 2. Medir a Baseline (Entrada, Saída, Cache)
Execute a tarefa com a configuração padrão do agente e registre:
- Quantidade de iterações executadas (ex. 10 passos);
- Volume de tokens de entrada (ex. 150.000 tokens);
- Volume de tokens de saída (ex. 2.500 tokens);
- Volume de tokens lidos do cache (cached tokens);
- Custo financeiro calculado pelas tarifas ativas.
Com uma tarifa de 0,45 por execução.
Em 2026-08-22, as tarifas atualizadas por 1M de tokens podem ser verificadas na página oficial de preços do BetterToken. O painel BetterToken Dashboard exibe a telemetria detalhada de cada chamada.
Passo 3. Alterar uma única variável de contexto
Realize execuções de teste modificando estritamente um parâmetro por rodada:
- Experimento A (Filtragem de ferramentas): Mantenha apenas 3 ferramentas básicas (read_file, replace_content, run_test) em vez de 15 gerais (economia de até 8.000 tokens por passo).
- Experimento B (Truncamento de saídas): Limite os logs do terminal às 50 primeiras linhas de erro em vez de 2.000 linhas completas.
- Experimento C (Prompt Caching): Mantenha o prompt de sistema e as ferramentas no início do contexto para reduzir o custo de leitura em cache para cerca de $0,30 por 1M de tokens.
Passo 4. Avaliar economia e qualidade da entrega
Compare as métricas com a baseline inicial. Se os testes continuarem passando sem perda de velocidade e o volume de tokens de entrada cair de 40% a 60%, consolide a alteração em produção.
Boas práticas de arquitetura para agentes
- Utilizar subagentes especializados: Não sobrecarregue o agente principal com ferramentas de terminal e edição simultaneamente. Utilize subagentes de leitura para a etapa de pesquisa.
- Manter prefixos estáveis de prompt: Posicione as regras imutáveis no início do contexto para maximizar o prompt caching (até 90% de desconto na leitura de contexto).
- Definir teto de iterações (max iterations): Configure um limite rígido de passos (ex. 15 passos) para interromper loops infinitos de retry em caso de erro.
Armadilhas comuns e cuidados
- Armadilha: Remoção de esquemas essenciais. Omitir parâmetros críticos faz o modelo produzir saídas JSON inválidas, gerando retrabalho.
- Armadilha: Acreditar em números genéricos de redes sociais. A economia real depende da estrutura dos arquivos e da densidade do repositório.
- Armadilha: Falta de telemetria detalhada. Consulte a documentação do BetterToken para configurar corretamente os cabeçalhos e o monitoramento de chamadas.