`ai.reserva` → `ai.usage` → `ai.reserva_liquidada`; teto

Selo de estado: Preview (teto atual do produto) · Curso ACD-430 — Governança de IA: custo, egress, LGPD e aprovação humana · Aula 3 de 7 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai configurar teto e ler ledger — percorrer o ciclo reserva → liquidação evento por evento, saber qual deles é dinheiro de verdade e explicar o que acontece com o produto no dia em que o teto estoura.

Vídeo#

Identificador no manifesto: acd-430-03-orcamento-reserva-liquidacao · duração-alvo 8 min · tela do produto: /auditoria.

Roteiro (capítulos):

00:00–01:00 — O problema: um laço de perguntas poderia sangrar o mês inteiro. A resposta não é um medidor, é um ledger.
01:00–03:00 — Os cinco eventos (ai.reserva, ai.usage, ai.reserva_liquidada, ai.reserva_cancelada, ai.blocked) e o padrão reserve-then-verify.
03:00–04:30 — O teto mensal por workspace (padrão R$ 50; zerado = sem teto), a reserva órfã que expira por TTL de 10 min e o fail-safe de infra (degraded).
04:30–06:00 — Preço, tokens e cache de prompt (~0,1× na releitura do contexto estável): por que a segunda pergunta sobre o mesmo painel é muito mais barata.
06:00–07:15 — Lendo em /auditoria e em /billing: achar o par pelo opId, somar o mês, configurar o % de aviso.
07:15–08:00 — O dia 20 da Aurora, erros comuns e o "faça você mesmo".

Conteúdo#

O ledger, não o medidor

O gasto de IA é controlado por um ledger sobre o registro de auditoria — append-only, sem tabela nova. Cada chamada escreve antes de gastar e fecha depois. Os cinco eventos:

Evento	Quando é gravado	Custo registrado
`ai.reserva`	Antes da chamada, com uma estimativa conservadora	a estimativa
`ai.usage`	Depois da chamada: custo real (tokens × preço do modelo, em R$) + resumo de egress	o custo real
`ai.reserva_liquidada`	Fecha o par da reserva — inclusive quando a chamada falha (libera o orçamento)	R$ 0
`ai.reserva_cancelada`	A reserva se cancela quando o verify detecta estouro	R$ 0
`ai.blocked`	A recusa por teto, para o admin ver a demanda barrada	R$ 0

A ordem importa: a linha de reserva é gravada e só depois o teto é verificado. É o padrão reserve-then-verify, e é ele que impede que N chamadas simultâneas furem o teto passando todas pelo mesmo check. Uma reserva que ficou órfã (o processo morreu no meio) expira por idade, com TTL de 10 minutos — não existe limpeza destrutiva, nem orçamento preso para sempre.

O teto, e o que ele não faz

O teto mensal por workspace é de R$ 50 por padrão; zerado significa sem teto. Quando o mês acumulado encosta no limite, a chamada é recusada com uma mensagem direta — "O limite de uso de IA deste mês foi atingido; fale com o administrador." — e o evento ai.blocked entra na trilha com custo R$ 0.

Fail-safe de infra: o teto nunca derruba a IA por acidente

Se a checagem do teto falhar (banco fora, timeout), a chamada é liberada e marcada degraded. Derrubar a IA inteira porque o Postgres piscou seria pior do que deixar passar uma chamada de centavos. "Bloqueado" só acontece quando o teto foi realmente atingido.

O custo de IA hoje é absorvido pelo plano — não é repassado por chamada —, e a IA analista depende do plano (a partir do Growth). Então o teto não é uma fatura: é um freio contra laço e abuso.

Preço, tokens e o cache de prompt

O preço vem de uma tabela interna por modelo (USD por milhão de tokens), convertida para BRL pelo câmbio corrente; modelo desconhecido cai num preço default conservador, nunca zero. A reserva é calculada por cima: entrada estimada pelo tamanho do prompt e precificada como gravação de cache (pior caso), saída por um orçamento fixo e generoso por capacidade, com piso de R$ 0,01.

O ganho grande vem do cache de prompt da Anthropic: o contexto estável (catálogo, schema, snapshot) é marcado como ponto de corte e relido a ~0,1× do preço nas chamadas seguintes. Na prática: a primeira pergunta sobre um painel é a caraça; da segunda à quinta, você paga uma fração. A separação entre tokens de leitura e de gravação de cache evita cobrança em dobro no cálculo.

Onde isso aparece no produto

/auditoria é a tela do ledger: filtre por ai. e você vê reserva, uso e liquidação em sequência, cada um com custo em R$ e o opId no detalhe. /billing é a tela do dinheiro: saldo, franquia do ciclo, extrato e o campo "% de aviso de saldo baixo" — esse, sim, self-service para o owner. O valor do teto mensal de IA é controle de plataforma hoje, não um campo do workspace.

Exemplo: o dia 20 da Aurora Varejo

A Aurora Varejo (plano Growth) está com o teto de IA ajustado em R$ 10 para a janela de treino. Durante o mês, Maria e Ana usam Q&A e narrativa; no dia 20, o acumulado chega a R$ 9,97 e Ana pede mais um insight sobre o painel de vendas. O que acontece: a ai.reserva é gravada (estimativa R$ 0,08), o verify soma consumo + reservas ativas, vê que estoura, grava ai.reserva_cancelada e ai.blocked — e Ana lê na tela "O limite de uso de IA deste mês foi atingido; fale com o administrador."

O que não acontece: nada mais quebra. O painel abre, o refresh roda, o relatório das 7h sai (sem a narrativa), o alerta de meta dispara e a anomalia diária continua rodando — todos determinísticos. Maria abre /auditoria, ordena por custo, vê que duas perguntas muito amplas consumiram quase metade do mês, e tem uma decisão informada para tomar: ajustar o teto ou orientar o time a perguntar com período e métrica definidos.

Erros comuns

Confundir reserva com cobrança. A reserva é uma estimativa conservadora que existe para segurar o lugar na fila do teto; o dinheiro é o ai.usage. Somar reserva + uso é contar o mesmo gasto duas vezes.
Achar que o teto estourado "derruba o produto". Só as capacidades com LLM recusam. O resto do produto não sente.
Ler ai.reserva_liquidada como um segundo gasto. Ela tem custo R$ 0: é o fechamento do par.
Esperar que uma chamada que falhou fique "presa" no orçamento. A liquidação é gravada mesmo na falha; e se nem isso der tempo, o TTL de 10 min resolve.
Tratar degraded como bloqueio. degraded significa "não consegui apurar, liberei" — o oposto de bloqueado.
Achar que o custo de IA vira item de fatura por chamada. Hoje é absorvido pelo plano.

O que esta capacidade NÃO faz, e em que estado está

O ledger não é um controle de crédito pré-pago por chamada, não emite fatura e não expõe um campo de teto por workspace na interface hoje. Ele também não mede o custo de dados (BigQuery) — esse tem outra guarda, o teto de bytes por consulta. O selo de C01.5 é Preview: o ledger atômico reserva→liquidação, a proveniência e o rate limit fail-closed são provados por testes; os valores de custo exibidos por evento são projeção (custo faturado em BRL não medido em produção).

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /auditoria no console):

Em /auditoria, filtre ai. nos últimos 7 dias e identifique, na sequência, uma ai.reserva e a ai.reserva_liquidada que a fecha.
Anote o opId do par e confirme que o ai.usage entre eles carrega o mesmo opId.
Compare os dois valores: a estimativa da reserva e o custo real do uso. Escreva por que a estimativa é maior.
Faça duas perguntas de Q&A sobre o mesmo painel, em sequência. ⚠️ Este passo consome orçamento de IA do workspace. Compare o custo real da primeira e da segunda e identifique o efeito do cache de prompt.
Em /auditoria, ordene os eventos de IA por custo e aponte a chamada mais cara do período — e por que ela foi cara (escopo? período? painel inteiro?).
Some o gasto de IA do mês corrente e calcule quantos % do teto de R$ 50 aquilo representa.
Em /billing, configure o % de aviso de saldo baixo e anote o valor em R$ que o aviso passa a vigiar.
Localize (ou provoque) um ai.blocked e confirme duas coisas: o custo registrado é R$ 0 e a mensagem na tela manda falar com o administrador.

Você terminou quando tiver um opId que casa ai.reserva ↔ ai.usage ↔ ai.reserva_liquidada anotado, a comparação de custo entre a primeira e a segunda pergunta sobre o mesmo painel, e o % do teto consumido no mês calculado pela sua própria soma.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

Capacidades ensinadas#

C01.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".