Gerir custos

Este guia mostra como ver quanto custam as execuções de agentes e como limitar os gastos de uma execução autónoma.

Como são registados os custos

Cada execução de agente escreve um registo de execução com os tokens de entrada, os tokens de saída, os tokens de raciocínio, os tokens de leitura de cache e de escrita de cache, um custo estimado em cêntimos e o custo dos subagentes que lançou.

Os preços vêm do catálogo models.dev, que serve apenas para enriquecer a lista de modelos com o preço e a janela de contexto — nunca como fonte de identificadores de modelos. Um modelo que o catálogo não consegue cotar fica registado como $0 e as execuções de custo zero são excluídas do resumo Uso e custo. Um modelo Ollama local não mostra, por isso, gasto nenhum, embora as suas contagens de tokens continuem a ser registadas. Um plano de tarifa fixa (kimi-code, uma subscrição Claude) fica na mesma apenas quando o catálogo não tem preço para o modelo servido; se tiver, a execução é estimada com esses valores mesmo assim. Numa cadeia de fallback, a execução é cotada em função do modelo que a serviu de facto, e não daquele que foi pedido.

Ver quanto está a gastar

Observabilidade → Resumo

Chega-se lá pelo rodapé da barra lateral → Observabilidade. Abre-se primeiro o separador Uso (totais de tokens desde sempre); mude para Resumo — o segundo separador — para a principal superfície de custos:

Um seletor de intervalo de tempo: últimas 24 horas, últimos 7 dias, últimos 30 dias ou desde sempre
Filtros facetados por agente, modelo, estado e função, em forma de chips que se podem dispensar
Uma faixa de KPI: execuções totais, custo total, taxa de erro, taxa de cache, tokens por segundo, latência média e tempo até ao primeiro token, cada um com a variação face ao período anterior (oculta em «Desde sempre»)
Gráficos de atividade e de custos, mais um detalhe Custo por função que reparte o gasto entre o agente principal, os seus subagentes e o seu consultor
Uma tabela por agente ordenada por custo, com os dez primeiros e um botão para mostrar tudo. Tocar numa linha filtra todas as outras superfícies para esse agente
O registo de execução detalhado, que fixa uma gaveta de transcrição para a execução selecionada

Definições → Servidor → Fornecedores de modelos

O cartão Uso e custo nesta página mostra os gastos observados dos últimos sete dias como um valor único em dólares, com um detalhe por fornecedor e, quando um fornecedor o publica, o tempo que falta até ao reinício da próxima janela de quota.

As execuções de um único agente

Definições → Espaço de trabalho → Agentes → selecionar um agente → Registos lista as suas execuções com o estado, a duração, as horas de início e de conclusão, o PID e o adaptador. Este separador não mostra custos — para isso, use a tabela por agente em Observabilidade → Resumo.

Limitar uma execução autónoma

Dois comandos slash, escritos no compositor de um espaço, são as únicas execuções com um limite de gastos:

/goal ship the auth refactor --budget 20
/loop keep the flaky tests green

Cada segmento de uma execução /goal ou /loop para quando o seu gasto cotado atinge 500 cêntimos ($5.00). Aos 80% desse valor, o ciclo começa por orientar o modelo a terminar e a deixar uma passagem limpa, para não morrer a meio da tarefa.
Um objetivo durável completo está limitado a 5000 cêntimos ($50.00), a menos que passe --budget <dollars>. O supervisor distribui o orçamento restante do objetivo por cada segmento, pelo que um orçamento explícito nunca é excedido por um segmento inteiro.
--days N acrescenta um prazo de relógio e --max N um teto de número de execuções. Ambos são opcionais; sem eles, o objetivo é limitado apenas pelo custo.
Um objetivo que atinge o seu prazo termina em budgetExhausted e só pode ser retomado aumentando o orçamento.

Como o limite se baseia em preços, um modelo que o catálogo não consegue cotar nunca o atinge. Uma execução dessas é limitada, em vez disso, pela proteção contra ciclos viciosos por repetição, pela desistência do supervisor ao fim de três falhas consecutivas e por si.

Uma mensagem num espaço, uma menção com @ ou um passo de pipeline não têm limite de gastos. A execução termina quando o modelo para, quando a interrompe ou quando a proteção contra ciclos viciosos a orienta.

Reduzir o consumo de tokens

Compactar uma conversa longa

Escreva /compact no compositor do espaço. O comando é intercetado no lado do cliente e nunca chega à transcrição; o servidor dobra o histórico mais antigo num resumo ancorado e a conversa continua sobre o contexto compactado.

A compactação é recusada enquanto um agente está a meio de um turno e quando não há nada suficientemente antigo para dobrar. O harness integrado também compacta por iniciativa própria à medida que o histórico se aproxima da janela de contexto do modelo.

Escolher o nível de esforço de forma deliberada

O Esforço de raciocínio de um agente (Definições → Espaço de trabalho → Agentes) oferece os níveis que o modelo selecionado publicar. Os níveis mais altos gastam mais tokens de raciocínio. Reserve os níveis mais altos para o trabalho que precisa deles.

Escolher o modelo por agente

O modelo é um campo por agente, pelo que um agente de formatação ou de triagem pode correr num modelo barato enquanto um agente de arquitetura corre num modelo caro. Filtre a tabela por agente em Observabilidade → Resumo por modelo para ver que combinação lhe está de facto a custar dinheiro.

Procurar execuções com contagens de tokens desproporcionadas

Abra o registo de execução do Resumo (as 50 execuções filtradas mais recentes) e a gaveta de transcrição em qualquer coisa fora do normal. As causas habituais são um prompt de sistema ou uma persona demasiado longos, contexto que devia ter sido compactado e uma tarefa que devia ter sido várias tarefas mais pequenas.

O que acontece se um orçamento for definido por fora

Para sermos exaustivos, se monthlyBudgetCents ou uma política de orçamento forem escritos diretamente numa linha de agente:

Os orçamentos são avaliados depois de a execução terminar, e não antes do despacho. Um ouvinte na conclusão da execução compara o gasto do agente no mês até à data com o seu teto.
Ultrapassar o limiar suave (80% por predefinição) regista um incidente de aviso e emite um evento BudgetThresholdCrossed ao qual pode associar um disparador de pipeline.
Esgotar o orçamento regista um incidente rígido, emite o mesmo evento e muda o estado do ciclo de vida do agente para paused.
O bloqueio de pré-despacho existe, mas só é consultado pelo reaper de execuções órfãs e pelo reconciliador de tickets encalhados ao agendar a recuperação — um despacho normal nunca lá chega e nada no percurso do despacho verifica o estado paused. O único sinal visível é o distintivo do ciclo de vida no organigrama.

Guias relacionados

Conceitos relacionados

Ciclo de vida do despacho de agentes