A Explosão de Tokens Agênticos: Atribuição de Custos e Orçamentos para Código Claude em CI/CD

Quando os agentes passam de sessões interativas para pipelines de CI/CD, o mecanismo de ritmo humano desaparece e os loops ReAct aumentam o contexto quadraticamente. A fatura do provedor informa quanto você gastou. Ela não pode dizer o porquê — ou onde cortar sem prejudicar a velocidade.

Por que o CI/CD muda a dinâmica econômica

Sessões interativas de IA têm um mecanismo de ritmo integrado: o humano na frente do teclado. O humano lê a saída do agente, decide o que fazer em seguida e consome aproximadamente um prompt a cada poucos minutos. Esse ritmo é um limite de taxa suave, mesmo quando nenhuma política o impõe.

Pipelines de CI/CD não têm isso. Um agente configurado para revisão automatizada de PR pode ser acionado centenas de vezes por hora pelo tráfego comum de commits, e não há nada em seu ambiente que o retarde. A matemática é pior do que a frequência de acionamento sugere, porque o custo por chamada em si aumenta — frameworks de agentes como o ReAct anexam o resultado de cada ação de volta à janela de contexto antes da próxima etapa de raciocínio. O consumo de tokens por execução de agente cresce aproximadamente O(n²) no número de etapas.

.

‍

O ponto cego da cobrança do provedor

Os painéis da Anthropic e da OpenAI informarão exatamente quantos tokens sua organização consumiu na última terça-feira. Eles não dirão o porquê. O provedor não tem contexto de aplicação — eles não conseguem distinguir um pipeline de dados de produção crítico de um projeto paralelo de loop infinito de um engenheiro júnior. Ambos cobram o mesmo.

Sem atribuição granular, o financeiro recorre à única ferramenta disponível: proibições gerais. O uso de IA é pausado para revisão. Cargas de trabalho legítimas são limitadas junto com as descontroladas. Líderes de engenharia aprendem a temer a chamada de fechamento mensal. O problema fundamental é que a atribuição deve ocorrer na ingestão, não na cobrança — quando a fatura chega, os rótulos de que você precisava já se foram.

A fatura do provedor responde “quanto”. O registro atribuído pelo gateway responde “qual repositório, qual pipeline, qual etapa do agente e o que corrigir”. Essa diferença transforma uma crise financeira em um ticket de engenharia.

Marcação de metadados em nível de gateway

A base da atribuição de custos é a marcação obrigatória no gateway. Cada requisição de um pipeline de CI/CD injeta um pequeno objeto JSON via cabeçalho X-TFY-METADATA, identificando a equipe, o repositório, o pipeline, a etapa do agente e o centro de custo responsável. O formato é simples, intencional e o mesmo em todas as equipes:

HTTP  ·  cabeçalho obrigatório em cada requisição de CI

X-TFY-METADATA: {
  "team":         "payments-platform",
  "repo":         "transaction-service",
  "pipeline":     "pr-security-audit",
  "agent_step":   "step-2-policy-check",
  "cost_center":  "eng-backend",
  "environment":  "production"
}

As tags são obrigatórias, não consultivas. Requisições sem tag são rejeitadas no gateway, não passadas silenciosamente. Esta é a política que produz 100% de observabilidade — não há uma categoria de "desconhecido" no painel, porque não há caminho que produza uma. O custo da aplicação é uma regra Cedar/OPA. O custo de não aplicar é uma escalada financeira trimestral.

‍

‍

Com as tags em mãos, o gateway conta os tokens de entrada, saída e em cache para cada chamada, avalia o custo do resultado com base nas tarifas atuais do provedor e registra uma entrada de livro-razão totalmente atribuída. As visualizações de custo são segmentadas por usuário, modelo e equipe de forma nativa, com uma opção de Download de Dados Brutos que permite exportar com campos de agrupamento personalizados (nome de usuário, nome do modelo, equipes ou qualquer chave de metadados que você tenha usado para taguear). Cada dólar tem um nome.

Orçamentos por projeto com disjuntores

Visibilidade sem aplicação é um painel que ninguém toma providências. A TrueFoundry atribui orçamentos hierárquicos e matematicamente impostos a cada centro de custo que o tagueamento produz. Os orçamentos são uma lista ordenada de regras, cada uma delas delimitada por assuntos, modelos ou chaves de metadados. Duas semânticas distinguem as regras de orçamento das regras de limite de taxa e vale a pena compreendê-las com precisão:

• O acompanhamento do orçamento ocorre para cada regra correspondente. Se uma solicitação corresponder a três regras, o custo é debitado contra todas as três. Orçamentos em camadas — um orçamento de equipe de US$ 500, além de um orçamento de US$ 50 por repositório, além de um orçamento de US$ 10 por desenvolvedor — todos permanecem sincronizados simultaneamente.
• As decisões de permitir/bloquear vêm apenas da primeira regra correspondente. As regras são avaliadas de cima para baixo, e a primeira cujas condições correspondem decide se a solicitação é aprovada ou rejeitada. Coloque as substituições de alta prioridade no topo, os padrões na parte inferior.

Os alertas de orçamento são acionados em quatro limites configuráveis — 75%, 90%, 95% e 100% do limite máximo — com canais de notificação para e-mail, webhook do Slack e bot do Slack. A verificação é executada a cada 20 minutos em relação ao último livro-razão atribuído:

Tabela 1 — Limites de orçamento. Cada limite é acionado uma vez por período orçamentário (dia / semana / mês) e é redefinido no início do próximo período. Os alertas são verificados a cada 20 minutos.

O comportamento de 100% faz parte do design, não é uma reflexão tardia. O gateway retorna um erro estruturado que nomeia o orçamento esgotado e direciona o operador para o painel:

JSON  ·  Resposta 429 sobre limite máximo rígido

{
  "error":      "Budget Exceeded",
  "rule_id":    "transaction-service-daily",
  "detail":     "Repository \"transaction-service\" has exhausted its
                 daily $50 AI budget at 14:32 UTC.",
  "mitigation": "Review pipeline logs for infinite loops or request a
                 quota increase via the platform team.",
  "dashboard":  "https://gateway.example.com/budgets/transaction-service"
}

Um pipeline que atinge seu orçamento deve saber o que fazer em seguida, sem que o desenvolvedor precise procurar a equipe da plataforma para obter contexto. Os executores de CI interpretam 429 como um sinal de backoff padrão; a compilação falha de forma limpa com uma mensagem acionável, em vez de travar de maneiras confusas.

Há mais um comportamento que vale a pena conhecer: o modo de auditoria. Definir block_on_budget_exceed: false em qualquer regra mantém o rastreamento e os alertas ativos, mas permite que as solicitações passem. Este é o padrão correto durante o primeiro mês de implementação. Observe os alertas serem acionados contra limites simulados; ajuste os limites; só então ative a aplicação. Pular o modo de auditoria é como você acorda com uma equipe irritada cujos pipelines falharam todos às 03:00.

YAML  ·  configuração de orçamento em camadas

name: cicd-budget
type: gateway-budget-config
rules:
  - id: "ml-team-override"
    when: { subjects: ["team:ml-engineering"] }
    limit_to: 200
    unit: cost_per_day
    budget_applies_per: ["user"]
  - id: "default-user-daily"
    when: {}
    limit_to: 10
    unit: cost_per_day
    budget_applies_per: ["user"]
  - id: "per-repo-daily"
    when: {}
    limit_to: 50
    unit: cost_per_day
    budget_applies_per: ["metadata.repo"]
    alerts:
      thresholds: [75, 90, 100]
      notification_target:
        - type: slack-webhook
          notification_channel: "ai-budget-alerts"

Construindo um painel de atribuição de custos

Dados tagueados fluindo para a camada de métricas do gateway permitem que a equipe da plataforma construa painéis que respondem a perguntas de propriedade em vez de produzir mais ruído agregado. Em vez de olhar para um pico e perguntar “quem fez isso?”, o painel já informa que às 02:00 UTC a equipe de frontend implantou um novo agente no react-monorepo que alucinou uma dependência ausente e entrou em um loop de resolução de 400 etapas.

Esse tipo de contexto operacional transforma o custo de um problema financeiro em um problema de engenharia. Uma vez que você pode ver que mudar a etapa inicial de sumarização de código de Sonnet para Haiku reduz o custo dessa etapa em 80% sem afetar a qualidade da revisão de PR, você faz a mudança. Você não discute sobre limites de orçamento em um comitê de direção. As visualizações de acompanhamento de custos da TrueFoundry vêm prontas para uso para as perspectivas de Usuário, Modelo e Equipe, e a exportação de dados brutos permite que você segmente por qualquer chave de metadados — então uma visualização por repositório, por pipeline ou por etapa de agente é um download com um clique, não um projeto de engenharia de dados.

‍

‍

Previsão de gastos mensais antes da chegada da fatura

Dados de tagueamento agregados também tornam a previsão viável. Cargas de trabalho agentivas são intermitentes — trabalhos pesados de CI periódicos dominam a fatura — e é por isso que médias móveis simples subestimam sistematicamente os gastos. A média dos últimos 7 dias é a previsão errada para uma carga de trabalho cujo percentil 95 é 4 vezes a sua média.

O modelo certo é uma previsão contínua P95, executada por repositório e por equipe. A P95 captura o risco de picos que uma média suaviza, projetando os gastos de fim de mês com tempo de antecedência suficiente para ajustar orçamentos, aumentar cotas ou desativar um pipeline problemático antes que o setor financeiro se depare com a surpresa. “Surpresa” é a palavra-chave: esta é uma previsão projetada para não produzi-las. Na prática, uma P95 de 7 dias monitorou os gastos reais de fim de mês com uma margem de 8–12% nas cargas de trabalho que medimos — próximo o suficiente para agir, muito melhor do que a alternativa da média móvel.

Um exemplo real: $8.400 → menos de $800

Uma organização com 50 engenheiros desenvolveu um agente de revisão de código Claude de três etapas que era executado em cada pull request: (1) resumir as diferenças, (2) revisar as diferenças em relação às políticas de segurança por meio de um servidor de documentação MCP, (3) sugerir alterações de código. Arquitetura sensata, fluxo de trabalho útil, sem sinais de alerta óbvios.

Com cerca de 15 PRs por engenheiro por semana, considerando as tentativas e o custo da janela de contexto de injetar arquivos inteiros nos prompts, o agente teve uma média de cerca de 400.000 tokens de entrada por PR. Fatura do primeiro mês para automação de CI/CD: $8.400.

Tabela 2 — Análise detalhada de uma depuração de atribuição de custos. Cinco cliques no gateway, uma alteração de configuração. Sem atribuição, a resposta teria sido uma proibição geral do Sonnet para fluxos de trabalho de CI. Com atribuição, a resposta foi uma alteração de configuração de uma linha.

Essa lacuna — entre “banir o modelo” e “armazenar um prompt em cache” — é o benefício total de fazer a atribuição corretamente. Os dados de custo existem de qualquer forma; a questão é se você tem os rótulos para lê-los.

Perguntas Frequentes

Os orçamentos devem ser denominados em dólares ou tokens?

Ambos, simultaneamente. Dólares se alinham com o planejamento financeiro e operacional. Tokens são a métrica de engenharia que permite depurar a eficiência dos prompts. A TrueFoundry monitora ambos — o setor financeiro é responsável pelos painéis de dólares, a engenharia pelos painéis de tokens, e o gateway é a fonte da verdade para ambos. As alterações de preço do provedor são absorvidas na camada de dólares sem que a engenharia precise refatorar nada; novos ajustes finos são absorvidos na camada de tokens sem que o setor financeiro precise saber o nome do modelo.

O que acontece quando um limite rígido é atingido no meio do pipeline?

O pipeline recebe um erro 429 com a descrição mostrada anteriormente e um link para o painel de orçamento. Os executores de CI interpretam o 429 como um sinal de backoff padrão; a compilação falha de forma limpa com uma mensagem acionável, em vez de travar de maneiras confusas. Os aumentos de cota são registrados como tickets padrão para a equipe de plataforma — a URL do painel no corpo do erro evita a rodada usual de “Não entendo por que isso está falhando.”

A marcação obrigatória atrasa a implantação?

Na prática, não — os wrappers do SDK lidam com a injeção automaticamente dentro dos modelos de CI, então os desenvolvedores individuais nunca editam cabeçalhos. O custo único é a atualização dos modelos de pipeline da equipe; o custo recorrente é zero. O benefício recorrente é cada painel, cada alerta e cada análise post-mortem que se segue.

Qual a diferença entre limites de taxa e limites de orçamento — quando usar cada um?

Limites de taxa interrompem picos; limites de orçamento interrompem gastos. Limites de taxa são denominados em requisições/minuto ou tokens/minuto — eles protegem os serviços downstream de serem sobrecarregados e são avaliados por requisição. Orçamentos são denominados em dólares por dia/semana/mês — eles protegem o caixa da empresa e são avaliados em relação ao registro cumulativo. A maioria das pilhas de produção executa ambos, com escopo para diferentes entidades. Os padrões são complementares, não redundantes.

‍

‍