👥 Multi-usuário

Qualquer dado que vive fora de "request do user X" — current_user, last_query, active_project.

Single-user esconde estado global. Multi-user expõe imediatamente.

Stateless functions, contextvars Python, scope por request.

User A pergunta sobre projeto X; user B pergunta sobre projeto Y. Agente responde A com Y.

Bug mais embaraçoso possível. Vaza dado de um cliente pra outro.

async with lock, request_id como chave, sem caches mutáveis globais.

Tabela memory sem coluna user_id, busca retorna fatos de qualquer user.

Único bug grave que LGPD pune. Não pode acontecer.

user_id como FK obrigatória, row-level security, namespace separators.

Sem atribuição de tokens por user, não dá pra cobrar nem identificar abuso.

Modelo de negócio depende disso. Sem custo por user, não há SaaS sustentável.

Token accounting por request, agregação diária, rate limit por user.

Quando um user reclama, você não consegue reproduzir o problema sem audit log por user.

Suporte ruim derruba retenção. Especialmente em produto premium.

Audit log com user_id, request_id rastreável, replay tool.

Lista que diz se seu agente sobrevive ao 2º user: user_id em tudo, lock em estado mutável, sessão por request.

Falhar nesse checklist = retrabalho ou incidente.

Stateless por design, audit log inicial, tests com 2 users simulados.

Tabela users com colunas mínimas. user_id é UUID, não inteiro sequencial.

UUID evita ID enumeration. Roles desde dia 1 = permissions depois.

UUID v4, roles JSON ['admin','user'], audit no created_at.

Pasta dedicada por usuário com memory.db, files/, preferences.json. Isolamento FS-level.

Backup, exportar dados (LGPD art. 18), delete account vira simples.

FileTool com workspace=user.workspace, MemoryStore com path por user.

Estrutura JSON com tokens por provider (google, anthropic, openai) por usuário, encriptados.

Cada user traz suas credenciais. Você não paga as APIs deles.

~/.config/app/auth.json estrutura aninhada, refresh automático, sentinel pra expirado.

Objeto Session com user, request_id, timestamp, tools_enabled — passado por toda a chain.

Toda função recebe Session. Audit fica automático.

Dataclass frozen, contextvars como alternativa, log inicial e final.

/start no Telegram inicia conversa estruturada que cria user, pede preferências, ativa tools.

Onboarding inline tem 3x mais conversão que "preencha esse form".

State machine simples, save partial progress, escape /cancel sempre.

/logout invalida tokens. /delete remove workspace completo + audit log mantém só metadados.

LGPD obriga. E user confia mais quando vê que pode sair.

Soft delete primeiro (7 dias), hard delete via cron, e-mail confirmação.

User scope (privado), team scope (compartilhado entre members), world scope (público, ex: docs).

Sem escopo explícito, tudo vira "world" e vaza tudo pra todos.

Coluna scope (enum), default user, promover requer ação explícita.

~/.app/users/<uuid>/memory.db isolado. Backup/restore por user trivial.

Isolamento real (não só lógico). Falha em 1 user não derruba os outros.

Pool de conexões por DB, vacuum periódico, backup com .dump.

1 instância Pinecone/Chroma com namespaces user_uuid e team_uuid. Query filtra por namespace.

Vector store é caro de rodar N vezes. Compartilhar com namespace é o padrão.

Filter por metadata, namespace prefix, defesa em profundidade.

Comando /share <memory_id> que copia para namespace team, audita quem promoveu.

Conhecimento que vira ativo do time só existe se for fácil promover.

Confirmation step, link de origem, revogar = unshare audit completo.

API que recebe lista de escopos permitidos. Default = ['user']. /search-team inclui ['user','team'].

Forçar escolha consciente evita escapes acidentais.

Default mais restrito, exception se vazio, audit do scope efetivamente usado.

Cron que remove memórias de user deletado, dedupica entries idênticas, comprime antigas.

Sem GC, o sistema acumula lixo e degrada busca.

SQL CASCADE em delete, hash de content para dedup, dry-run primeiro.

Um agente "chief" que recebe a request, decompõe, delega para sub-agentes especialistas.

Padrão com maior ganho de qualidade documentado em multi-agent research.

Decompor, delegar, reconciliar respostas, decidir quando parar.

Configuração por user/tier que define quais modelos e tools estão disponíveis.

Free user usa Haiku + 3 tools; Pro usa Opus + todas. Sem refatorar.

Tabela tiers (JSON config), feature flags por user, sobrepor preferences.

Cada sub-agente tem seu CLAUDE.md, set de tools restrito, contexto limpo.

Contexto pequeno + foco = qualidade. Generalista vira mediano.

Subagent task como ferramenta, summary report, isolamento de falha.

Limites por minuto/hora/dia. Circuit breaker quando tool externa falha N vezes.

Sem limit, 1 user em loop ferra os outros e a fatura.

Token bucket por user_id, decay automático, half-open state.

Protocolo que permite agentes em máquinas/repos diferentes se chamarem. Mensagens estruturadas com auth.

Escala horizontal sem virar monorepo gigante.

Bearer token compartilhado, envelope com correlation_id, replay protection.

Tool com flag requires_approval=True pausa execução e manda mensagem ao humano.

"Mandar e-mail pra cliente" precisa de OK. "Listar arquivos" não.

Pending state em DB, timeout em 24h, audit do aprovador.

Tabela channel_links mapeia telegram_chat_id, slack_user_id, web_session_id → user_id.

User entra no Slack continuando conversa do Telegram. Magia experimentada.

Pareamento via código de 6 dígitos, e-mail como ponte, audit do link.

Implementa Channel via Slack Bolt SDK em Socket Mode (sem URL pública necessária).

Slack é onde empresas vivem. Bot em DM ou canal.

App token vs bot token, event subscriptions, thread_ts preserva contexto.

Endpoint /chat com SSE pra streaming. Cookie httpOnly pra session.

Nem todo user usa Telegram/Slack. Página web democratiza.

Server-Sent Events vs WebSocket, CSRF, rate limit por IP.

Channel.send sem incoming antes. Agente reporta evento (relatório matinal, alerta).

Diferença entre chatbot (reativo) e agente (proativo). Push muda relação.

Preferência por canal (user pode escolher), quiet hours, opt-out granular.

Output do agente é estruturado (markdown + blocks). Channel renderiza nativo.

Slack tem blocks, Telegram tem MarkdownV2, Web tem HTML. Não pode tratar igual.

Intermediate AST, renderer por channel, fallback para plain text.

Lista priorizada de canais. Se primary falha em N tentativas, tenta secondary.

Alertas críticos não podem depender de 1 canal estar funcionando.

Backoff exponencial, audit do canal usado, alerta se todos falharem.

Web page com 4 cards: usuários ativos hoje, custo do dia, erros últimas 24h, latência p95.

Sem dashboard, ops é "alguém me avisa quando quebra".

SQL agregado, refresh a cada 30s, cache 60s, sem build (HTML + Tailwind).

Arquivo .jsonl com event_type, user_id, request_id, timestamp, payload (sem PII).

Compliance e debug. "Mostra o que o user X fez quinta passada" tem resposta.

Rotação por dia, retenção 90 dias, redact via regex, hash de PII.

Tabela usage com user, day, model, tokens_in, tokens_out, cost_usd. Agregada diariamente.

Sem isso, modelo de pricing é palpite. Com isso, é decisão informada.

Tabela de preços versionada (modelos mudam), alerta de outlier, top 10 users.

Cron a cada 5 min checa thresholds: custo > X, latência > Y, erros > Z.

Alerta proativo > user reclamando depois.

Threshold em config, deduplicate (não alertar 100x), snooze.

Flag em DB que, se true, todas as requests retornam "em manutenção". Endpoint /killall pra ativar.

Loop infinito, vazamento, alucinação grave — você precisa parar em 30s.

Flag global checada em cada request, kill por user específico, audit.

Daily Active Users, custo médio por user, taxa de respostas com 👍 vs 👎.

Métrica errada = decisão errada. DAU e custo unitário são os 2 que sempre importam.

Botão de feedback inline, conversion funnel, churn detection.