🏗️ Arquitetura de Plataformas de Agentes

Conceito Principal

A arquitetura de uma plataforma madura se organiza em seis camadas fundamentais, cada uma com responsabilidades isoladas e comunicacao bem definida com as camadas adjacentes.

Presentation Layer: A camada de entrada. Ela recebe requests de qualquer canal (Telegram, Slack, API REST, WebSocket, webhooks) e normaliza tudo num formato interno padrao. O resto do sistema nunca sabe se a mensagem veio do Telegram ou de uma chamada REST. Essa normalizacao e o que permite adicionar novos canais sem tocar em nenhuma outra camada.

Orchestration Layer: O cerebro do roteamento. Recebe a mensagem normalizada, classifica a intencao, seleciona o agente correto, monta o contexto relevante e despacha. Pode usar regras fixas (comandos como /claude), classificacao por IA (um LLM pequeno que decide), ou uma combinacao dos dois. O orquestrador nunca executa logica de agente. Ele decide quem executa.

Agent Layer: Onde mora a inteligencia. Cada agente e uma unidade autonoma com seu proprio system prompt, seu conjunto de ferramentas disponiveis e sua logica de raciocinio. Um agente de pesquisa sabe buscar na web e sintetizar. Um agente de codigo sabe ler e editar arquivos. Eles nao se conhecem diretamente. Toda comunicacao entre agentes passa pelo orquestrador.

Tool Layer: Acoes atomicas que os agentes podem executar. Cada tool faz exatamente uma coisa: buscar na web, ler um arquivo, enviar email, consultar banco de dados. Tools sao reutilizaveis entre agentes. A interface e padronizada: recebe parametros, executa, retorna resultado.

Memory Layer: Persistencia inteligente. Memoria de curto prazo (historico da sessao), memoria de longo prazo (preferencias do usuario, fatos aprendidos), memoria semantica (embeddings para busca por similaridade). Essa camada define se o sistema "lembra" das coisas ou se cada conversa comeca do zero.

Storage Layer: A infraestrutura de dados. SQLite ou PostgreSQL para dados estruturados, vector stores para embeddings, file system para arquivos, cache (Redis) para dados de alta frequencia. A camada de storage e invisivel para os agentes. Eles falam com a camada de memory, que fala com a storage.

Conceito Principal

Request-Response e o modelo sincrono classico. O cliente envia um request, espera, e recebe um response. HTTP APIs, chamadas de funcao, queries no banco. E simples, previsivel e facil de debugar. O problema: quando uma chamada de LLM demora 30 segundos, o cliente fica travado esperando. Se o provedor cai, o sistema inteiro para.

Event-Driven e o modelo assincrono. Em vez de chamar diretamente, o componente emite um evento. Outros componentes que estao interessados naquele evento reagem. Ninguem espera ninguem. O sistema emite "message.received", o roteador processa quando puder e emite "agent.selected", o agente processa quando puder e emite "response.ready". Cada peca trabalha no seu ritmo.

Message Queues (RabbitMQ, SQS, BullMQ) armazenam eventos numa fila com garantia de entrega. Se o consumidor esta offline, a mensagem espera. Se falha no processamento, a mensagem volta pra fila e tenta novamente. Isso e essencial para workloads de IA onde uma chamada pode demorar minutos.

Pub/Sub (Redis Pub/Sub, Google Pub/Sub, Kafka) permite que multiplos consumidores recebam o mesmo evento. Quando "response.ready" e emitido, o logger registra, o dashboard atualiza, e o canal de Telegram envia a resposta. Todos reagem ao mesmo evento sem saber da existencia um do outro.

Webhooks sao o ponto de integracao com servicos externos. Em vez de ficar fazendo polling ("ja terminou? e agora?"), voce registra uma URL de callback e o servico externo chama quando tiver novidade. A maioria das APIs de IA (OpenAI, Anthropic) suporta webhooks para respostas longas ou batch processing.

Conceito Principal

O Actor Model foi formalizado por Carl Hewitt em 1973 e popularizado pelo framework Akka (Scala/Java). A ideia central e simples: cada unidade de computacao (ator) tem seu proprio estado privado, uma mailbox de mensagens e a capacidade de criar outros atores. Atores nunca compartilham estado. Toda comunicacao acontece via troca de mensagens.

Aplicado a agentes de IA: cada agente e um ator. Ele tem seu estado interno (system prompt, configuracao, historico de sessao), sua mailbox (fila de mensagens a processar) e pode criar sub-atores (um agente de pesquisa pode criar atores temporarios para buscar em paralelo em 5 fontes diferentes). Quando voce manda uma mensagem para o agente de pesquisa, ela vai para a mailbox dele. Ele processa uma mensagem por vez, na ordem que chegaram. Sem race conditions, sem locks, sem bugs de concorrencia.

Message Passing: a comunicacao entre atores e exclusivamente por mensagens. O agente de pesquisa nao chama uma funcao do agente de codigo. Ele envia uma mensagem: "preciso do conteudo deste arquivo". O agente de codigo recebe na sua mailbox, processa, e envia uma mensagem de volta com o resultado. Esse desacoplamento total e o que permite escalar para milhoes de atores.

Fault Tolerance (Let It Crash): no modelo de atores, quando um ator falha, ele nao derruba o sistema. O supervisor (um ator que gerencia outros atores) decide o que fazer: reiniciar o ator, escalar, ou propagar o erro. Esse padrao "let it crash" do Erlang/OTP e a razao pela qual sistemas de telecom tem 99.999% de uptime. Aplicado a agentes: se o agente Ollama trava, o supervisor reinicia ele e reprocessa a mensagem da mailbox.

10M TPS Potential: sistemas baseados no actor model como Akka reportam processamento de ate 10 milhoes de mensagens por segundo em clusters modestos. Isso e possivel porque atores sao leves (nao sao threads do OS) e a mailbox e uma estrutura de dados simples (fila em memoria). Para plataformas de agentes, esse potencial significa que o gargalo nunca sera a infraestrutura de orquestracao. Sera sempre o tempo de resposta do LLM.

Conceito Principal

Multi-tenancy e a capacidade de servir multiplos clientes (tenants) na mesma infraestrutura, mantendo seus dados e execucoes completamente isolados. Existem tres estrategias principais, cada uma com trade-offs claros.

Database-per-tenant: Cada tenant tem seu proprio banco de dados (ou schema). Isolamento maximo: mesmo um bug grave no codigo nao vaza dados entre tenants porque as conexoes sao fisicamente separadas. O custo e maior complexidade operacional: mais bancos para gerenciar, mais backups, mais migracoes. Indicado para dados altamente sensiveis (saude, financeiro).

Schema-per-tenant: Um unico banco de dados, mas cada tenant tem seu proprio schema (conjunto de tabelas). Bom equilibrio entre isolamento e operacao. Migracoes precisam rodar em todos os schemas, mas o gerenciamento e mais simples que databases separados. Indicado para a maioria dos SaaS B2B.

Shared-tables com Row-Level Security (RLS): Todos os tenants compartilham as mesmas tabelas, com uma coluna tenant_id em cada registro. O banco de dados (PostgreSQL RLS) garante que queries de um tenant nunca retornam dados de outro, mesmo se o codigo da aplicacao errar. E a abordagem mais simples de implementar e operar, e funciona bem para a maioria das plataformas de agentes.

Isolamento de API keys: Alem do banco, cada tenant precisa ter suas proprias chaves de API para provedores de IA. Se voce usa uma chave unica da plataforma, o consumo de tokens de um tenant afeta o rate limit de todos. Tenants com suas proprias chaves pagam seu proprio consumo e nao competem por rate limits.

-- PostgreSQL Row-Level Security
CREATE TABLE conversations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL REFERENCES tenants(id),
  agent_id TEXT NOT NULL,
  messages JSONB NOT NULL DEFAULT '[]',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Habilitar RLS
ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;

-- Policy: cada tenant so ve seus dados
CREATE POLICY tenant_isolation ON conversations
  USING (tenant_id = current_setting('app.tenant_id')::UUID);

-- No codigo, antes de cada query:
-- SET app.tenant_id = 'uuid-do-tenant';

Conceito Principal

Stateless Agents: O principio fundamental da escalabilidade horizontal e que qualquer instancia pode processar qualquer request. Um agente nao pode guardar estado na memoria do processo (variaveis locais, cache in-memory exclusivo). Todo estado precisa estar em storage externo (banco de dados, Redis, file system distribuido). Assim, se voce tem 5 instancias do agente Claude rodando, qualquer uma pode pegar a proxima mensagem da fila e processar, porque o historico e contexto estao no banco.

Load Balancing: Um load balancer (Nginx, HAProxy, AWS ALB) distribui requests entre as instancias. Para plataformas de agentes, o round-robin simples funciona quando os agentes sao stateless. Se precisar de sticky sessions (manter um usuario na mesma instancia), use session affinity baseada no chat_id, mas isso complica o failover.

Container Orchestration: Docker empacota cada servico (bot, dashboard, workers) em containers isolados. Kubernetes (ou Docker Compose para ambientes menores) orquestra esses containers: quantas replicas rodar, como distribuir, como reiniciar quando falham. Para uma plataforma de agentes, o setup tipico e: 1 container para o bot (presentation layer), N containers para workers de agentes (agent layer), 1 container para o banco, 1 container para Redis.

Auto-Scaling baseado em Token Usage: Metricas tradicionais de auto-scaling (CPU, memoria) nao funcionam bem para workloads de IA. Uma chamada de LLM usa pouca CPU mas demora 30 segundos. A metrica certa e: profundidade da fila de mensagens ou tempo medio de processamento. Se a fila de mensagens pendentes cresce acima de um threshold, suba mais instancias de workers. Se o tempo medio de resposta ultrapassa 15 segundos, adicione capacidade. Se a fila esvazia, reduza as instancias para economizar.

Conceito Principal

O exercicio cobre 5 entregas concretas que, juntas, formam a documentacao arquitetural da sua plataforma.

Entrega 1 - Diagrama de Camadas: Desenhe as 6 camadas (presentation, orchestration, agent, tool, memory, storage) como blocos empilhados. Para cada camada, liste os componentes internos e as tecnologias escolhidas. Use setas para indicar a direcao da comunicacao. Ferramentas sugeridas: Excalidraw (rapido e bonito), Mermaid (diagramas como codigo), ou papel e caneta mesmo.

Entrega 2 - Fluxo de Mensagem: Trace o caminho completo de uma mensagem do usuario desde a chegada no Telegram ate a resposta final. Identifique cada componente que a mensagem toca, se a comunicacao e sincrona ou assincrona, e onde pode haver fila. Inclua o caminho alternativo (fallback) quando o provedor principal falha.

Entrega 3 - Modelo de Dados: Defina as tabelas principais: tenants, users, conversations, messages, agent_configs, api_keys, token_usage. Para cada tabela, defina as colunas essenciais e os relacionamentos. Inclua a coluna tenant_id em todas as tabelas que precisam de isolamento.

Entrega 4 - Estrategia de Scaling: Documente quantas instancias de cada componente voce planeja rodar, qual metrica dispara o auto-scaling, e qual e o custo estimado por 1.000 usuarios. Inclua o calculo de tokens: se cada usuario manda 20 mensagens por dia e cada mensagem consome ~2.000 tokens, quanto custa por mes.

Entrega 5 - Decision Log: Para cada decisao arquitetural importante (event-driven vs sincrono, shared-tables vs database-per-tenant, Kubernetes vs Docker Compose), documente: a decisao tomada, as alternativas consideradas, e a razao da escolha. Esse log e ouro para o futuro quando alguem (incluindo voce) perguntar "por que fizemos assim?".

# Exemplo de Mermaid para Diagrama de Camadas
```mermaid
graph TB
  subgraph Presentation
    TG[Telegram Bot]
    API[REST API]
    WH[Webhooks]
  end

  subgraph Orchestration
    RT[Router]
    CL[Classifier]
    CTX[Context Builder]
  end

  subgraph Agents
    AG1[Claude Agent]
    AG2[Ollama Agent]
    AG3[OpenRouter Agent]
  end

  subgraph Tools
    WS[Web Search]
    FR[File Read]
    DB[DB Query]
  end

  subgraph Memory
    STM[Short-Term]
    LTM[Long-Term]
    SEM[Semantic]
  end

  subgraph Storage
    PG[(PostgreSQL)]
    RD[(Redis)]
    VS[(Vector Store)]
  end

  TG --> RT
  API --> RT
  RT --> CL --> CTX --> AG1 & AG2 & AG3
  AG1 & AG2 & AG3 --> WS & FR & DB
  AG1 & AG2 & AG3 --> STM & LTM & SEM
  STM & LTM & SEM --> PG & RD & VS
```