Como controlar custos de um agente de IA no VPS

Como evitar que um agente de IA sempre ativo gere custos elevados

O controlo de custos de um agente de IA num VPS (servidor privado virtual) depende de limites definidos antes de o agente arrancar, porque ninguém está a acompanhar o consumo enquanto ele é executado. Limite cada resposta com max_tokens, limite as iterações do ciclo no seu próprio código, coloque em cache a parte do prompt que nunca muda e registe os valores de utilização de cada resposta para identificar que tarefa consome mais. O aluguer do servidor tem um preço mensal fixo. A API do modelo é faturada por token, e um ciclo sem supervisão pode consumir tokens silenciosamente.

Isto pressupõe um agente que já existe e chama a Messages API a partir de um servidor que controla. Criar um agente de IA com Claude num VPS aborda a implementação propriamente dita.

Por que um agente sem supervisão tem uma estrutura de custos diferente

Uma sessão interativa tem uma pessoa presente. Quando o modelo segue um caminho errado ou lê um log com 40,000 linhas, a pessoa que o acompanha interrompe-o. Um agente sem supervisão não tem esse travão: executa até o loop terminar e, depois, um temporizador inicia-o novamente.

A frequência é o multiplicador que muitas pessoas ignoram. Um job agendado para cada cinco minutos executa 288 vezes por dia e cerca de 8,640 vezes por mês. Multiplique o custo de uma execução por esse número. Muitos agentes "always-on" não precisam de estar sempre ativos. Precisam de responder dentro de um determinado número de minutos, o que pode ser feito com um agendamento.

Um agente também paga por elementos que uma janela de chat não utiliza.

• As definições das ferramentas acompanham cada pedido. O system prompt do sistema de utilização de ferramentas custa 290 tokens no Claude Opus 4.8 com tool_choice de auto ou none, e 410 com any ou tool. A ferramenta bash acrescenta mais 325. Cada servidor MCP que anexar adiciona os seus schemas a esse volume; MCP significa model context protocol.
• Os resultados das ferramentas são tokens de entrada. Um comando que imprime 8,000 linhas coloca 8,000 linhas no pedido seguinte e em todos os pedidos seguintes desse turno.
• As páginas obtidas são tokens de entrada. Uma página Web média com 10 kB tem aproximadamente 2,500 tokens, e um PDF de investigação com 500 kB tem aproximadamente 125,000. max_content_tokens trunca apenas o texto, porque "aplica-se a conteúdo de texto, não a conteúdo binário, como PDFs". Limite um PDF com max_uses e allowed_domains.
• A pesquisa Web é cobrada por pesquisa, a $10 por 1,000 pesquisas, independentemente do número de resultados devolvidos. Uma pesquisa que falhe não é cobrada.

Nada disso é caro quando ocorre uma única vez. Tudo isso se torna caro 8,640 vezes.

Limites rígidos e limites flexíveis resolvem problemas diferentes

max_tokens é aplicado. É um limite rígido para a saída total de um pedido, incluindo o raciocínio e o texto da resposta. O Claude nunca ultrapassa esse limite, e o modelo não consegue ver o valor. Ao atingir o limite, é devolvido stop_reason: "max_tokens" e a resposta fica truncada. Para agentes, há uma particularidade: cada pedido num ciclo de utilização de ferramentas tem o seu próprio max_tokens. Por isso, o limite aplica-se a uma resposta, não à tarefa completa. Dez chamadas de ferramentas a 4,000 tokens correspondem a um limite de 40,000 tokens para a interação.

Um orçamento de tarefa é consultivo. task_budget fica dentro de output_config e informa o modelo de quantos tokens dispõe para todo o ciclo agêntico, contando o raciocínio, as chamadas de ferramentas, os resultados das ferramentas e a saída.

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,
)

"Os orçamentos de tarefas são uma indicação flexível, não um limite rígido." O Claude pode ultrapassar esse valor durante uma ação, mas o limite aplicado à saída continua a ser max_tokens. "A contagem decrescente só é visível para o modelo", e as respostas não incluem um campo com o orçamento restante. O valor mínimo aceite para task_budget.total é 20,000 tokens. Um valor inferior devolve um erro 400. Se o orçamento for demasiado pequeno para o trabalho, o modelo pode apresentar um comportamento semelhante a uma recusa. Nesse caso, reduz o âmbito da tarefa ou termina mais cedo.

Um detalhe gera custos em vez de os reduzir. Se o cliente diminuir task_budget.remaining em cada pedido de seguimento, o valor alterado invalida qualquer prefixo em cache que o contenha. Defina-o uma única vez, no primeiro pedido.

Os orçamentos de tarefas 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 os orçamentos de tarefas não se aplicam ao Claude Code. Por isso, uma sessão do Claude Code desanexada num tmux depende da gestão correta da sessão.

O terceiro limite existe na Claude Console. Dê ao agente o seu próprio workspace e defina um limite mensal de despesas e limites de taxa por minuto para esse workspace. "Não é possível definir limites no Default Workspace", e "os limites aplicados a toda a organização prevalecem sempre, mesmo quando a soma dos limites dos workspaces é superior". Adicione notificações de despesas para receber um alerta quando um limiar for atingido, antes de o limite ser ultrapassado.

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

A escolha do modelo é feita por tarefa. Em julho de 2026, por milhão de tokens, primeiro a entrada e depois a saída: Claude Fable 5 a $10 e $50, Claude Opus 4.8 e Opus 4.7 a $5 e $25, Claude Sonnet 5 a $3 e $15, Claude Haiku 4.5 a $1 e $5. O Sonnet 5 está temporariamente abaixo do preço anunciado, porque está em vigor a "Introductory pricing of $2/$10 per million input/output tokens ... through August 31, 2026". Uma etapa que apenas classifica linhas de log não precisa do Opus. Também não existe uma franquia gratuita para absorver um agendamento intenso, porque a Claude API não tem um nível gratuito além do pequeno crédito concedido no registo.

O esforço é a segunda variável. output_config.effort aceita low, medium, high, xhigh e max, e o valor predefinido é high, portanto definir high explicitamente equivale a não o definir. Um nível de esforço menor reduz mais do que o comprimento do raciocínio: a documentação indica que faz o Claude executar menos chamadas de ferramentas e combinar operações numa só. Num agente, essa é a maior poupança, porque uma chamada de ferramenta evitada corresponde a um pedido inteiro que deixa de ser feito.

O problema é que o esforço entra em conflito com a cache. Alterar o valor entre pedidos invalida o armazenamento em cache do prompt. No exemplo documentado, o pedido 2 informou cache_read_input_tokens: 3546; o pedido 3, com o esforço alterado de alto para médio, informou cache_creation_input_tokens de 3546 e cache_read_input_tokens de 0. Por isso, varie o esforço entre cargas de trabalho, nunca dentro da mesma conversa em cache. Para controlar a profundidade sem quebrar a cache, faça isso no prompt: uma linha como "Answer directly without deliberating." na mensagem de utilizador mais recente mantém os pontos de interrupção anteriores intactos.

Os tokens de raciocínio são cobrados às tarifas de saída e contam para max_tokens, razão pela qual uma resposta truncada muitas vezes significa que o raciocínio consumiu o orçamento. Consulte usage.output_tokens_details.thinking_tokens para ver o número. O que realmente compõe uma fatura de tokens do Claude detalha o cálculo.

Armazene o prefixo estável e pare de invalidá-lo por acidente

Uma escrita na cache custa 1.25 vezes o preço base dos tokens de entrada na cache de cinco minutos e 2 vezes na cache de uma hora. Uma leitura da cache custa 0.1 vezes esse valor. Por isso, «a utilização de cache compensa depois de apenas uma leitura da cache na duração de 5 minutos (escrita a 1.25x), ou depois de duas leituras da cache na duração de 1 hora (escrita a 2x)».

Uma linha explica por que isto é adequado para um agente sempre ativo: «A cache é atualizada sem custo adicional sempre que o conteúdo armazenado é utilizado.» Um job executado a cada dois minutos contra a cache de cinco minutos mantém o prefixo aquecido durante todo o dia com uma única escrita.

Há três formas de perder a cache sem perceber.

Um prefixo que muda. «Os prefixos da cache são criados pela seguinte ordem: tools, system e depois messages.» Qualquer alteração de bytes nessa ordem invalida tudo o que vem depois, e editar as definições das ferramentas invalida toda a cache. O erro clássico provocado pelo próprio utilizador é incluir um timestamp ou um run id no system prompt: cada pedido passa então a transportar um prefixo diferente, escreve uma entrada nova a 1.25x e não obtém qualquer leitura da cache. O sinal é usage.cache_read_input_tokens a 0 em chamadas com o mesmo aspeto. Mova o texto variável para a mensagem user mais recente.

Um prefixo demasiado curto. Cada modelo tem um comprimento mínimo que pode ser colocado em cache. Abaixo desse limite, o pedido é processado sem cache e «não é devolvido qualquer erro». Os valores incluem 1,024 tokens no Claude Opus 4.8 e no Claude Sonnet 5, e 4,096 no Claude Haiku 4.5. Por isso, mover um job de Sonnet para Haiku pode desativar a cache silenciosamente.

Uma conversação que ultrapassa o lookback. «A janela de lookback é de 20 blocos.» O sistema verifica no máximo 20 posições por breakpoint e depois para. No exemplo documentado, um turno que contém 35 blocos e tem um breakpoint no bloco 35 verifica os blocos 35 a 16. A entrada do turno anterior no bloco 15 fica fora da janela, pelo que não há hit. Um agente que acrescenta vários blocos de tool-use e tool-result por turno ultrapassa 20 blocos em dois ou três turnos. Tem quatro breakpoints por pedido, por isso reserve um para as mensagens recentes.

Envie à Batches API tudo o que puder esperar

"Todo o uso é cobrado a 50% dos preços padrão da API", tanto para a entrada como para a saída. O processamento em lote é assíncrono, "com a maioria dos lotes a terminar em menos de 1 hora", e os resultados ficam disponíveis quando todos os pedidos terminarem ou após 24 horas, consoante o que ocorrer primeiro. Isto é habitual, mas não é garantido.

Consulte processing_status até apresentar ended. Os pedidos que devolvam errored, canceled ou expired não são cobrados. Existe uma ressalva se utilizar um limite de despesa: "os lotes podem ultrapassar ligeiramente o limite de despesa configurado para o seu Workspace."

Os descontos acumulam-se. Como um lote pode demorar mais de cinco minutos, a documentação recomenda a cache de uma hora para lotes que partilhem contexto. Separe o trabalho: tudo o que uma pessoa ou um webhook aguarda permanece no caminho em tempo real; um resumo noturno ou a classificação dos logs do dia anterior deve ser enviado para um lote, a metade do preço.

Registe todos os campos de utilização de cada resposta no seu próprio armazenamento

Não é possível atribuir custos que nunca foram registados. Cada resposta informa quanto custou.

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,
}

Acrescente uma linha por chamada à API a um ficheiro JSON Lines, identificada pelo nome do job. Uma semana depois, poderá saber qual job gera custos e qual apenas parece ocupado. Monitorize cache_read: uma coluna de zeros é o erro de custos mais comum num agente autoalojado.

Um campo pode ser facilmente interpretado de forma errada. input_tokens conta apenas os tokens depois do último ponto de cache, portanto o tamanho real do prompt é total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Um agente que reporte input_tokens: 400 num prompt grande não é barato: o restante veio da cache.

Faça a contagem antes de enviar. A contagem de tokens é gratuita e os seus limites de taxa são separados dos limites de criação de mensagens. Por isso, use count_tokens para recusar um anexo demasiado grande, em vez de pagar para descobrir esse problema. O resultado é uma estimativa. Por isso, volte a medir para cada modelo e nunca reutilize uma contagem feita com o tokenizer de outro fornecedor. Claude Opus 4.7 e os modelos Opus posteriores, Claude Fable 5 e Claude Sonnet 5 usam um tokenizer mais recente que "produz aproximadamente 30% mais tokens para o mesmo texto". Claude Sonnet 4.6 e versões anteriores, incluindo Claude Haiku 4.5, usam o tokenizer anterior.

Para obter a visão autoritativa, a Admin API comunica a utilização em https://api.anthropic.com/v1/organizations/usage_report/messages e os custos em https://api.anthropic.com/v1/organizations/cost_report. Ambos requerem uma chave de administrador (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[]=. Existe uma limitação: "A Admin API não está disponível para contas individuais."

Esse último parâmetro é uma forma simples de atribuir custos: atribua a cada job a sua própria chave de API, filtre com api_key_ids[] e divida o relatório por chave com group_by[]=api_key_id. O filtro é plural e a dimensão de agrupamento é singular. Mantenha as chaves no ambiente, e não no código, tal como uma primeira aplicação Claude API num VPS as gere.

Limite o loop, porque mais ninguém o fará

Um número limitado de iterações não é opcional neste caso. O loop é seu, por isso 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 faz isso por si só: max_tokens limita uma resposta, e o modelo apenas é informado de um orçamento de tarefas. Um produto alojado interromperia a execução neste ponto, tal como o limite de chamadas de ferramentas do Claude numa única interação encerra uma sessão que fez chamadas em excesso. No entanto, um loop que escreveu por sua conta não tem esse mecanismo de proteção até lhe adicionar um.

Adicione um segundo mecanismo de proteção fora do processo. Execute o job através de um temporizador do systemd em vez de usar um processo permanente, e defina RuntimeMaxSec= na respetiva unidade de serviço. Com RuntimeMaxSec=600, uma execução bloqueada é terminada após dez minutos, em vez de continuar indefinidamente até reparar no problema. Executar um programa como serviço e temporizador do systemd explica os próprios ficheiros de unidade. Consulte o que uma execução fez com journalctl -u triage-agent.service --since "1 hour ago".

Limite também as tentativas, porque um handler que tenta novamente sem fim cobra cada tentativa. Um erro 429 ou 500 justifica algumas tentativas com backoff. Um erro 400 não justifica nenhuma, porque o mesmo pedido falhará da mesma forma.

O controlo de custos de um agente de IA começa pela leitura dos seus próprios números

Ninguém pode dizer quanto custa um agente sempre ativo, porque o custo corresponde aos tokens por execução multiplicados pelo número de execuções por dia, e ambos os valores dependem de si. Execute-o uma vez, leia a linha de utilização que registou e multiplique-a pelo seu agendamento. Consulte o relatório de custos dois dias depois e compare-o com esse cálculo. Quando os dois valores não coincidem, a diferença deve-se quase sempre a uma cache que não funcionou ou a um loop que executou durante mais tempo do que o previsto.

Isto pressupõe uma chave de API, porque o agente é o seu próprio programa a chamar a Messages API. Para o seu trabalho interativo, qual plano Claude se adequa à sua forma de trabalhar explica a parte da subscrição. Todos os preços e limites foram verificados na documentação da Anthropic em julho de 2026. Consulte novamente a página de preços antes de elaborar um orçamento.

FAQ

Quanto custa executar um agente de IA sempre ativo numa VPS?

Existem duas faturas, mas apenas uma é previsível. O servidor tem um preço mensal fixo. A API do modelo é faturada por token, pelo que o custo corresponde ao que uma execução consome multiplicado pela frequência de execução. A Anthropic não publica nenhum valor para um agente sempre ativo alojado no próprio servidor, por isso trate qualquer valor indicado como uma estimativa. Registe usage de uma execução real e multiplique pelo seu agendamento.

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

max_tokens é aplicado e invisível para o modelo. Limita a saída de um pedido, incluindo o raciocínio, e atingi-lo gera stop_reason: "max_tokens". Um orçamento de tarefa funciona ao contrário: o modelo recebe esse número e ajusta o ciclo agêntico de acordo com ele, mas "Os orçamentos de tarefas são uma indicação flexível, não um limite rígido" e o limite aplicado continua a ser max_tokens.

Porque é que cache_read_input_tokens é sempre zero para o meu agente?

Porque o prefixo muda entre pedidos ou é demasiado curto para ser colocado em cache. A causa habitual é um carimbo de data/hora ou um ID de execução interpolado no prompt do sistema: a cache usa o prefixo como chave, pelo que qualquer alteração de bytes invalida tudo o que vem depois. Alterar as definições das ferramentas ou o valor de effort produz o mesmo efeito. Caso contrário, o problema é o tamanho, porque os prompts mais curtos não são colocados em cache e nenhum erro é devolvido.

Como impeço um agente de IA de entrar num ciclo infinito?

Conte as iterações no código do ciclo e pare num máximo fixo, porque max_tokens limita uma resposta e um agente produz muitas. Adicione um limite de tempo de relógio externo ao processo: inicie a tarefa a partir de um temporizador systemd com RuntimeMaxSec= definido, para que uma execução bloqueada seja terminada conforme o agendamento. Limite também as tentativas, porque um ciclo de novas tentativas fatura cada tentativa.

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

O limite de gastos documentado aplica-se ao workspace e não à chave, por isso atribua ao agente um workspace próprio e limite aí os gastos mensais. "Não é possível definir limites no Default Workspace". Adicione notificações de gastos para receber primeiro um alerta quando um limiar for atingido. Para atribuir os custos, emita uma chave própria para cada tarefa e agrupe depois o relatório de utilização com group_by[]=api_key_id.