Imagine uma correção de bug que altera 12 linhas. O agente lê o projeto, escreve um plano, inicia um auxiliar, executa os testes, lê as falhas e tenta de novo antes de produzir essa correção.
A conta inclui todas as solicitações necessárias para chegar até ela.
Isso faz com que seja surpreendentemente fácil pagar demais por uma tarefa curta. Uma conversa longa pode levar arquivos antigos para solicitações posteriores. Uma ferramenta pode retornar páginas de dados quando a próxima decisão precisa de apenas um registro. Vários agentes podem repetir a mesma investigação.
Você pode encontrar esses custos no histórico de execução. Comece com uma tarefa, acompanhe tudo o que ela consome e verifique se o resultado realmente passa. Depois, altere a parte que está fazendo trabalho desnecessário.
1. Atribua um custo à tarefa concluída
Escolha uma tarefa que você repete: corrigir um erro relatado, preparar um resumo de pesquisa ou verificar um lote de registros de clientes. Defina o que conta como concluído antes de executá-la.
Para a correção de um erro, a aceitação pode exigir um teste que reproduza a falha original, um resultado aprovado após a alteração e nenhuma falha nos testes de integração afetados. Uma mensagem dizendo que o erro foi corrigido não atende a essas condições.
Atribua um ID à tarefa. Mantenha esse ID nas novas tentativas, nos agentes auxiliares, na verificação e no resultado final. Registre um ID de solicitação separado para cada chamada ao modelo para poder detectar duplicatas nos registros.
O cálculo básico é:
Custo por tarefa aceita = gasto total registrado / número de tarefas aceitas
Inclua as tentativas que falharam. Se 10 tarefas custarem US$ 8 no total e apenas 4 forem aprovadas, o custo será de US$ 2 por tarefa aceita. Informe também a taxa de aceitação de 40%. Se nenhuma tarefa for aprovada, informe o gasto e zero tarefas aceitas; a proporção é indefinida.
Acompanhe separadamente o tempo gasto por pessoas em correções. Um fluxo de trabalho que economiza US$ 1 em cobranças de API, mas exige 20 minutos de ajustes, apresenta uma compensação que vale a pena conhecer.
Para o trabalho com APIs, salve a resposta de uso do provedor, o ID do modelo, a data dos preços, as cobranças das ferramentas, o resultado da tarefa e os carimbos de data e hora. Se os dados de uso estiverem ausentes após um tempo limite, marque o custo como desconhecido e confira os registros do provedor. A ausência de uma resposta não prova que a solicitação foi gratuita. Se alguma solicitação continuar sem preço definido, identifique o total do lote como incompleto.
Quem usa o Claude Code pode começar com /usage e /context. O primeiro ajuda a inspecionar o uso; o segundo mostra o que ocupa a conversa. Em uma assinatura, uma estimativa local em dólares não é uma fatura separada, e a janela de contexto é um limite diferente da cota do seu plano.
2. Descubra qual contexto continua voltando
Sua mensagem mais recente é apenas parte de uma solicitação ao modelo. No Claude Code, as solicitações também podem conter instruções do projeto, descrições de ferramentas, histórico da conversa, conteúdo de arquivos e resultados anteriores de ferramentas.
Suponha que um documento inalterado de 12.000 tokens apareça em 8 solicitações. Nessas chamadas, o documento contribui com 96.000 tokens de entrada. Leituras elegíveis do cache podem ter uma tarifa menor. Mesmo assim, o documento pode ser irrelevante para algumas dessas decisões.
Examine a sequência de uma única tarefa. Quais arquivos foram lidos? Quais resultados permaneceram na conversa? Qual solicitação causou o maior aumento? O agente ainda estava usando esses detalhes no fim?
Para um erro no total de uma fatura, comece pela entrada que falha, pelo cálculo, por quem o chama e pelos testes que o cobrem. Deixe o agente seguir as referências quando precisar de mais informações. Carregar um repositório inteiro de antemão pode fazer com que todas as interações posteriores incluam material que nunca contribuiu para a correção.
Mantenha todas as evidências disponíveis em disco. Retorne um resultado conciso com o caminho do arquivo e detalhes suficientes para inspecionar o original. Para uma execução de teste, isso significa o comando, o código de saída, os nomes dos testes que falharam, o erro relevante e o local do registro.
Um resumo que omite a única pista gera mais trabalho. Preserve o erro exato, o identificador afetado e as evidências necessárias para a próxima ação.
3. Verifique se o cache está sendo útil
O cache de prompts reutiliza o início correspondente de uma solicitação que seja elegível. Coloque primeiro as instruções estáveis e, depois, os dados variáveis da tarefa.
Em um fluxo de trabalho personalizado com a API da Claude, um carimbo de data e hora antes do limite do cache pode criar uma entrada diferente a cada chamada. Posicione o limite depois do conteúdo que se repete. Consulte a documentação atual de cache para seu modelo e a estrutura da solicitação.
Compare as leituras e gravações no cache entre as solicitações. Muitas gravações e poucas leituras são motivo para verificar mudanças no prefixo, o tamanho mínimo elegível, a duração e o momento das chamadas.
As leituras do cache ainda custam dinheiro. Um número elevado de leituras pode indicar que o cache está funcionando; verifique também se esse contexto ajuda a concluir a tarefa.
No Claude Code, os subagentes comuns têm contexto próprio e comportamento de cache próprio. Uma bifurcação funciona de outra forma. A compactação também usa uma solicitação ao modelo e reconstrói o contexto da conversa. Evite agendar compactações manuais a cada poucos minutos sem medir o resultado.
4. Reduza o que as ferramentas retornam
A resposta de uma ferramenta pode se tornar entrada para chamadas posteriores ao modelo. Portanto, uma resposta grande pode afetar mais do que a solicitação que a obteve inicialmente.
Considere um relatório diário de pedidos. Uma ferramenta busca todos os pedidos, o modelo lê cada linha e outra solicitação pede que ele calcule os totais. Um script pode filtrar os registros, calcular os totais e retornar as exceções que exigem avaliação.
Isso muda o que chega ao modelo. Também cria um cálculo que você pode testar de forma independente.
Use a mesma abordagem para registros, planilhas e resultados de pesquisa. Filtre pelos clientes, datas, erros ou tipos de registro relevantes antes de retornar os dados. Inclua o filtro usado, a quantidade processada, qualquer truncamento e um caminho ou identificador para as evidências originais.
Verifique a paginação. Processar a primeira página e apresentá-la como se fosse todo o conjunto de dados resulta em uma resposta errada mais barata.
Os resultados intermediários podem permanecer no ambiente de execução enquanto os dados selecionados chegam ao modelo. Você pode aplicar esse princípio em um pequeno script local, sem criar um sistema de agentes complicado.
As definições das ferramentas também ocupam contexto quando são carregadas. Alguns clientes já adiam o carregamento das definições completas até que sejam necessárias. Inspecione sua configuração real antes de remover integrações: só a quantidade de conexões não informa o custo delas em tokens.
5. Salve o procedimento depois de descobrir como fazê-lo
Fique atento a tarefas em que o agente descobre repetidamente os mesmos comandos, reescreve o mesmo plano ou decide do zero quais testes executar.
Quando entender o procedimento, salve-o. Coloque as instruções específicas do projeto em um guia curto e reutilizável. Coloque cálculos fixos, transformações de arquivos e sequências de comandos em um script testado.
Para o erro no cálculo da fatura, um script pode preparar um caso de teste, executar o cálculo, comparar o valor esperado e informar o resultado. O agente ainda precisa diagnosticar uma divergência inesperada e escolher a correção adequada. Mas não precisa inventar o comando de teste toda vez.
Mantenha o procedimento vinculado às suas premissas. Registre as dependências necessárias, as entradas esperadas e as condições em que deve parar. Quando o ambiente mudar, uma falha explícita é mais fácil de diagnosticar do que uma mensagem plausível de sucesso.
Verificações de status repetidas merecem o mesmo tratamento. Se um serviço fornecer um ID de tarefa, use o evento de conclusão ou uma função de consulta periódica com limite definido. Volte ao modelo quando a tarefa terminar, falhar ou ultrapassar o prazo.
Ações que criam ou enviam algo exigem cuidado extra ao tentar novamente. Verifique se a primeira tentativa foi bem-sucedida antes de repeti-la. Reutilizar uma chave de idempotência, quando disponível, pode impedir que uma resposta incerta gere dois pedidos ou duas mensagens.
6. Dê a cada agente uma tarefa distinta
Agentes paralelos podem reduzir o tempo decorrido. As chamadas, o contexto e a coordenação deles também contribuem para o gasto total.
Divida o trabalho quando as tarefas forem independentes e os resultados fáceis de combinar. Um agente pode reproduzir um erro relatado, enquanto outro verifica o contrato da interface afetada. Dê a cada um uma pergunta clara e um resultado definido.
Evite dar a vários assistentes a mesma instrução ampla para inspecionar tudo. Isso pode gerar várias cópias da mesma investigação, seguidas de outra etapa para conciliar os resumos.
Uma transferência de trabalho útil especifica a tarefa, os arquivos relevantes, as alterações permitidas, o resultado esperado e a condição de parada. Peça os caminhos das evidências e as descobertas necessárias para a próxima etapa. Mantenha o trabalho intermediário detalhado disponível nos arquivos do assistente.
Planeje a verificação deliberadamente. Execute verificações direcionadas durante a implementação e, em seguida, execute as verificações mais abrangentes necessárias no resultado combinado. Repita uma verificação se o código tiver mudado, uma execução anterior tiver falhado ou novas evidências justificarem isso. Registre o motivo de cada execução.
Meça as mudanças no modelo separadamente das mudanças no fluxo de trabalho. Use o mesmo conjunto de tarefas e os mesmos testes de aceitação ao experimentar outro modelo ou configuração de raciocínio. Inclua novas tentativas e tempo de correção na comparação. Um preço menor por chamada só ajuda se o trabalho inteiro continuar valendo a pena.
7. Interprete corretamente os campos de uso
Provedores diferentes informam o uso de entradas em cache de maneiras diferentes. Copiar a fórmula de um provedor para os registros de outro pode gerar uma cobrança convincente, mas incorreta.
Em uma resposta padrão da Claude Messages, input_tokens, cache_creation_input_tokens e cache_read_input_tokens são categorias de entrada distintas. A criação do cache também pode ser dividida por duração. Associe cada categoria à sua tarifa.
No esquema atual da OpenAI Responses, as entradas em cache e as contagens aplicáveis de gravação no cache fazem parte do total de entradas. É necessário subtraí-las conforme a documentação antes de calcular o preço das entradas comuns. Use o cálculo do provedor para o modelo e a API que estiver usando.
Mantenha a resposta de uso original junto ao seu registro normalizado. Assim, você poderá corrigir o cálculo quando o provedor, o modelo ou os preços mudarem.
Alguns recursos também geram trabalho extra cobrado. Na compactação pela API da Claude, as contagens de entrada e saída de nível superior não incluem a iteração de compactação. Calcule uma vez os valores em usage.iterations, usando os campos de uso de cada entrada. Não some novamente as contagens de nível superior.
A execução de ferramentas, a pesquisa, a hospedagem e o armazenamento podem ter cobranças separadas. Identifique um valor como custo do modelo se essas cobranças estiverem excluídas. Para solicitações transmitidas em fluxo, use os totais de uso da solicitação concluída, quando disponíveis, e evite contar atualizações cumulativas várias vezes.
8. Analise um lote
Veja um cálculo ilustrativo que você pode reproduzir. As contagens de solicitações, os volumes de tokens, as tarifas das ferramentas e os resultados abaixo são inventados. Nenhum agente foi executado para produzi-los.
O trabalho de exemplo extrai três valores e as passagens que os sustentam de cada um de quatro documentos. Um resultado só é aprovado quando o JSON, os valores e as evidências de origem estão corretos.
Ambos os cenários pressupõem três resultados aceitos, uma tentativa rejeitada que precisa ser repetida e uma tarefa que acaba falhando. São cinco tentativas para quatro tarefas. Cada tentativa contribui para a cobrança.
O primeiro cenário contém 15 solicitações ao modelo: 375.000 tokens de entrada não armazenados em cache e 15.000 tokens de saída. Aos preços padrão da Claude Haiku 4.5 verificados em 7 de setembro de 2026, a entrada custa US$ 1 por milhão de tokens e a saída custa US$ 5 por milhão. A cobrança do modelo é de US$ 0,45. Somando US$ 0,06 em tarifas inventadas de ferramentas externas, o total é US$ 0,51.
Divida US$ 0,51 pelos três resultados aceitos: US$ 0,17 por resultado aceito.
O segundo cenário pressupõe 10 solicitações, com menos entradas novas e algumas entradas em cache. As cobranças do modelo são discriminadas da seguinte forma:
• 55.000 tokens de entrada não armazenados em cache a US$ 1 por milhão: US$ 0,055.
• 25.000 tokens de gravação no cache por cinco minutos a US$ 1,25 por milhão: US$ 0,03125.
• 25.000 tokens de gravação no cache por uma hora a US$ 2 por milhão: US$ 0,05.
• 50.000 tokens de leitura do cache a US$ 0,10 por milhão: US$ 0,005.
• 7.500 tokens de saída a US$ 5 por milhão: US$ 0,0375.
Isso totaliza US$ 0,17875 em cobranças do modelo. Somando US$ 0,05 em tarifas inventadas de ferramentas externas: US$ 0,22875 por todas as tentativas, ou US$ 0,07625 por resultado aceito. A combinação de durações de cache demonstra as categorias contábeis; não é uma configuração recomendada.
Esses números mostram o custo do uso declarado. Não demonstram que filtrar o contexto ou alterar um limite do cache produzirá essas contagens ou manterá a qualidade. Uma comparação real exige solicitações registradas e resultados verificados de forma independente. As tarefas que falharam ainda fazem parte do total.
9. Experimente no seu próprio fluxo de trabalho
Escolha um pequeno conjunto de tarefas representativas e mantenha as entradas inalteradas. Inclua um caso de sucesso comum, um caso difícil e uma tarefa que já tenha falhado antes. Defina as verificações de aceitação antes de fazer alterações.
Execute o fluxo de trabalho atual e salve os registros das solicitações. Marque o ponto em que material desnecessário entrou na conversa, um procedimento foi recriado, uma verificação duplicada foi executada ou um erro inalterado provocou outra tentativa.
Altere um mecanismo. Filtre um resultado grande de uma ferramenta. Salve uma sequência de comandos repetida. Corrija um limite do cache. Restrinja a tarefa de um assistente. Mantenha o modelo e os critérios de aceitação inalterados nessa comparação.
Execute novamente as mesmas entradas em um ambiente de teste limpo. Diferencie as execuções iniciais das execuções com o cache aquecido. Repita o suficiente para verificar se o resultado é consistente e mantenha as tentativas que falharam nos totais.
Use este prompt com um agente de programação que possa acessar sua implementação e seus registros:
Inspecione este fluxo de trabalho e os registros de execução disponíveis.
Defina os limites da tarefa e as verificações de aceitação. Rastreie as chamadas principais, as chamadas dos assistentes, as novas tentativas, a verificação e o resultado final.
Crie um relatório local com o custo registrado do modelo, as cobranças separadas das ferramentas, os dados de uso ausentes, as tarefas aceitas, as tarefas que falharam, o tempo decorrido e as intervenções humanas. Use os campos de uso específicos do provedor e uma tabela de preços datada. Preserve as respostas de uso brutas. Elimine IDs de solicitação duplicados.
Identifique o maior custo evitável respaldado pelos registros. Aponte as chamadas específicas e explique por que o trabalho era desnecessário. Mantenha as estimativas separadas dos valores registrados.
Proponha uma alteração e uma comparação usando as mesmas entradas, o mesmo modelo e as mesmas verificações de aceitação. Separe as execuções iniciais das execuções com o cache aquecido. Pare se faltarem as evidências necessárias e especifique exatamente o que é necessário.
Não faça chamadas pagas à API nem altere o fluxo de trabalho em produção durante esta inspeção. Salve o relatório e a proposta de alteração para revisão.
As verificações de aceitação são o que mantém a comparação honesta. Se filtrar um registro ocultar a falha, ou se um modelo menor precisar de correções repetidas, registre esse resultado e reveja a alteração.
Escrevo aqui sobre fluxos de trabalho práticos com IA. Siga-me para acompanhar o próximo.