🏗️ Arquitetura multi-tenant: isolamento real de dados
Multi-tenancy é a capacidade de um único deployment servir múltiplos clientes com isolamento garantido entre eles. Um cliente jamais pode ver ou afetar os dados de outro — nem via bug, nem via configuração errada.
🗄️ Estratégias de isolamento de banco de dados
Row-Level Security (RLS) — Recomendado
Melhor custo-benefícioPostgres RLS: toda query automaticamente filtrada por tenant_id via política de banco. Developer não pode esquecer o filtro — o banco garante.
CREATE POLICY tenant_isolation ON agent_runs USING (tenant_id = current_setting('app.tenant_id')::uuid);
Schema per Tenant — Maior isolamento
Alto custo operacionalSchema Postgres separado por tenant. Isolamento forte, mas migrations precisam rodar N vezes (um por tenant). Dificulta escala acima de centenas de tenants.
Database per Tenant — Isolamento máximo
Enterprise onlyBanco de dados separado por tenant. Isolamento total, compliance mais fácil de demonstrar. Custo elevado. Faz sentido apenas para clientes enterprise com requisitos regulatórios específicos.
🔑 Tenant context propagation
O tenant_id deve fluir por todo o stack — do request HTTP até o banco de dados. Qualquer ponto onde o tenant_id se perde é um potencial data leakage.
# Middleware que injeta tenant_id em cada request
class TenantMiddleware:
async def __call__(self, request, call_next):
tenant = await get_tenant_from_jwt(request)
# Propaga para banco via connection var
await set_db_tenant_context(tenant.id)
# Propaga para cache (Redis namespace)
request.state.tenant_id = tenant.id
request.state.redis_prefix = f"tenant:{tenant.id}:"
response = await call_next(request)
return response
⚠️ O risco do noisy neighbor
Um tenant que consome recursos excessivos degrada a performance para todos os outros. Implemente: CPU limits por tenant, queue priority por plano (enterprise vai na frente), storage quotas e alertas quando tenant ultrapassa 80% do limite. Isolamento não é só de dados — é de recursos também.
💳 Billing por uso de tokens: metering e Stripe
Usage-based billing é o modelo natural para SaaS agentic — clientes pagam pelo que consomem. Implementar corretamente requer metering preciso por tenant e integração confiável com a plataforma de billing.
📊 Pipeline de metering
🔄 Token-to-credit conversion
Expor tokens diretamente para o cliente cria confusão (o que é um token?). Converta para créditos ou outra unidade compreensível.
💡 Garantias de metering
Metering deve ser: idempotente (duplicatas não cobram duas vezes), persistente (não perde eventos se o serviço reinicia), real-time (cliente vê uso atual, não só no fim do mês) e auditável (cliente pode questionar e você pode provar). Metering incorreto é passivo legal.
⚡ Rate limiting e quotas: soft e hard limits
Rate limiting protege o SaaS de clientes que consomem recursos excessivos (acidentalmente ou não) e garante que todos os tenants têm acesso justo ao sistema. Soft limits alertam; hard limits bloqueiam.
⚡ Token Bucket Algorithm para agentes
Token bucket é o algoritmo mais adequado para rate limiting de APIs de agentes: permite bursts curtos enquanto limita a taxa média de forma suave.
Como funciona
- • Bucket começa cheio (ex: 1000 tokens)
- • Cada request consume N tokens
- • Tokens são repostos a taxa fixa (ex: 100/min)
- • Burst: pode fazer requests rápidos até esvaziar o bucket
- • Depois do burst: volta à taxa de reposição
Implementação com Redis
-- Redis Lua script
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local tokens_needed = tonumber(ARGV[3])
-- Busca estado atual
local tokens = redis.call('GET', key)
-- Calcula tokens disponíveis
-- Subtrai se suficiente, retorna erro se não
Soft limits (alertas)
- ✓70% do limite: email para usuário admin do tenant
- ✓90% do limite: Slack do tenant + painel mostra warning
- ✓95% do limite: sugestão de upgrade de plano
- ✓Sem interrupção de serviço — apenas alertas
Hard limits (bloqueio)
- •100% do limite: novas execuções bloqueadas
- •Retorna 429 Too Many Requests com Retry-After
- •Execuções em andamento não são interrompidas
- •Opção de overage: cobra extra e desbloqueia
📋 Configuração de quotas por plano
| Limite | Starter | Growth | Enterprise |
|---|---|---|---|
| Execuções/mês | 500 | 5.000 | Custom |
| Tokens/mês | 2M | 20M | Custom |
| Execuções concorrentes | 5 | 25 | 100+ |
| Retenção de logs | 7 dias | 90 dias | 1 ano |
📊 Painel admin: visibilidade para tenant e para SaaS
Existem dois tipos de painel: o painel do tenant (o cliente vê seus próprios dados) e o painel do SaaS admin (você vê todos os tenants). Ambos são críticos — um para retenção de clientes, o outro para operação do negócio.
📱 Painel do Tenant
O que o cliente precisa ver:
- •Execuções do período atual vs. mês anterior
- •Consumo de tokens em tempo real + projeção
- •Histórico de execuções com status e duração
- •Top agentes por uso e por custo
- •Alertas de quota e sugestões de otimização
- •Custo estimado para o fim do ciclo
🎛️ Painel do SaaS Admin
O que você (SaaS owner) precisa ver:
- •MRR, ARR, churn, novos tenants do mês
- •Tenants próximos do limite (upgrade opportunity)
- •Tenants inativos (churn risk)
- •Custo de infra vs. receita por tenant (LTV/CAC)
- •Erros e alertas operacionais em tempo real
- •Gross margin por plano e tendência
💡 Transparência como retenção
Clientes que veem seus dados em tempo real têm churn 40% menor do que clientes sem visibilidade (dados internos de SaaS B2B). Visibilidade de custo e uso cria confiança e reduz surpresas na fatura — o maior trigger de churn em SaaS de uso variável.
🎯 Onboarding automatizado: time-to-value em minutos
Time-to-value é o principal preditor de churn em SaaS B2B. Se o cliente não experimenta valor nas primeiras horas, a probabilidade de converter de trial para pago cai drasticamente. Onboarding automatizado comprime esse tempo de dias para minutos.
🔄 Fluxo de provisionamento automático
📊 Métricas de onboarding para otimizar
💰 Pricing strategy: modelos e garantia de margem
Pricing de SaaS agentic é complexo porque o custo é variável (tokens) e o valor percebido é difícil de medir. O modelo de pricing deve capturar valor proporcional ao benefício enquanto garante margem operacional positiva em todos os planos.
Por execução
Ex: R$0.50/execuçãoVantagens
- • Previsível para cliente
- • Fácil de calcular ROI
- • Escalabilidade clara
Desvantagens
- • Execuções com custo muito diferente
- • Pode ser caro para workflows simples
- • Precisa definir o que é uma "execução"
Por tokens (usage-based)
Ex: R$0.05/1k tokensVantagens
- • Reflete custo real diretamente
- • Justo para todos os casos de uso
- • Familiar para devs
Desvantagens
- • Imprevisível para clientes
- • Difícil de orçar
- • "Anxiety pricing" — clientes hesitam em usar
Por resultado (outcome-based)
Ex: R$50/contrato revisadoVantagens
- • Máximo alinhamento de incentivos
- • Cliente paga proporcional ao valor recebido
- • Maior disposição a pagar
Desvantagens
- • Difícil de definir e medir "resultado"
- • Risco de margem se custo varia muito
- • Complexidade contratual alta
📐 Calculando margem mínima por plano
Para cada plano, calcule o cenário de uso máximo e verifique se há margem positiva:
# Starter Plan: R$99/mês # Quota: 500 execuções, 2M tokens # Custo máximo se cliente usa 100% do plano: custo_tokens = 2_000_000 * 0.000015 # Claude Haiku: $0.000015/token custo_infra = 15 # storage, redis, compute custo_stripe = 99 * 0.029 + 0.30 # Stripe fee custo_total = custo_tokens + custo_infra + custo_stripe # R$30 tokens + R$15 infra + R$3.17 Stripe = R$48.17 # Receita: R$99 # Margem bruta: R$50.83 (51%) — SAUDÁVEL ✓ # Se margem < 30%, revisar pricing ou quota
💡 Recomendação: híbrido flat + usage
O modelo mais robusto para SaaS agentic: mensalidade flat (predictability para cliente, baseline de receita para você) + usage fee acima da quota incluída (captura valor de clientes power users). Esse modelo combina previsibilidade com escalabilidade de receita.
✅ Resumo do Módulo 6.5
Próximo Módulo:
6.6 — Gestão de Custos em Escala: cost allocation, chargeback, otimização contínua, ROI calculation e previsão de custo.