> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apollospace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Caps de gasto

> Como travar tetos de uso por organização, por agente ou por usuário — antes do saldo estourar.

## 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:

<CardGroup cols={2}>
  <Card title="1. Saldo da carteira" icon="wallet">
    A proteção fundamental — se a carteira está zerada, nenhuma nova
    chamada é autorizada. Você pode operar livremente desde que o
    saldo seja positivo.
  </Card>

  <Card title="2. Teto mensal por organização" icon="building">
    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).
  </Card>

  <Card title="3. Teto diário por agente" icon="robot">
    Limita quanto **cada agente** pode gastar **por dia**. Útil pra
    evitar que um único agente em loop consuma o orçamento do dia
    todo.
  </Card>

  <Card title="4. Teto mensal por usuário × agente" icon="user-tag">
    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.
  </Card>
</CardGroup>

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

Nenhuma chamada paga acontece "silenciosamente" — o usuário sempre
sabe quando bateu num teto.

## 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

Útil pra entender padrões — se um cap está disparando muito, talvez
a configuração precise ajuste.

## Estratégia recomendada

Pra times começando:

<Steps>
  <Step title="Confie no saldo + bônus inicial">
    Não configure nada por agora. O bônus inicial é generoso o
    suficiente pra exploração tranquila.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Cap por user×agente só em casos específicos">
    Não default pra todo mundo. Use só quando faz sentido de governança
    (ex.: estagiário, agente premium).
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Stars — visão geral" icon="star" href="/pt/billing/stars">
    Como funciona a carteira que os caps protegem.
  </Card>

  <Card title="Planos e pacotes" icon="box" href="/pt/billing/plans-and-packs">
    Como dimensionar o saldo + buy avulso.
  </Card>

  <Card title="Agentes" icon="robot" href="/pt/concepts/agents">
    Cada agente respeita os caps automaticamente — sem precisar
    código adicional.
  </Card>
</CardGroup>