Por que caps existem
Agentes de IA têm uma habilidade incômoda: gastar muito rápido. Um prompt ambíguo, um loop não previsto, uma integração que retorna sempre erro mas o agente tenta de novo — qualquer um desses cenários pode queimar Stars em minutos. Caps são tetos que você configura antes do gasto, garantindo que mesmo na pior das hipóteses o consumo fica controlado.Os quatro níveis de proteção
O Apollo Space aplica caps em camadas. Antes de cada chamada cobrável, o sistema verifica:1. Saldo da carteira
A proteção fundamental — se a carteira está zerada, nenhuma nova
chamada é autorizada. Você pode operar livremente desde que o
saldo seja positivo.
2. Teto mensal por organização
Mesmo com saldo, você pode definir um teto de gasto mensal
pra org inteira. Ao atingir, todas as chamadas pagas param até
o próximo ciclo (ou até você bumpar o teto).
3. Teto diário por agente
Limita quanto cada agente pode gastar por dia. Útil pra
evitar que um único agente em loop consuma o orçamento do dia
todo.
4. Teto mensal por usuário × agente
A combinação mais granular — quanto o usuário X usando o
agente Y pode gastar no mês. Útil em times grandes onde você
quer alocar orçamento por pessoa.
Como configurar
Tudo no painel Settings → Caps de gasto dentro do app.Cap por org
Configurado uma vez pelo owner/admin da org. Costuma ser re-avaliado a cada poucos meses conforme o uso real evolui.Cap por agente
Configurado por agente ao criar/editar a persona. Defaults sensíveis são aplicados automaticamente (você não precisa configurar do zero); customizar só quando o default não cabe.Cap por usuário × agente
Configurado opcionalmente pelo admin. Não precisa preencher pra todos os pares — só pra usuários específicos que você quer limitar explicitamente (ex.: um intern que precisa de boundary, um agente caro que só pessoas autorizadas usam).Precedência
Os 4 níveis são checados em ordem. A primeira proteção que dispara bloqueia — as próximas nem são avaliadas. Exemplo: se o saldo está zerado, não importa se o teto da org tem espaço ou se o usuário ainda tem cota — a chamada é bloqueada pelo nível 1. Isso significa que você não precisa configurar todos os 4 níveis. O nível 1 (saldo) já te protege da pior hipótese; os outros são ajustes finos pra casos específicos.O que o usuário vê quando um cap dispara
Quando uma chamada é bloqueada por cap, o agente:- Para a execução imediatamente (não tenta de novo)
- Surface uma mensagem clara no chat indicando qual cap foi atingido (ex.: “Limite diário deste agente atingido — você pode aumentar em Settings → Caps”)
- Sugere a ação corretiva (subir o cap, esperar o próximo ciclo, trocar pra outro agente)
Audit
Toda vez que um cap dispara, fica registrado no histórico de eventos da org com:- Qual cap (saldo / org / agente / user×agente)
- Qual valor estava configurado
- Quanto da chamada teria custado
- Quem disparou (qual user + qual agente)
- Timestamp
Estratégia recomendada
Pra times começando:Confie no saldo + bônus inicial
Não configure nada por agora. O bônus inicial é generoso o
suficiente pra exploração tranquila.
Quando virar operação real, adicione cap por agente
Defina um teto diário pros agentes mais usados (Marcus, Athena).
Default razoável — você ajusta depois conforme o uso real.
Quando passar de 5 usuários ativos, adicione cap por org
Um teto mensal pra org inteira evita surpresa no final do mês.
Calcule baseado em 70-80% do crédito mensal do seu plano.
Próximos passos
Stars — visão geral
Como funciona a carteira que os caps protegem.
Planos e pacotes
Como dimensionar o saldo + buy avulso.
Agentes
Cada agente respeita os caps automaticamente — sem precisar
código adicional.