Como controlar custos de agentes IA em VPS

Como evitar gastos excessivos com um agente de IA sempre ativo

O controle de custos de um agente de IA em um VPS (virtual private server) depende de limites definidos antes da execução, pois não há monitoramento manual durante o processo. Defina um limite para cada resposta com max_tokens, limite as iterações do loop no seu código, faça cache da parte estática do prompt e registre o uso de cada resposta para identificar o custo por tarefa. O aluguel do servidor tem preço mensal fixo. A API do modelo é cobrada por token, e um loop sem supervisão pode consumir tokens rapidamente.

Este guia assume que você já possui um agente que utiliza a Messages API a partir de um servidor próprio. Construindo um agente de IA com Claude em um VPS aborda a estrutura do sistema.

Por que um agente unattended possui um perfil de custo diferente

Uma sessão interativa possui um humano. Quando o modelo segue um caminho errado ou lê um log de 40.000 linhas, a pessoa monitorando interrompe o processo. Um agente unattended não possui esse freio: ele executa até o fim do loop, e então um timer o reinicia.

A frequência é o multiplicador que as pessoas ignoram. Um job com agendamento de cinco minutos roda 288 vezes por dia e cerca de 8.640 vezes por mês. O custo de uma única execução deve ser multiplicado por esse valor. Muitos agentes "always-on" não precisam estar ativos o tempo todo. Eles precisam responder dentro de um limite de minutos, o que define um agendamento.

Um agente também gera custos que uma janela de chat não gera.

• Tool definitions são enviadas em cada request. O system prompt de tool-use custa 290 tokens no Claude Opus 4.8 com tool_choice de auto ou none, e 410 com any ou tool. A tool bash adiciona mais 325. Cada MCP server que você anexar adiciona seus schemas a esse peso; MCP é o model context protocol.
• Tool results são input tokens. Um comando que imprime 8.000 linhas insere essas 8.000 linhas na próxima request, e em todas as requests subsequentes daquele turno.
• Páginas carregadas são input tokens. Uma página web média de 10 kB tem aproximadamente 2.500 tokens e um PDF de pesquisa de 500 kB tem aproximadamente 125.000. O max_content_tokens trunca apenas conteúdos de texto, pois "aplica-se a conteúdo de texto, não a conteúdo binário como PDFs". Use max_uses e allowed_domains para PDFs.
• Web search é cobrado por busca, a $10 por 1.000 buscas, independentemente do número de resultados retornados. Buscas que resultam em erro não são cobradas.

Nada disso é caro em uma única execução. Tudo isso é caro 8.640 vezes.

Hard ceilings e soft ceilings resolvem problemas diferentes

max_tokens é imposto. É um limite rígido para o output total de uma requisição, somando o texto de pensamento e a resposta. O Claude nunca gera além dele, e o modelo não consegue ver esse número. Atingir esse limite resulta em stop_reason: "max_tokens" e uma resposta truncada. O problema para agentes: cada requisição em um loop de tool-use possui seu próprio max_tokens, limitando apenas uma resposta e não a tarefa completa. Dez chamadas de ferramenta com 4.000 tokens resultam em um teto de 40.000 tokens para o turno.

Um task budget é consultivo. O task_budget está contido no output_config e informa ao modelo quantos tokens ele possui para todo o loop de agente, contando pensamento, chamadas de ferramenta, resultados de ferramentas e output.

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["task-budgets-2026-03-13"],
    output_config={"task_budget": {"type": "tokens", "total": 64000}},
    messages=messages,
)

"Task budgets são uma dica suave, não um limite rígido." O Claude pode exceder um durante uma ação, e o limite imposto de output continua sendo max_tokens. "A contagem regressiva é visível apenas para o modelo", e as respostas não possuem um campo de orçamento restante. O task_budget.total mínimo aceito é de 20.000 tokens; valores menores retornam um erro 400. Um orçamento muito pequeno para o trabalho produz um comportamento de recusa, fazendo com que o modelo reduza o escopo da tarefa ou pare precocemente.

Um detalhe gera custo em vez de economia. Se o seu cliente decrementar o task_budget.remaining em cada requisição de follow-up, o valor alterado invalida qualquer prefixo em cache que o contenha. Defina-o uma única vez, na primeira requisição.

Task budgets estão em beta no Claude Fable 5, Claude Opus 4.8 e Claude Opus 4.7. Claude Sonnet 5 e Claude Haiku 4.5 estão listados como Not supported, e task budgets não se aplicam ao Claude Code; portanto, uma sessão do Claude Code desvinculada no tmux depende da higiene da sessão.

O terceiro limite reside no Claude Console: atribua ao agente seu próprio workspace e, então, defina um limite de gastos mensal e limites de taxa por minuto. "Você não pode definir limites no Default Workspace", e "Limites de nível organizacional sempre se aplicam, mesmo que os limites do workspace somados sejam maiores". Adicione notificações de gastos para que um alerta de limite seja enviado antes que o teto seja atingido.

Escolha de modelo por tarefa e o que realmente altera o esforço

A escolha do modelo é uma decisão por tarefa. Em julho de 2026, por milhão de tokens (input e depois output): Claude Fable 5 custa $10 e $50, Claude Opus 4.8 e Opus 4.7 custam $5 e $25, Claude Sonnet 5 custa $3 e $15, Claude Haiku 4.5 custa $1 e $5. O Sonnet 5 está abaixo do preço de tabela por enquanto, pois "O preço introdutório de $2/$10 por milhão de tokens de input/output está em vigor até 31 de agosto de 2026". Uma etapa que apenas classifica linhas de log não precisa do Opus.

O esforço é o segundo fator de ajuste. output_config.effort aceita low, medium, high, xhigh e max, e o padrão é high, portanto definir high explicitamente é o mesmo que omiti-lo. Menos esforço reduz mais do que o comprimento do raciocínio: a documentação afirma que isso faz o Claude realizar menos chamadas de ferramenta (tool calls) e combinar operações em uma só. Em um agente, essa é a maior economia, pois uma chamada de ferramenta evitada é uma requisição inteira que nunca ocorre.

O problema é que o esforço conflita com o cache. Alterar o valor entre requisições invalida o prompt caching. No exemplo documentado, a requisição 2 reportou cache_read_input_tokens: 3546; a requisição 3, com o esforço alterado de high para medium, reportou cache_creation_input_tokens de 3546 e cache_read_input_tokens de 0. Portanto, varie o esforço entre diferentes cargas de trabalho, nunca dentro de uma mesma conversa com cache. Para controlar a profundidade sem quebrar o cache, faça isso no prompt: uma linha como "Responda diretamente sem deliberar." na mensagem mais recente do usuário mantém os breakpoints anteriores intactos.

Tokens de pensamento (thinking tokens) são cobrados pelas taxas de output e contam para o max_tokens, por isso uma resposta truncada geralmente significa que o raciocínio consumiu o orçamento. Leia usage.output_tokens_details.thinking_tokens para ver o número. O que realmente preenche uma fatura do Claude detalha o consumo.

Armazene o prefixo estável e evite quebras acidentais

Uma escrita em cache custa 1.25 vezes o preço base de input no cache de cinco minutos e 2 vezes no cache de uma hora. Uma leitura de cache custa 0.1 vezes, portanto "o cache compensa após apenas uma leitura para a duração de 5 minutos (1.25x escrita), ou após duas leituras para a duração de 1 hora (2x escrita)".

Uma frase explica por que isso é ideal para um agente sempre ativo: "O cache é atualizado sem custo adicional cada vez que o conteúdo em cache é utilizado." Um job executado a cada dois minutos contra o cache de cinco minutos mantém seu prefixo aquecido o dia todo com apenas uma escrita.

Três formas de perder o cache sem perceber.

Um prefixo que muda. "Os prefixos de cache são criados na seguinte ordem: tools, system, depois messages." Qualquer alteração de byte antes dessa ordem invalida tudo o que vem depois, e editar definições de ferramentas invalida todo o cache. O erro clássico causado pelo próprio usuário é um timestamp ou um run id no system prompt: cada requisição passa a carregar um prefixo diferente, realiza uma nova escrita a 1.25x e não obtém nenhuma leitura de volta. O sinal de alerta é usage.cache_read_input_tokens em 0 em chamadas visualmente idênticas. Mova o texto volátil para a mensagem de usuário mais recente.

Um prefixo muito curto. Cada modelo possui um comprimento mínimo para cache; abaixo disso, a requisição é processada sem cache e "nenhum erro é retornado". Os valores incluem 1,024 tokens no Claude Opus 4.8 e Claude Sonnet 5, e 4,096 no Claude Haiku 4.5, portanto, migrar um job de Sonnet para Haiku pode desativar o cache silenciosamente.

Uma conversa que excede a janela de busca. "A janela de busca (lookback window) é de 20 blocos." O sistema verifica no máximo 20 posições por breakpoint e então para. No exemplo documentado, um turno contendo 35 blocos com um breakpoint no bloco 35 verifica do bloco 35 ao 16; a entrada do turno anterior no bloco 15 fica fora da janela, portanto não há hit. Um agente que anexa vários blocos de tool-use e tool-result por turno ultrapassa 20 em dois ou três turnos. Você tem quatro breakpoints por requisição, então utilize um para as mensagens recentes.

Envie tarefas não urgentes para a Batches API

"Todo o uso é cobrado a 50% dos preços padrão da API", tanto para input quanto para output. O processamento em lote é assíncrono, "com a maioria dos batches finalizando em menos de 1 hora", com os resultados disponíveis quando todas as requisições terminarem ou após 24 horas, o que ocorrer primeiro. Isso é o comportamento típico, não uma garantia.

Faça o poll de processing_status até que o valor seja ended. Requisições que retornarem errored, canceled ou expired não são faturadas. Uma observação se você utiliza um limite de gastos (spend cap): "batches podem exceder levemente o limite de gastos configurado no seu Workspace."

Os descontos são cumulativos e, como um batch pode levar mais de cinco minutos, a documentação recomenda o uso de cache de uma hora para batches que compartilham o mesmo contexto. Portanto, divida o trabalho: qualquer tarefa que dependa de uma pessoa ou de um webhook deve permanecer no fluxo principal, enquanto resumos diários ou classificações de logs do dia anterior devem ser enviados para um batch com metade do preço.

Registre os campos de uso de cada resposta em seu próprio armazenamento

Você não pode atribuir gastos que não foram registrados. Cada resposta informa o custo gerado.

u = resp.usage
row = {
    "job": job_name,
    "model": resp.model,
    "uncached_input": u.input_tokens,
    "cache_write": u.cache_creation_input_tokens,
    "cache_read": u.cache_read_input_tokens,
    "output": u.output_tokens,
    "stop_reason": resp.stop_reason,
}

Adicione uma linha por chamada de API a um arquivo JSON-lines, com a tag do nome do seu job. Uma semana depois, você poderá identificar quais jobs geram gastos e quais apenas parecem ocupados. Monitore cache_read: uma coluna de zeros é o erro de custo mais comum em agentes self-hosted.

Um campo é fácil de interpretar incorretamente. input_tokens conta apenas os tokens após o último breakpoint de cache, portanto o tamanho real do prompt é total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Um agente que reporta input_tokens: 400 em um prompt grande não é barato: o restante veio do cache.

Conte antes de enviar. A contagem de tokens é gratuita e seus rate limits são separados da criação de mensagens; use count_tokens para recusar um anexo grande demais em vez de pagar para descobri-lo. O resultado é uma estimativa, portanto meça novamente por modelo e nunca reutilize uma contagem de um tokenizer de outro vendor. Claude Opus 4.7 e modelos Opus posteriores, Claude Fable 5 e Claude Sonnet 5 usam um tokenizer mais novo que "produz aproximadamente 30% mais tokens para o mesmo texto". Claude Sonnet 4.6 e anteriores, incluindo Claude Haiku 4.5, usam o anterior.

Para uma visão definitiva, a Admin API reporta o uso em https://api.anthropic.com/v1/organizations/usage_report/messages e o custo em https://api.anthropic.com/v1/organizations/cost_report. Ambos utilizam uma admin key (sk-ant-admin01-...) como x-api-key: $ANTHROPIC_ADMIN_KEY com anthropic-version: 2023-06-01, e aceitam bucket_width=1d, group_by[]=model e api_key_ids[]=. Uma limitação: "The Admin API is unavailable for individual accounts."

Esse último parâmetro é um truque de atribuição de baixo custo: atribua uma chave de API para cada job, filtre com api_key_ids[] e divida o relatório por chave com group_by[]=api_key_id. O filtro está no plural, a dimensão de agrupamento está no singular. Mantenha as chaves no ambiente em vez de no código, da forma como o primeiro app Claude API em um VPS as manipula.

Limite o loop, pois nada mais o fará

Um limite de iteração não é opcional aqui. O loop é seu, portanto o contador também é seu:

for step in range(MAX_STEPS):          # MAX_STEPS = 12, never "while True"
    resp = client.messages.create(...)
    if resp.stop_reason != "tool_use":
        break
else:
    log.warning("job %s hit MAX_STEPS=%d, giving up", job_name, MAX_STEPS)

Nenhum dos limites acima resolve o problema: max_tokens limita apenas uma resposta, e o modelo recebe apenas uma estimativa de orçamento de tarefa.

Coloque um segundo freio fora do processo. Execute o job através de um timer do systemd em vez de um processo permanente, e defina RuntimeMaxSec= na sua unit de serviço. Com RuntimeMaxSec=600, uma execução travada é encerrada após dez minutos em vez de rodar indefinidamente até que você perceba. Executar um programa como um serviço e timer do systemd aborda os arquivos de unit. Veja o que uma execução realizou com journalctl -u triage-agent.service --since "1 hour ago".

Limite também as tentativas de reprocessamento (retries), pois um handler que tenta infinitamente gera custos em cada tentativa. Um erro 429 ou 500 merece algumas tentativas com backoff. Um erro 400 não merece nenhuma, já que a mesma requisição falhará da mesma forma.

O controle de custos de agentes de IA começa com a análise dos seus próprios dados

Ninguém pode prever o custo de um agente sempre ativo, pois o custo é o número de tokens por execução multiplicado pelo número de execuções por dia, e ambos os valores dependem de você. Execute o agente uma vez, verifique a linha de uso registrada no log e multiplique pelo seu cronograma. Compare o relatório de custos dois dias depois com esse cálculo. Quando houver divergência, a causa quase sempre é um cache corrompido ou um loop que durou mais do que o esperado.

Isso assume o uso de uma API key, pois o agente é o seu próprio programa chamando a Messages API. Para uso interativo, qual plano do Claude se adapta ao seu fluxo de trabalho aborda o lado da assinatura. Todos os preços e limites aqui foram validados com a documentação da Anthropic em julho de 2026; portanto, revise a página de preços antes de elaborar um orçamento.

FAQ

Quanto custa rodar um agente de IA sempre ativo em um VPS?

Existem duas faturas e apenas uma é previsível. O servidor tem um preço mensal fixo. A API do modelo é cobrada por token, portanto o custo é o consumo de uma execução multiplicado pela frequência das execuções. A Anthropic não publica valores para um agente self-hosted sempre ativo, então trate qualquer valor citado como uma estimativa. Registre o usage de uma execução real e multiplique pelo seu cronograma.

Qual é a diferença entre max_tokens e um budget de tarefa?

O max_tokens é imposto e invisível para o modelo. Ele limita a saída de uma requisição, incluindo o pensamento, e atingir esse limite resulta em stop_reason: "max_tokens". Um budget de tarefa é o oposto: o modelo recebe o número e ajusta o loop agente com base nele, mas "Task budgets are a soft hint, not a hard cap" e o limite imposto continua sendo max_tokens.

Por que cache_read_input_tokens é sempre zero para o meu agente?

Porque o prefixo muda entre as chamadas ou é curto demais para o cache. A causa comum é um timestamp ou um run id interpolado no system prompt: o cache é baseado no prefixo, então qualquer alteração de byte invalida tudo o que vem depois. Alterar definições de ferramentas ou o valor de effort causa o mesmo efeito. Caso contrário, o motivo é o tamanho, já que prompts curtos não são armazenados em cache e nenhum erro é retornado.

Como eu impeço um agente de IA de entrar em loop infinito?

Conte as iterações no seu código de loop e pare em um máximo fixo, pois o max_tokens limita uma resposta e um agente faz várias. Adicione um limite de tempo real fora do processo: inicie o job via um timer do systemd com RuntimeMaxSec= configurado, para que uma execução travada seja finalizada no horário programado. Limite também as tentativas de reprocessamento (retries), pois um loop de retry gera cobrança em cada tentativa.

Posso definir um limite de gastos para uma única chave de API do Claude?

O limite de gastos documentado é por workspace e não por chave, portanto atribua ao agente um workspace próprio e limite o gasto mensal nele. "You cannot set limits on the Default Workspace". Adicione notificações de gastos para que um alerta seja enviado ao atingir um limite. Para atribuição de custos, emita uma chave para cada job e depois agrupe o relatório de uso com group_by[]=api_key_id.