Quanto custa um agente de IA
(e como não estourar o orçamento)

"Quanto custa rodar um agente de IA?" é a primeira pergunta de quem vai colocar um em produção — e a resposta honesta não é um número, é um mecanismo. O custo de um agente é função de poucas variáveis concretas: quantos tokens entram, quantos tokens saem, qual o preço do modelo por milhão de tokens e quantas chamadas de modelo um único turno dispara. Quem entende o mecanismo transforma o orçamento de loteria em engenharia.

Este post desmonta essa conta: para onde os tokens vão num turno agêntico, por que uma única "mensagem" pode custar várias vezes o preço de uma completion simples, e como fazemos para que o custo seja medido, não estimado — com uma trava dura no orçamento em vez de uma surpresa na fatura.

A conta básica: tokens × preço do modelo

Todo provedor de LLM cobra do mesmo jeito: tokens de entrada (tudo que você envia ao modelo) e tokens de saída (tudo que ele gera), cada um com um preço por milhão de tokens. Saída costuma custar um múltiplo da entrada, e o preço entre modelos varia ordens de magnitude — de modelos rápidos que custam centavos por milhão de tokens a modelos de fronteira que custam dezenas de dólares. A mesma pergunta, respondida por dois modelos diferentes, pode ter custo 100x distinto.

A fórmula de uma chamada é trivial: custo = entrada × preço_entrada + saída × preço_saída. O que engana não é a fórmula — é achar que um turno de agente é uma chamada só.

Um turno agêntico são várias chamadas de modelo

Um agente com ferramentas trabalha em rodadas: o modelo lê o contexto e decide chamar uma ferramenta; a plataforma executa a chamada REST; o resultado volta para o modelo; ele decide se chama outra ferramenta ou se já tem o que precisa para responder. Cada rodada é uma chamada de modelo completa — e o contexto inteiro (system prompt, histórico, definições de ferramenta, resultados anteriores) é reenviado em cada uma.

Na prática: uma mensagem que aciona duas ferramentas vira pelo menos três chamadas de modelo, cada uma pagando o contexto de novo — e o contexto ainda cresce a cada rodada, porque os resultados das ferramentas entram nele. Estimar custo "por mensagem" subestima sistematicamente; o multiplicador real é o número de rodadas.

O custo de um agente não é o preço de uma resposta — é o preço de um raciocínio inteiro, com o contexto reprocessado a cada rodada. Quem mede por mensagem erra a conta; quem mede por execução acerta.

Para onde vão os tokens num turno

Antes de o modelo escrever a primeira palavra da resposta, a janela de contexto já carrega:

• System prompt — a persona e as instruções do agente;
• Skills — os blocos de instrução reutilizáveis anexados ao agente;
• Memória — o que o agente sabe sobre este usuário final: fatos, preferências, resumo das conversas anteriores;
• Contexto de RAG — os trechos dos seus documentos recuperados para a pergunta;
• Definições de ferramentas — nome, descrição e parâmetros de cada tool disponível;
• Histórico da conversa e a mensagem do usuário.

Tudo isso é token de entrada, cobrado em cada rodada. Do outro lado saem a resposta final e os argumentos de cada chamada de ferramenta — tokens de saída.

ENTRADA (recontada a cada rodada)          SAÍDA
┌─────────────────────────────┐            ┌────────────────────┐
│ system prompt               │            │ raciocínio          │
│ skills (disclosure)         │            │ argumentos de tool  │
│ memória (L3 diária + L4)    │  ──modelo─▶ │ resposta final      │
│ RAG (rag_top_k trechos)     │            └────────────────────┘
│ definições de ferramentas   │
│ histórico + mensagem        │   rodada 1 → tool → rodada 2 → tool → rodada 3 → responde
└─────────────────────────────┘   (o contexto CRESCE a cada rodada: resultados entram nele)

Memória e RAG não são de graça: adicionam tokens de entrada. Mas é um trade explícito — contexto certo melhora a qualidade da resposta e evita rodadas extras de esclarecimento. O objetivo não é cortar contexto às cegas; é saber exatamente quanto ele custa e enxugar onde ele não paga o próprio peso.

Uma conta de exemplo, rodada a rodada

Números ilustrativos, num modelo econômico a US$ 0,40 por milhão de tokens de entrada e US$ 1,60 por milhão de saída (é o custo catalogado que a plataforma usa para calcular o cost_usd). Um turno com duas chamadas de ferramenta — três rodadas de modelo:

rodada  entrada   saída   observação
  1     6.000     120     lê o contexto, decide chamar brain_search
  2     6.400     140     resultado da tool entrou no contexto (+400 in)
  3     6.900     680     mais um resultado + a resposta final (saída maior)
────────────────────────────────────────────
total  19.300    940     tokens

custo = 19.300/1e6 × US$0,40  +  940/1e6 × US$1,60
      = US$ 0,00772  +  US$ 0,00150  =  US$ 0,0092

Repare que a entrada domina a conta (19.300 vs 940 tokens) justamente porque o contexto é recontado três vezes — e é por isso que enxugar o contexto e limitar as rodadas mexe mais no custo do que encurtar a resposta. Uma completion única com o mesmo contexto custaria cerca de um terço disso.

Medido, não estimado: cost_usd em cada execução

A maioria das equipes descobre o custo do agente na fatura do provedor, 30 dias tarde demais — e agregado, sem saber qual agente, qual modelo ou qual dia estourou. No Catcher Agents, cada execução grava o próprio custo: tokens de entrada, tokens de saída e o cost_usd calculado com o preço catalogado do modelo usado. Por run, não por amostragem.

O Console agrega esse dado em três eixos — por agente, por modelo e por dia — com janelas de 7, 30 e 90 dias. É o suficiente para responder as perguntas que importam: qual agente consome mais, qual modelo está fazendo trabalho barato a preço caro, em que dia o consumo dobrou. E dentro do chat, o inspetor de custo mostra o que cada turno custou, com o prompt e as rodadas à vista.

O mesmo dado está na API. O custo de um turno específico sai em GET /v1/agents/{id}/runs/{run_id} (o corpo do POST …/messages traz o run_id, mas não o custo — ele fica no run):

{
  "id": "9f2c…", "model": "gpt-5.4-mini", "status": "completed",
  "usage": { "input_tokens": 19300, "output_tokens": 940, "total_tokens": 20240 },
  "cost_usd": 0.0092, "rounds": 3, "duration_ms": 26600,
  "started_at": "2026-07-02T01:00:00Z"
}

E o agregado da conta em GET /v1/agents/usage?days=30, já quebrado por agente, por modelo e por dia:

{
  "usage": {
    "total_runs": 2515, "total_tokens": 70563496, "total_cost_usd": 32.37,
    "by_agent": [ { "label": "Atendimento", "runs": 904, "cost_usd": 18.50, "…": "…" } ],
    "by_model": [ { "label": "gpt-5.4-mini", "…": "…" } ],
    "by_day":   [ { "date": "2026-07-01", "runs": 120, "cost_usd": 1.44 } ]
  },
  "days": 30
}

Budget com trava dura: HTTP 402

Medir resolve metade do problema; a outra metade é o teto. O budget mensal da conta é definido em PUT /v1/agents/budget ({ monthly_budget_usd, alert_pct }); a leitura em GET /v1/agents/budget devolve também o gasto do mês (month_to_date_usd), o percentual e o state (ok | warn | exceeded). O cap de um agente é outro campo, monthly_budget_usd, na configuração daquele agente. Quando o acumulado correspondente bate no teto, a próxima execução não roda: a API responde HTTP 402 — BUDGET_EXCEEDED no nível da conta, AGENT_BUDGET_EXCEEDED no nível do agente — e o run para ali, antes de gerar um centavo novo.

Isso é diferente de um alerta. O alert_pct muda o state para warn quando você chega perto do teto — útil para avisar — mas o 402 é a trava determinística: o custo nunca escapa silenciosamente enquanto ninguém olha o dashboard. Retomar é uma decisão explícita do operador: subir o budget ou esperar a janela mensal virar. Trate o 402 como um estado do produto ("assistente pausado por orçamento"), não como erro genérico.

Como não estourar o orçamento

Cinco práticas que seguram a conta sem degradar o produto:

• Escolha o modelo por agente (model), não por padrão. O catálogo curado cobre 11 provedores (OpenAI, Anthropic, Google, xAI, Groq, Mistral, DeepSeek, Cerebras e outros) com o preço de cada modelo catalogado. Agente de triagem e FAQ pede modelo rápido e barato; agente que raciocina sobre contratos pede modelo forte. A diferença entre os dois é ordens de magnitude, e trocar é um campo de config.
• Limite max_tokens e max_rounds_per_run. O teto de saída (max_tokens, clamp 0..64000) evita respostas-ensaio; o teto de rodadas (max_rounds_per_run, default 20, clamp 1..50) evita loops de ferramenta que multiplicam chamadas de modelo. Os dois são knobs do agente.
• Calibre o contexto de RAG (rag_top_k) e meça rag_qa. Menos trechos recuperados (rag_top_k, default 5) significa menos tokens por rodada, mas pode custar recall. O modo qa_first atual combina cards destilados com chunks do corpus — não substitui automaticamente um pelo outro —, então ele melhora prontidão sem prometer redução de contexto. Compare qualidade e tokens no seu corpus.
• Olhe as janelas de 7/30/90 dias por agente e por modelo. Outliers ficam visíveis: o agente que consome 10x a média, o dia em que o custo dobrou. Sem medição por execução, isso só aparece na fatura.
• Dê budget próprio a agentes experimentais. Um agente novo em teste, com monthly_budget_usd baixo no próprio agente, não compromete o resto da conta se algo sair do controle.

Quem paga a conta de LLM hoje

Transparência sobre o modelo atual: hoje quem paga os provedores de LLM é a plataforma — você cria e roda agentes sem plugar chave própria, e o consumo aparece medido em USD, execução por execução. BYOK (usar as suas próprias chaves de provedor) está planejado para o tier Business. Nos dois modelos, a mecânica de controle é a mesma: cost_usd por execução, budget com trava 402.

Perguntas frequentes

O que faz o custo de um agente de IA variar tanto?

Três multiplicadores: o preço do modelo (que varia ordens de magnitude entre modelos), o tamanho do contexto de entrada (system prompt, skills, memória, RAG, ferramentas e histórico — reenviado a cada rodada) e o número de rodadas do turno (cada chamada de ferramenta adiciona uma chamada de modelo). A mesma pergunta pode custar 100x mais dependendo dessas três escolhas.

Como o Catcher Agents mede o custo de cada execução?

Cada run grava tokens de entrada, tokens de saída e o cost_usd calculado com o preço catalogado do modelo usado. O Console agrega por agente, por modelo e por dia, com janelas de 7, 30 e 90 dias — medição real por execução, não estimativa por amostragem.

O que acontece quando o budget estoura?

A próxima execução não roda: a API responde HTTP 402 e o run é bloqueado antes de gerar custo novo. O budget é mensal e pode ser definido por conta ou por agente. É uma trava dura, não um alerta — o custo não continua correndo enquanto ninguém está olhando.