🏗️ Arquitetura da Plataforma de Agentes

Conceito Principal

Uma plataforma de agentes profissional se organiza em camadas com responsabilidades claras. A camada de entrada (app/) recebe requests de diferentes canais: Telegram, API REST, webhooks. A camada de decisao (agents/) contem a logica de cada agente e sua capacidade de raciocinio. A camada de ferramentas (tools/) oferece acoes atomicas que os agentes podem chamar. A camada de instrucoes (prompts/) armazena system prompts versionados e templates. A camada de habilidades (skills/) compoe multiplas tools em capacidades complexas. E a camada de estado (memory/) persiste tudo que precisa sobreviver entre execucoes.

O modelo event-driven e a cola entre essas camadas. Em vez de chamadas diretas e acopladas, cada componente emite e escuta eventos. Quando um usuario envia uma mensagem, o sistema emite um evento "message.received". O roteador escuta esse evento, classifica a intencao e emite "agent.selected". O agente processa e emite "response.ready". Esse desacoplamento permite adicionar novos agentes, trocar provedores ou adicionar logging sem mexer no codigo existente.

Conceito Principal

A estrutura de referencia para uma plataforma de agentes segue o principio de separacao por dominio funcional, nao por tipo de arquivo. Em vez de ter uma pasta "controllers/", outra "models/" e outra "services/" (que nao dizem nada sobre o que o sistema faz), voce organiza por responsabilidade:

projeto/
├── app/              # Entrada: servidor, rotas, middleware
│   ├── server.ts
│   ├── router.ts
│   └── middleware/
├── agents/           # Logica de cada agente
│   ├── claude.ts
│   ├── ollama.ts
│   └── openrouter.ts
├── prompts/          # System prompts e templates
│   ├── global.md
│   └── agents/
├── skills/           # Capacidades compostas
│   ├── gmail.ts
│   └── calendar.ts
├── tools/            # Acoes atomicas
│   ├── web-search.ts
│   ├── file-read.ts
│   └── db-query.ts
├── memory/           # Persistencia de estado
│   ├── store.ts
│   └── migrations/
├── config/           # Configuracao centralizada
│   ├── env.ts
│   └── providers.ts
├── .env
├── .env.example
└── .gitignore

Conceito Principal

O padrao profissional de configuracao usa tres camadas. A primeira e o arquivo .env na raiz do projeto, que contem as variaveis de ambiente locais e nunca entra no git. A segunda e o arquivo .env.example, que contem as mesmas variaveis mas com valores placeholder, servindo de documentacao viva. A terceira e um modulo config/ que carrega, valida e exporta as configuracoes de forma tipada:

// config/env.ts
import { config } from 'dotenv';
config();

export const env = {
  // Provedores de IA
  OPENAI_API_KEY: requireEnv('OPENAI_API_KEY'),
  ANTHROPIC_API_KEY: requireEnv('ANTHROPIC_API_KEY'),
  GOOGLE_API_KEY: getEnv('GOOGLE_API_KEY', ''),

  // Telegram
  TELEGRAM_TOKEN: requireEnv('TELEGRAM_TOKEN'),
  ALLOWED_CHAT_ID: requireEnv('ALLOWED_CHAT_ID'),

  // Server
  PORT: getEnv('PORT', '3000'),
  NODE_ENV: getEnv('NODE_ENV', 'development'),
};

function requireEnv(key: string): string {
  const value = process.env[key];
  if (!value) throw new Error(`Missing: ${key}`);
  return value;
}

function getEnv(key: string, fallback: string): string {
  return process.env[key] || fallback;
}

Conceito Principal

O sistema de contexto funciona como uma hierarquia de heranca. No topo esta o contexto global: identidade da plataforma, regras de seguranca, formato de resposta padrao, e restricoes que valem para todos os agentes. Esse contexto normalmente fica em um arquivo como CLAUDE.md ou system-prompt.md na raiz do projeto.

No segundo nivel esta o contexto por agente: dominio de atuacao, tom de voz especifico, ferramentas disponiveis e restricoes locais. Cada agente tem seu arquivo de configuracao (agents/research.yaml, agents/comms.yaml) que define essas instrucoes especificas.

No terceiro nivel esta o contexto por sessao: historico da conversa atual, preferencias do usuario detectadas durante a interacao, e estado temporario. Esse contexto existe apenas durante a execucao e nao persiste entre sessoes (a menos que explicitamente salvo em memory/).

// Hierarquia de contexto
const context = {
  global: loadFile('prompts/global.md'),     // Regras da plataforma
  agent:  loadFile('prompts/agents/research.md'), // Instrucoes especificas
  session: getSessionHistory(chatId),         // Historico da conversa
  user:   getUserPreferences(userId),         // Preferencias do usuario
};

// O system prompt final e a composicao das camadas
const systemPrompt = [
  context.global,
  context.agent,
  context.user,
].join('\n\n');

Conceito Principal

O pipeline padrao de execucao tem quatro fases:

1. Entrada: O sistema recebe a mensagem (Telegram, API, webhook), valida o formato, autentica o usuario, e registra o inicio do request com um ID unico para rastreabilidade.

2. Decisao: O roteador analisa a mensagem e decide qual agente deve processar. Isso pode ser baseado em comandos explicitos (/claude, /ollama), classificacao por IA, ou regras fixas. O contexto relevante e montado nesta fase.

3. Execucao: O agente selecionado recebe a mensagem e o contexto, processa usando o provedor de IA correspondente, pode chamar tools durante o processo, e gera uma resposta. Se o provedor falha, o sistema tenta um fallback.

4. Saida: A resposta e formatada para o canal de origem, metricas sao registradas (tokens usados, tempo de resposta, custo), o historico e atualizado, e a resposta e enviada ao usuario.

// Fluxo simplificado
async function handleMessage(msg) {
  const requestId = generateId();
  log.info({ requestId, user: msg.from }, 'request.start');

  try {
    // 1. Entrada: validar e autenticar
    validateMessage(msg);
    authenticate(msg.from.id);

    // 2. Decisao: rotear para agente
    const agent = router.selectAgent(msg.text);
    const context = await buildContext(msg, agent);

    // 3. Execucao: processar com fallback
    const response = await executeWithFallback(
      () => agent.process(msg.text, context),
      () => fallbackAgent.process(msg.text, context)
    );

    // 4. Saida: formatar, registrar, enviar
    await trackUsage(requestId, response.usage);
    await saveHistory(msg.chat.id, msg.text, response.text);
    await sendResponse(msg.chat.id, response.text);

    log.info({ requestId, tokens: response.usage }, 'request.done');
  } catch (error) {
    log.error({ requestId, error }, 'request.failed');
    await sendResponse(msg.chat.id, 'Erro no processamento.');
  }
}

Conceito Principal

O exercicio cobre 5 passos concretos:

Passo 1 - Inicializar o repositorio: git init, npm init, instalar dependencias base (dotenv, typescript).

Passo 2 - Criar a estrutura de pastas: Criar todos os diretorios (app/, agents/, prompts/, skills/, tools/, memory/, config/) com seus index files.

Passo 3 - Configurar .env: Criar .env com as chaves de pelo menos um provedor, .env.example como documentacao, e .gitignore para proteger os secrets.

Passo 4 - Modulo de configuracao: Criar config/env.ts que carrega, valida e exporta as variaveis de ambiente de forma tipada.

Passo 5 - Esqueleto do primeiro agente: Criar agents/simple.ts com a interface basica: recebe mensagem, chama provedor de IA, retorna resposta. Testar com um script simples.

# Passo 1: Inicializar
mkdir meu-saas-agentes && cd meu-saas-agentes
git init
npm init -y
npm install dotenv typescript @types/node
npx tsc --init

# Passo 2: Criar estrutura
mkdir -p app agents prompts/agents skills tools memory config
touch app/server.ts app/router.ts
touch agents/simple.ts agents/index.ts
touch prompts/global.md
touch tools/index.ts skills/index.ts
touch memory/store.ts
touch config/env.ts

# Passo 3: Configurar
echo "OPENAI_API_KEY=sk-sua-chave" > .env
echo "OPENAI_API_KEY=sk-xxx" > .env.example
echo -e ".env\nnode_modules/\ndist/" > .gitignore

# Passo 4: Primeiro commit
git add .
git commit -m "feat: scaffold inicial da plataforma"