🏗️ Arquitetura da Plataforma de Agentes

Camadas app, agents, prompts, skills, tools, memory

Base para qualquer SaaS com IA

Camadas, separacao, modularidade

Organizacao que escala

Projetos desorganizados morrem rapido

MVC, feature-based, monorepo

.env, secrets, providers

Seguranca e flexibilidade

dotenv, vault, multi-provider

Compartilhar vs isolar contexto

Performance e seguranca

shared state, isolation, tenant

Pipeline Entrada>Decisao>Execucao>Saida

Previsibilidade e debug

middleware, pipeline, streaming

Repo, pastas, .env, primeiro agente

Teoria sem pratica nao constroi

scaffold, git init, skeleton

Presentation, Agent, Service, Data layer. Cada camada com responsabilidade clara.

Separacao de camadas permite escalar e manter o sistema sem caos.

Presentation, Agent, Service, Data layer

Dois paradigmas de comunicacao entre componentes e agentes.

Agentes asincronos precisam de event-driven. Sincrono limita escala.

Pub/sub, webhooks, polling

Tiers separados com deployment independente para cada camada.

Deploy independente permite iterar rapido sem derrubar o sistema inteiro.

Tiers separados, deployment independente

Isolamento de dados e execucao entre diferentes clientes/tenants.

Sem isolamento, um tenant pode acessar dados de outro. Risco critico.

Data isolation, tenant ID, RLS

Adicionar mais instancias em vez de instancias maiores.

Agentes IA sao stateful por natureza. Escalar exige design stateless.

Stateless, load balancing, auto-scaling

Desenhar a arquitetura completa do seu SaaS com camadas e fluxos.

Diagrama visual solidifica o entendimento e serve de referencia.

Desenhar a arquitetura do SaaS

A relacao direta entre estrutura de pastas e sobrevivencia do projeto.

Projetos mal estruturados ficam impossiveis de manter em semanas.

Manutencao, escalabilidade, onboarding

Trade-offs entre um repositorio unico e multiplos repos para projetos com agentes.

Escolha errada no inicio custa caro para corrigir depois.

Turborepo, Nx, trade-offs

Separacao em Domain, Application e Infrastructure layers.

Clean Architecture torna o sistema testavel e substituivel por camada.

Domain, application, infra layers

Organizar por feature (tudo junto) vs por camada (controllers, services, models).

Feature folders escalam melhor para projetos com muitos agentes.

Organizacao por feature, colocation

Index files como ponto unico de exportacao, naming conventions e imports limpos.

Convencoes consistentes reduzem carga cognitiva do time e da IA.

Index files, naming, imports

Criar a estrutura real de pastas do projeto seguindo as convencoes aprendidas.

Pratica consolida o conhecimento e cria a base para os proximos modulos.

Criar estrutura real

Gerenciamento de variaveis de ambiente, .env.example e gitignore.

Chaves expostas no GitHub sao exploradas em minutos por bots.

dotenv, .env.example, gitignore

Configurar OpenAI, Anthropic e outros com fallback chain.

Depender de um unico provider e risco. Fallback garante uptime.

OpenAI, Anthropic, fallback chain

Vault, rotacao de chaves e controle de acesso.

Chaves estaticas sao bomba-relogio. Rotacao e access control sao obrigatorios.

Vault, rotation, access control

Setup de Supabase, Neon e connection pooling para producao.

Banco mal configurado e gargalo numero 1 em apps com agentes.

Supabase, Neon, connection pooling

Validar config com Zod schema, fail fast e health checks.

Melhor falhar no boot do que em producao com config errada.

Zod schema, fail fast, health checks

Configurar todas as variaveis de ambiente do projeto real.

Setup manual garante entendimento de cada variavel e seu proposito.

Configurar tudo do projeto

Token window, tipos de contexto e como modelos consomem informacao.

Contexto mal gerenciado causa respostas erradas e custos altos.

Token window, types of context

Prompts globais, por agente e por tarefa em hierarquia.

Hierarquia bem definida evita conflitos e comportamento imprevisivel.

Global, agent, task-level prompts

Memoria e estado compartilhado entre multiplos agentes.

Agentes que colaboram precisam de contexto compartilhado consistente.

Shared memory, consistency, sync

Cada agente com seu proprio escopo de contexto isolado.

Isolamento reduz ruido, melhora performance e protege dados sensiveis.

Privacy, performance, noise reduction

Tecnicas para gerenciar o limite de tokens: contagem, sumarizacao e poda.

Estourar a context window quebra o agente. Gerenciar e obrigatorio.

Token counting, summarization, pruning

Mapear o fluxo completo de contexto do seu SaaS.

Mapa de contexto e o blueprint para implementacao dos agentes.

Mapear fluxo de contexto

O ciclo de vida completo de uma requisicao em sistema de agentes.

Sem pipeline claro, debug vira pesadelo e bugs sao impossiveis de rastrear.

Request lifecycle, stages

Camadas de pre e pos processamento: logging, auth, validacao.

Middleware evita duplicacao e centraliza logica transversal.

Pre/post processing, logging, auth

Estrategias de tratamento de erro e degradacao graceful.

APIs de IA falham. Seu sistema precisa continuar funcionando.

Try/catch, graceful degradation

Retry inteligente com backoff e circuit breaker para evitar cascata de falhas.

Retry cego piora tudo. Circuit breaker protege o sistema inteiro.

Exponential backoff, failure threshold

Enviar resposta em chunks enquanto o modelo gera, em vez de esperar tudo.

Streaming reduz perceived latency drasticamente. UX obrigatoria para IA.

SSE, WebSocket, chunked response

Construir o pipeline completo com middleware, error handling e streaming.

Pipeline funcional e a espinha dorsal do seu SaaS de agentes.

Build the full flow

Git init, .gitignore, README e license do projeto.

Todo projeto profissional comeca com versionamento configurado.

Git init, .gitignore, README, license

Criar a arvore de diretorios com mkdir e index files.

Estrutura pronta acelera todo o desenvolvimento subsequente.

mkdir structure, index files

npm init e instalacao das dependencias essenciais.

Package.json bem configurado e a fundacao do projeto Node.

npm init, essentials

Configurar Supabase, criar tabelas iniciais e migrations.

Banco funcionando desde o inicio evita divida tecnica.

Supabase config, migrations

O agente minimo que funciona: recebe input, processa, retorna output.

Ter algo funcionando cedo valida toda a arquitetura.

Minimal agent that works

Tudo rodando: repo, pastas, banco, agente, health check passando.

Entregavel final da Trilha 2. Base solida para construir nas proximas trilhas.

Everything running