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 é imposto. É um limite rígido para a saída total de um pedido, incluindo o raciocínio e o texto da resposta. Claude nunca ultrapassa esse limite, e o modelo não consegue ver o valor. Ao atingir o limite, recebe stop_reason: "max_tokens" e uma resposta 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 inteira. 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 é indicativo. task_budget fica dentro de output_config e informa o modelo de quantos tokens dispõe para todo o ciclo agêntico, incluindo 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." Claude pode ultrapassar o orçamento durante uma ação, e o limite imposto à 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 é de 20,000 tokens. Um valor inferior devolve um erro 400. Um orçamento demasiado pequeno para o trabalho provoca um comportamento semelhante a uma recusa. Nesse caso, o modelo reduz o âmbito da tarefa ou para mais cedo.

Um detalhe aumenta os 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 vez, no primeiro pedido.

Os orçamentos de tarefas estão em beta no Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5 e Claude Haiku 5.5. 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 desligada no tmux depende da gestão correta da sessão.

O terceiro limite encontra-se na Claude Console: atribua ao agente o seu próprio workspace e defina um limite mensal de gastos e limites de taxa por minuto para esse workspace. "Não é possível definir limites no Default Workspace", e "os limites aplicáveis a toda a organização aplicam-se sempre, mesmo que a soma dos limites dos workspaces seja superior". Adicione notificações de gastos para receber um alerta quando um limiar for atingido, antes de o limite ser ultrapassado.

Escolha do modelo por trabalho e o que o nível de esforço realmente altera

A escolha do modelo é feita por trabalho. Em outubro de 2026, por milhão de tokens, primeiro a entrada e depois a saída: Claude Fable 5.1 e Fable 5 custam $10 e $50, Claude Opus 5.5 custa $4 e $20, Claude Opus 5, Opus 4.8 e Opus 4.7 custam $5 e $25, Claude Sonnet 5.5 e Sonnet 5 custam $2 e $10, Claude Haiku 5.5 custa $0.10 e $0.50 para prompts até 100,000 tokens ($0.50 e $2.50 acima desse limite, com os tokens em cache incluídos na contagem), e Claude Haiku 4.5 custa $1 e $5. A Anthropic vendeu inicialmente o Sonnet 5 a esse preço como tarifa introdutória, depois tornou-o o preço padrão e cancelou o aumento planeado para $3 e $15. Um passo que apenas classifica linhas de log não precisa do Opus.

Também não deve contar com a utilização gratuita para absorver uma agenda intensa. Além de o pequeno crédito que a Claude API concede no registo, a única franquia recorrente é o crédito mensal da API incluído nos planos Claude Max e Team: $100 no Max 5x, $200 no Max 20x e até $500 partilhados no Team, renovados em cada ciclo de faturação. Pode reclamá-lo após 7 dias num plano elegível e não é necessário um método de pagamento. O crédito cobre a Claude API, Managed Agents, o Agent SDK e o playground, mas não o Claude Code, e expira no fim de cada ciclo sem transitar para o seguinte. A utilização conta para o seu limite de gastos e, quando o crédito termina, os pedidos param, a menos que a organização também tenha créditos adquiridos.

O esforço é a segunda variável de controlo. output_config.effort aceita low, medium, high, xhigh e max, embora nem todos os modelos suportem todos os níveis. O padrão é high na maioria dos modelos e medium no Claude Opus 5.5 e no Claude Haiku 5.5. Definir explicitamente o valor padrão de um modelo equivale a omiti-lo. Um 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 várias operações em menos chamadas. Num agente, essa é a maior poupança, porque uma chamada de ferramenta evitada é um pedido completo que nunca chega a ser feito.

O problema é que o esforço entra em conflito com a cache. Alterar o valor de nível superior entre pedidos invalida o armazenamento em cache do prompt. No exemplo documentado com Claude Opus 5.5, o pedido 2 comunicou cache_read_input_tokens: 3546. O pedido 3 alterou o esforço de medium, o padrão desse modelo, para low e comunicou cache_creation_input_tokens de 3546 e cache_read_input_tokens de 0. Por isso, varie o esforço de nível superior entre cargas de trabalho, nunca dentro da mesma conversa em cache. Existem duas formas de alterar a profundidade sem quebrar a cache. No Claude Fable 5.1, Opus 5.5, Opus 5, Sonnet 5.5 e Haiku 5.5, uma alteração do esforço por mensagem (beta, cabeçalho mid-conversation-output-config-2026-07-01) define um novo nível e mantém intacto o prefixo em cache. Em qualquer modelo, também pode orientar o comportamento no prompt: uma linha como "Responda diretamente sem deliberar." na mensagem de utilizador mais recente mantém intactos os pontos de interrupção anteriores. No Claude Haiku 5.5, porém, essa frase não reduz o raciocínio de forma fiável.

Os tokens de raciocínio são faturados às tarifas de saída e contam para max_tokens. Por isso, uma resposta truncada significa muitas vezes 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 da Claude detalha como o contador é calculado.

Coloque em cache o prefixo estável e evite quebrá-lo por acidente

Uma gravação 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. Na maioria dos modelos, uma leitura da cache custa 0.1 vezes esse preço. Por isso, "a utilização de cache compensa após uma leitura da cache na duração de 5 minutos (gravação a 1.25x) ou após duas leituras da cache na duração de 1 hora (gravação a 2x)". Nos modelos mais recentes, as leituras são ainda mais baratas: 0.05 vezes no Claude Opus 5.5 e no Claude Sonnet 5.5, e 0.025 vezes no Claude Fable 5.1.

Uma linha explica por que isto é adequado para um agente sempre ativo: "A cache é atualizada sem custo adicional sempre que o conteúdo colocado em cache é 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 gravação.

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 anterior nessa ordem invalida tudo o que vem depois. A edição das definições das ferramentas invalida toda a cache. O erro clássico causado pelo próprio utilizador é incluir um timestamp ou um ID de execução no system prompt. Nesse caso, cada pedido transporta um prefixo diferente, grava uma entrada nova a 1.25x e não obtém nenhuma leitura da cache. O indicador é usage.cache_read_input_tokens a 0 em chamadas visualmente idênticas. Mova o texto variável para a mensagem de utilizador 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 são 512 tokens no Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5 e Haiku 5.5; 1,024 no Claude Opus 4.8 e Claude Sonnet 5; e 4,096 no Claude Haiku 4.5. Assim, mover um job do Sonnet 5 para o Haiku 4.5 pode desativar a cache silenciosamente.

Uma conversa que ultrapassa a janela de retrospetiva. "A janela de retrospetiva tem 20 blocos." O sistema verifica no máximo 20 posições por breakpoint e depois para. No exemplo documentado, um turno com 35 blocos e um breakpoint no bloco 35 verifica os blocos 35 a 16. A entrada do turno anterior, no bloco 15, fica fora da janela e, por isso, não há correspondência. Um agente que acrescenta vários blocos de utilização de ferramentas e de resultados de ferramentas por turno ultrapassa 20 blocos em dois ou três turnos. Há quatro breakpoints por pedido. Reserve um deles 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 indica 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 com o nome do job. Uma semana depois, poderá saber qual job gera custos e qual apenas parece ocupado. Monitorize cache_read: uma coluna só com zeros é o erro de custos mais comum num agente alojado localmente.

É fácil interpretar mal um campo. input_tokens conta apenas os tokens depois do último ponto de cache, pelo que o tamanho real do prompt é total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Um agente que indique input_tokens: 400 num prompt grande não é barato: o restante veio da cache.

Conte antes de enviar. A contagem de tokens é gratuita e tem limites de taxa separados dos da criação de mensagens. Por isso, use count_tokens para rejeitar um anexo demasiado grande, em vez de pagar para descobrir isso. O resultado é uma estimativa. Volte a medir por modelo e nunca reutilize uma contagem de outro tokenizer de outro fornecedor. Os modelos Claude 4.7 e posteriores, incluindo Claude Fable 5 e Claude Sonnet 5, usam um tokenizer mais recente que "produces approximately 30% more tokens for the same text". Claude Sonnet 4.6 e anteriores, incluindo Claude Haiku 4.5, usam o tokenizer anterior.

Para obter a informação autoritativa, a Admin API fornece 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 aceitam uma chave de administrador (sk-ant-admin01-...) como x-api-key: $ANTHROPIC_ADMIN_KEY com anthropic-version: 2023-06-01. O relatório de utilização aceita bucket_width=1d, group_by[]=model e api_key_ids[]=. O relatório de custos está disponível apenas por dia e agrupa por workspace_id ou description. Existe uma limitação: "The Admin API is unavailable for individual accounts."

Esse parâmetro api_key_ids[] é uma forma simples de atribuir custos: dê a cada job a sua própria chave da API, filtre o relatório de utilização com api_key_ids[] e divida-o por chave com group_by[]=api_key_id. O filtro está no plural, enquanto a dimensão de agrupamento está no singular. Mantenha as chaves no ambiente, e não no código, tal como uma primeira aplicação da Claude API numa VPS faz.

Limite o loop, porque mais nada o fará

Um limite para o número 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 recebe informação sobre um orçamento de tarefas. Um produto alojado pararia aqui, tal como o limite do Claude para chamadas de ferramentas numa única interação termina uma sessão que fez demasiadas chamadas. Um loop que escreveu por sua conta não inclui essa proteção até que a adicione.

Adicione uma segunda proteção fora do processo. Execute o trabalho através de um temporizador do systemd, em vez de manter um processo permanente, e defina um limite de tempo real na respetiva unidade de serviço. Um trabalho de temporizador normalmente é Type=oneshot, e RuntimeMaxSec= "não tem qualquer efeito em serviços Type=oneshot", por isso defina TimeoutStartSec=600 nessa unidade. Use RuntimeMaxSec=600 apenas numa unidade Type=simple. Em qualquer dos casos, uma execução bloqueada é terminada ao fim de dez minutos, em vez de continuar até que a detete. Executar um programa como serviço e temporizador do systemd explica os próprios ficheiros de unidade. Consulte o resultado de uma execução com journalctl -u triage-agent.service --since "1 hour ago".

Limite também as tentativas, porque um handler que tenta novamente sem fim fatura 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. Dois dias depois, compare o relatório de custos com esse cálculo. Quando os dois valores não coincidem, a diferença quase sempre resulta de uma cache com problemas ou de um ciclo que foi executado durante mais tempo do que esperava.

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 aborda a componente da subscrição. Todos os preços e limites aqui indicados foram verificados na documentação da Anthropic em outubro 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 despesas e apenas uma é previsível. O servidor tem um preço mensal fixo. A API do modelo é faturada por token, portanto 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 pelo próprio utilizador, portanto trate qualquer valor apresentado como uma estimativa. Registe usage de uma execução real e multiplique esse valor pelo seu agendamento.

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

max_tokens é aplicado e invisível para o modelo. Limita a saída de um pedido, incluindo o raciocínio, e atingir esse limite produz 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 "Task budgets are a soft hint, not a hard cap" e o limite aplicado continua a ser max_tokens.

Porque é que cache_read_input_tokens está sempre a zero para o meu agente?

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

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 real fora do processo: inicie o trabalho a partir de um temporizador systemd e defina TimeoutStartSec= numa unidade oneshot, ou RuntimeMaxSec= numa unidade simple, para que uma execução bloqueada seja terminada no horário previsto. Limite também as tentativas, porque um ciclo de novas tentativas gera custos em cada tentativa.

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

O limite de despesas documentado aplica-se ao workspace e não à chave, portanto atribua ao agente um workspace próprio e limite aí as despesas mensais. "You cannot set limits on the Default Workspace". Adicione notificações de despesas para receber primeiro um alerta quando um limiar for atingido. Para atribuição, emita uma chave própria para cada trabalho e agrupe depois o relatório de utilização com group_by[]=api_key_id.