Gerenciar custos

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

Como os custos são registrados

Cada execução de agente grava um log de execução com seus tokens de entrada, tokens de saída, tokens de raciocínio, tokens de leitura em cache e de gravação em cache, um custo estimado em centavos e o custo de todos os subagentes que ela gerou.

Os preços vêm do catálogo models.dev, que serve apenas para enriquecer a lista de modelos com preço e janela de contexto — nunca como fonte de ids de modelo. Um modelo que o catálogo não consegue precificar registra $0, e execuções de custo zero ficam fora do resumo Uso e custo. Um modelo Ollama local, portanto, não mostra gasto nenhum, embora suas contagens de tokens ainda sejam registradas. Um plano de tarifa fixa (kimi-code, uma assinatura Claude) só se comporta da mesma forma quando o catálogo não tem preço para o modelo servido; se tiver, a execução é estimada nessas tarifas de qualquer maneira. Em uma cadeia de fallback, a execução é tarifada com base no modelo que de fato a atendeu, e não no que foi solicitado.

Veja o que você está gastando

Observabilidade → Resumo

Acesse-a pelo rodapé da barra lateral → Observabilidade. A aba Uso abre primeiro (totais de tokens acumulados); mude para Resumo — a segunda aba — para chegar à 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, status e função, como chips dispensáveis
Uma faixa de KPIs: execuções totais, custo total, taxa de erro, taxa de cache, tokens por segundo, latência média e tempo até o primeiro token, cada um com uma variação em relação ao período anterior (oculto em “Desde sempre”)
Gráficos de atividade e de custo, além de um detalhamento de custo por função que divide os gastos entre o agente principal, seus subagentes e seu consultor
Uma tabela por agente ordenada por custo, com os dez primeiros e um botão para mostrar todos. Tocar em uma linha filtra todas as outras superfícies por esse agente
O log de execução granular, que acopla uma gaveta de transcrição para a execução selecionada

Configurações → Servidor → Provedores de modelos

O cartão Uso e custo desta página mostra os gastos observados dos últimos sete dias como um valor único em dólares, com um detalhamento por provedor e, quando o provedor publica essa informação, o tempo até a redefinição da próxima janela de cota.

As execuções de um único agente

Configurações → Espaço de trabalho → Agentes → selecione um agente → Registros lista suas execuções com status, duração, horários de início e conclusão, PID e adaptador. Esta aba não mostra custo — para isso, use a tabela por agente em Observabilidade → Resumo.

Limitar uma execução autônoma

Dois comandos slash, digitados no composer de um espaço, são as únicas execuções com teto 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 seu gasto precificado chega a 500 centavos ($5.00). A 80% disso, o loop primeiro orienta o modelo a encerrar e deixar uma passagem limpa, para que não morra no meio da tarefa.
Uma meta durável inteira tem teto de 5000 centavos ($50.00), a menos que você passe --budget <dollars>. O supervisor injeta o orçamento restante da meta em cada segmento, de modo que um orçamento explícito nunca é ultrapassado por um segmento inteiro.
--days N adiciona um prazo em tempo real e --max N um teto de número de execuções. Ambos são opcionais; sem eles, a meta é limitada apenas pelo custo.
Uma meta que atinge seu limite para em budgetExhausted e só pode ser retomada se o orçamento for aumentado.

Como o teto é precificado, um modelo que o catálogo não consegue precificar nunca o alcança. Uma execução assim é limitada, em vez disso, pela proteção contra repetição de loop infinito, pela desistência do supervisor após três falhas consecutivas e por você.

Uma mensagem em um espaço, uma menção com @ ou uma etapa de pipeline não tem teto de gastos. A execução termina quando o modelo para, quando você a interrompe ou quando a proteção contra loop infinito a orienta.

Reduzir o uso de tokens

Compactar uma conversa longa

Digite /compact no composer do espaço. O comando é interceptado no lado do cliente e nunca chega à transcrição; o servidor dobra o histórico mais antigo em um resumo ancorado, e a conversa continua no contexto compactado.

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

Escolher o nível de esforço de propósito

O Esforço de raciocínio de um agente (Configurações → Espaço de trabalho → Agentes) oferece os níveis que o modelo selecionado publicar. 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, então um agente de formatação ou de triagem pode ser executado em um modelo barato, enquanto um agente de arquitetura é executado em um caro. Filtre a tabela por agente em Observabilidade → Resumo por modelo para ver qual combinação está de fato custando caro.

Procurar execuções com contagens de tokens desproporcionais

Abra o log de execução do Resumo (as 50 execuções filtradas mais recentes) e a gaveta de transcrição em qualquer coisa fora do comum. As causas comuns são um prompt de sistema ou uma persona longos demais, contexto que já deveria ter sido compactado e uma tarefa que deveria ter sido várias tarefas menores.

O que acontece se um orçamento for definido fora do fluxo normal

Para ser completo: se monthlyBudgetCents ou uma política de orçamento for gravado diretamente em uma linha de agente:

Os orçamentos são avaliados depois que uma execução é concluída, e não antes do despacho. Um listener na conclusão da execução compara os gastos do agente no mês até a data com seu teto.
Cruzar o limite suave (80% por padrão) registra um incidente de aviso e dispara um evento BudgetThresholdCrossed no qual você pode pendurar um gatilho de pipeline.
Esgotar o orçamento registra um incidente grave, dispara o mesmo evento e muda o status de ciclo de vida do agente para paused.
O bloqueio pré-despacho existe, mas é consultado apenas pelo coletor de execuções órfãs e pelo reconciliador de tickets presos ao agendar uma recuperação — um despacho normal nunca o alcança, e nada no caminho de despacho verifica o status de pausa. O único sinal visível é o selo de ciclo de vida no organograma.

Guias relacionados

Conceitos relacionados

Ciclo de vida do despacho de agentes