Sentinel Agents - Documentacao Completa v4.1

Inicio Rapido

#

O Sentinel Agents roda em um unico container Docker com Express + WebSocket. Tudo que voce precisa e Docker, Node.js 22+ e acesso ao CLI Claude Code.

1. Clonar o repositorio

bash

# Clone o projeto
git clone https://github.com/rsoftconsultoria/moltbot-platform.git
cd moltbot-platform/agents-orchestrator

2. Instalar dependencias

bash

npm install

3. Iniciar o servidor

bash

# Producao
npm start

# Desenvolvimento (hot reload)
npm run dev

O painel estara disponivel em http://localhost:3000.

Arquitetura do Sistema

#

O Sentinel Agents opera em um unico container Docker contendo o servidor Express, WebSocket, sistema de persistencia JSON e o CLI Claude Code como subprocesso.

Docker Container

Infraestrutura

Navegador (SPA Vanilla JS) | HTTP REST + WebSocket (ws) | +---------------------------+ | Docker Container | | | | server.js -> Express 4.21 | | | | | api.js -> Rotas REST | | manager.js -> CRUD Agentes| | executor.js -> Spawn CLI | | scheduler.js -> node-cron | | pipeline.js -> Steps seq | | brain.js -> Analise IA | | communication.js -> Bus | | review-engine.js -> QA | | | | | db.js -> JSON em /data/ | | | | | Claude Code CLI (spawn) | +---------------------------+ | Persistencia: data/*.json

Fluxo de Execucao

Frontend envia POST /api/agents/:id/execute com JWT
manager.executeTask() recebe e delega ao executor.execute()
Executor faz spawn do CLI Claude Code com --output-format stream-json
Stdout e parseado linha a linha via stream-json
Chunks sao enviados via WebSocket broadcast ao frontend
brain.js analisa o resultado automaticamente
Se configurado, review-engine.js dispara revisao entre agentes

Pipelines

Executam steps em sequencia. Cada step usa um agente diferente. A saida de um step e passada como input do proximo via template {{input}}.

16 Agentes Especializados

#

Cada agente possui um system prompt especializado, modelo configuravel (padrao: claude-sonnet-4-6), modo de permissao e secrets individuais.

J

Jarvis

Chief Orchestrator -- coordena todos os agentes

B

Beatrix

PO/CFO -- gestao de produto e financeiro

D

DaVinci

Tech Lead/CEO -- lideranca tecnica

Py

Pythia

Python -- backend, scripts, automacao

R

Reacto

Elite UI/UX -- frontend premium

JM

JavaMax

Java -- backends enterprise, Spring

NN

NodeNinja

Full-Stack JS -- Node.js, Express, React

S

Shield

QA/CISO -- qualidade e seguranca

Sc

Scribe

Docs -- documentacao tecnica

T

Terraform

IaC/DevOps -- infra como codigo

CA

CloudAWS

AWS -- servicos e otimizacao AWS

AZ

CloudAzure

Azure -- servicos Microsoft Cloud

K

KubeOps

Kubernetes -- orquestracao de containers

N

Nexus

Sales -- vendas e estrategia comercial

Ne

Neuron

ML -- machine learning e IA

L

Lexicon

Prompt Eng -- engenharia de prompts

Cada agente pode ter secrets individuais (ex: tokens GitHub, chaves AWS) configurados via POST /api/agents/:id/secrets. O system prompt fica em config.systemPrompt (nao no nivel raiz).

Stack Tecnologica

#

Node.js 22 Alpine

Runtime principal, ESM nativo com import/export

Express 4.21

Framework HTTP com rotas REST organizadas

ws 8.18

WebSocket bidirecional com reconexao automatica

JSON Persistence

Arquivos JSON em /app/data/ com write atomy

Claude Code CLI

Spawn como child_process com stream-json

node-cron

Agendamento cron in-memory para tarefas

Docker

Container unico com todo o sistema

Vanilla JS SPA

Frontend sem framework, objetos globais no window

JWT + bcrypt

Autenticacao com tokens e hash de senhas

Estrutura de Diretorios

textoagents-orchestrator/

agents-orchestrator/
|-- server.js                  # HTTP + WebSocket na mesma porta
|-- src/
|   |-- routes/api.js          # Rotas REST sob /api
|   |-- agents/
|   |   |-- manager.js         # CRUD + orquestracao
|   |   |-- executor.js        # Spawn do CLI Claude
|   |   |-- scheduler.js       # Cron in-memory
|   |   |-- pipeline.js        # Execucao sequencial
|   |   |-- brain.js           # Analise de resultados
|   |   |-- communication.js   # Message Bus inter-agentes
|   |   |-- review-engine.js   # Motor de revisao
|   |   |-- git-integration.js # Integracao GitHub
|   |-- store/db.js            # Persistencia JSON
|   |-- auth/plans.js          # Sistema de planos
|   |-- memory/                # Memoria semantica (ES)
|   |-- cache/                 # Cache em memoria
|-- public/
|   |-- index.html             # SPA single-page
|   |-- css/styles.css         # Estilos globais
|   |-- js/
|       |-- app.js             # Controlador principal + WS
|       |-- api.js             # Client HTTP para /api/*
|       |-- components/*.js    # UI por secao
|-- data/                      # Persistencia JSON
    |-- agents.json
    |-- tasks.json
    |-- pipelines.json
    |-- messages.json
    |-- reviews.json

API -- Autenticacao

#

Toda requisicao (exceto webhooks publicos) requer um token JWT no header Authorization: Bearer <token>.

POST /api/auth/login Autenticar e obter token JWT

Request Body

curl -X POST https://sentinel-agents.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@sentinel-agents.com.br",
    "password": "sua-senha"
  }'

const response = await fetch('https://sentinel-agents.com.br/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'admin@sentinel-agents.com.br',
    password: 'sua-senha'
  })
});

const { token } = await response.json();
// Usar token em requests subsequentes

import requests

resp = requests.post(
    'https://sentinel-agents.com.br/api/auth/login',
    json={
        'email': 'admin@sentinel-agents.com.br',
        'password': 'sua-senha'
    }
)
token = resp.json()['token']

Response (200)

json

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid-v4",
    "email": "admin@sentinel-agents.com.br",
    "role": "owner",
    "plan": "enterprise"
  }
}

API -- Agentes

#

CRUD completo de agentes. Cada agente possui configuracoes de modelo, system prompt, diretorio de trabalho e secrets.

GET /api/agents Listar todos os agentes

jsonResponse 200

[
  {
    "id": "uuid-v4",
    "name": "Jarvis",
    "description": "Chief Orchestrator",
    "status": "idle",
    "config": {
      "model": "claude-sonnet-4-6",
      "systemPrompt": "...",
      "workingDirectory": "/app",
      "maxTurns": 0,
      "permissionMode": "bypassPermissions"
    },
    "createdAt": "2026-03-01T..."
  }
]

GET /api/agents/:id Detalhes de um agente

Retorna o agente com o ID especificado, incluindo configuracoes e historico de execucoes recentes.

POST /api/agents Criar novo agente

jsonRequest Body

{
  "name": "MeuAgente",
  "description": "Descricao do agente",
  "config": {
    "model": "claude-sonnet-4-6",
    "systemPrompt": "Voce e um agente especializado em...",
    "workingDirectory": "/app/workspace",
    "maxTurns": 0,
    "permissionMode": "bypassPermissions"
  }
}

PUT /api/agents/:id Atualizar agente

O system prompt deve ser enviado dentro de config.systemPrompt, nunca no nivel raiz do objeto.

DELETE /api/agents/:id Remover agente

Remove o agente permanentemente. Execucoes em andamento serao canceladas.

POST /api/agents/:id/secrets Configurar secrets do agente

jsonRequest Body

{
  "name": "GITHUB_TOKEN",
  "value": "ghp_xxxxxxxxxxxx"
}

API -- Execucao

#

POST /api/agents/:id/execute Executar tarefa em um agente

curl -X POST https://sentinel-agents.com.br/api/agents/AGENT_ID/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Criar endpoint REST para usuarios",
    "instructions": "Usar Express com validacao Joi"
  }'

const res = await fetch(`/api/agents/${agentId}/execute`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    task: 'Criar endpoint REST para usuarios',
    instructions: 'Usar Express com validacao Joi'
  })
});

const { executionId } = await res.json();
// Acompanhar via WebSocket

resp = requests.post(
    f'https://sentinel-agents.com.br/api/agents/{agent_id}/execute',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'task': 'Criar endpoint REST para usuarios',
        'instructions': 'Usar Express com validacao Joi'
    }
)
execution_id = resp.json()['executionId']

WebSocket Events

Evento	Descricao
`execution_output`	Chunk de saida do agente (streaming)
`execution_complete`	Execucao finalizada com sucesso
`execution_error`	Erro durante a execucao
`pipeline_step_start`	Inicio de step do pipeline
`pipeline_step_complete`	Step do pipeline finalizado
`pipeline_complete`	Pipeline inteiro finalizado
`pipeline_error`	Erro no pipeline

POST /api/agents/:id/cancel/:executionId Cancelar execucao ativa

Cancela a execucao em andamento. O processo Claude Code sera terminado (SIGTERM).

GET /api/executions/active Listar execucoes ativas

Retorna todas as execucoes em andamento com status, agente e tempo decorrido.

API -- Comunicacao Inter-Agentes

#

Sistema de Message Bus que permite troca de mensagens entre agentes com threads, prioridades e inbox individual.

Tipos de Mensagem

review_request

Solicitacao de revisao

review_response

Resposta de revisao

question / answer

Perguntas entre agentes

task_delegation

Delegacao de tarefas

recommendation

Sugestoes e recomendacoes

correction

Correcoes de problemas

notification

Notificacoes gerais

approval

Aprovacoes de revisao

Prioridades

low | normal | high | critical

POST /api/communication/send Enviar mensagem entre agentes

jsonRequest Body

{
  "from": "agent-uuid-jarvis",
  "to": "agent-uuid-shield",
  "type": "review_request",
  "priority": "high",
  "subject": "Revisar endpoint de autenticacao",
  "content": "Verificar vulnerabilidades OWASP...",
  "threadId": "thread-uuid"
}

GET /api/communication/threads Listar todas as threads

Retorna threads agrupadas por assunto, com contagem de mensagens.

GET /api/communication/inbox/:agentId Inbox de um agente

Mensagens recebidas pelo agente, ordenadas por data.

GET /api/communication/unread/:agentId Contagem de nao-lidas

Retorna o numero de mensagens nao lidas para o agente.

POST /api/communication/read/:messageId Marcar como lida

Marca uma mensagem como lida. Atualiza o status para read.

GET /api/communication/stats Estatisticas de comunicacao

Total de mensagens, threads ativas, mensagens por tipo e prioridade.

API -- Revisoes

#

Motor de revisao automatica entre agentes. Suporta ate 5 rodadas de revisao antes de solicitar aprovacao humana.

GET /api/reviews Listar todas as revisoes

Retorna historico de revisoes com status (pending, approved, rejected).

POST /api/reviews/trigger Disparar revisao

jsonRequest Body

{
  "executionId": "exec-uuid",
  "agentId": "agent-uuid"
}

POST /api/reviews/:id/approve Aprovacao humana

Aprova a revisao. Necessario quando o ciclo automatico atinge o limite de 5 rodadas.

POST /api/reviews/:id/reject Rejeicao humana

Rejeita a revisao e solicita nova execucao com feedback.

GET /api/reviews/stats Estatisticas de revisao

Total de revisoes, taxa de aprovacao, media de rodadas, revisores mais ativos.

Agent Brain System

#

Sistema inteligente de analise, categorizacao e orquestracao de revisoes entre agentes. Implantado na v4.1.

brain.js -- Analise e Categorizacao

Analisa automaticamente o resultado de cada execucao de agente, categorizando por tipo (codigo, documentacao, infraestrutura, seguranca) e selecionando revisores adequados.

Analise de Resultado

Classifica a saida do agente em categorias semanticas automaticamente

Selecao de Revisores

Escolhe o agente mais qualificado para revisar baseado na categoria

POST /api/brain/analyze Analisar resultado de execucao

jsonRequest Body

{
  "executionId": "exec-uuid",
  "result": "Codigo gerado pelo agente..."
}

communication.js -- Message Bus

Barramento de mensagens para comunicacao estruturada entre agentes. Suporta threads, prioridades, inbox individual e limpeza automatica apos 30 dias.

Ate 1000 mensagens sao mantidas em memoria com persistencia debounced (300ms) para disco em data/messages.json. Mensagens mais antigas que 30 dias sao removidas automaticamente.

review-engine.js -- Motor de Revisao

Orquestra ciclos de revisao onde agentes revisam o trabalho uns dos outros. Ao final, solicita confirmacao do operador humano.

Ate 5 Rodadas

Ciclo automatico de revisao com ate 5 iteracoes antes de escalar para humano

Aprovacao Humana

Apos ciclo automatico, requer aprovacao/rejeicao do operador

Persistencia em data/reviews.json com limite de 500 revisoes. Debounce de 300ms para escrita.

Webhooks

#

Webhooks permitem integracoes externas dispararem pipelines automaticamente. A rota POST /hook/:token e publica (nao requer autenticacao JWT).

Webhooks Ativos

Nome	Trigger	Pipeline	Descricao
GitHub Push	`/hook/051906c8...`	Full-Stack	Dispara pipeline completo a cada push
AWS FinOps	`/hook/e0cf2210...`	FinOps	Analise de custos e otimizacao AWS
SIEM Security	`/hook/ece4a028...`	SIEM	Monitoramento de seguranca
Infrastructure	`/hook/8c4e1582...`	Infra	Monitoramento de infraestrutura

Exemplo de Integracao

bashGitHub Webhook

# Disparar webhook manualmente
curl -X POST https://sentinel-agents.com.br/hook/TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repository": { "name": "meu-repo" },
    "commits": [{ "message": "feat: nova funcionalidade" }]
  }'

Agendamentos (Cron)

Nome	Expressao Cron	Descricao
FinOps Daily	`0 8 * * 1-5`	Segunda a sexta as 08:00
SIEM Weekly	`0 6 * * 1`	Toda segunda as 06:00
Infra Daily	`0 7 * * *`	Todos os dias as 07:00
Tasks Daily	`0 9 * * 1-5`	Segunda a sexta as 09:00

Kanban Workflow

#

O fluxo Kanban controla o ciclo de vida de cada tarefa executada pelos agentes, desde a preparacao ate a finalizacao.

Preparacao

Em Execucao

Em Revisao

Correcoes

Homologacao

Finalizado

Preparacao

Tarefa configurada com agente, prompt e parametros. Aguardando inicio.

Em Execucao

Agente processando a tarefa. Output via WebSocket em tempo real.

Em Revisao

Resultado sendo revisado pelo review-engine com agente revisor.

Correcoes

Ajustes solicitados pelo revisor. Ate 5 rodadas automaticas.

Homologacao

Aprovacao humana necessaria. Operador valida o resultado final.

Finalizado

Tarefa concluida e aprovada. Resultado persistido e disponivel.

Guia de Deploy

#

Docker Setup

dockerfileDockerfile

FROM node:22-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY . .
RUN mkdir -p /app/data

EXPOSE 3000

CMD ["node", "server.js"]

yamldocker-compose.yml

version: '3.8'

services:
  agents-orchestrator:
    build: ./agents-orchestrator
    container_name: agents-orchestrator
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - PORT=3000
    networks:
      - agents-net

networks:
  agents-net:
    driver: bridge

Nginx + SSL

nginx/etc/nginx/sites-available/sentinel

server {
    listen 443 ssl http2;
    server_name sentinel-agents.com.br;

    ssl_certificate     /etc/letsencrypt/live/sentinel-agents.com.br/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sentinel-agents.com.br/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    listen 80;
    server_name sentinel-agents.com.br;
    return 301 https://$server_name$request_uri;
}

A configuracao do WebSocket no nginx requer os headers Upgrade e Connection para funcionar corretamente. Sem eles, o streaming de execucao nao funciona.

Comandos de Deploy

bash

# Build e start
docker compose up -d --build

# Ver logs
docker logs -f agents-orchestrator

# Restart
docker compose restart agents-orchestrator

# SSL com Certbot
certbot --nginx -d sentinel-agents.com.br

# Verificar status
curl -s https://sentinel-agents.com.br/api/system/status | jq

Variaveis de Ambiente

#

Variavel	Padrao	Descricao
`NODE_ENV`	development	Ambiente de execucao (production/development)
`PORT`	3000	Porta do servidor HTTP + WebSocket
`JWT_SECRET`	auto-gerado	Segredo para assinatura de tokens JWT
`CLAUDE_BIN_PATH`	/usr/local/bin/claude	Caminho do CLI Claude Code
`MAX_CONCURRENT`	3	Maximo de execucoes simultaneas
`DATA_DIR`	/app/data	Diretorio para persistencia JSON
`GOOGLE_AI_KEY`	--	Chave da Google AI API (Nano Banana, Veo)

Nunca hardcode chaves de API no codigo. Use variaveis de ambiente ou o sistema de secrets dos agentes (POST /api/agents/:id/secrets).

Changelog

#

v4.1 2026-03-14

FEAT Agent Brain System -- analise, categorizacao e selecao de revisores
FEAT Communication.js -- Message Bus inter-agentes com threads e inbox
FEAT Review Engine -- motor de revisao automatica (ate 5 rodadas + aprovacao humana)
FEAT 12 novos endpoints API (communication, reviews, brain)
FEAT Frontend -- secao "Comunicacao" no sidebar
FEAT Sentinel Firewall (porta 3100) -- iptables/nftables/UFW real-time

v4.0 2026-03-10

FEAT Arquitetura baseada em Claude Code CLI (spawn child_process)
FEAT 16 agentes especializados com system prompts otimizados
FEAT Pipelines sequenciais com template {{input}}
FEAT WebSocket com reconexao automatica e backoff exponencial
FEAT 4 webhooks ativos (GitHub Push, AWS FinOps, SIEM, Infra)
FEAT 4 agendamentos cron (FinOps, SIEM, Infra, Tasks)
FEAT Sistema de planos (Enterprise com limites ilimitados)
FIX Correcao de secrets.json para array vazio (resolvia erro all.filter)
FEAT N8N Automation (n8n.sentinel-agents.com.br) com SSL

v3.x 2026-02

FEAT Migracao de MoltBot para Sentinel Agents
FEAT Docker container unico (Node.js 22 Alpine)
FEAT Persistencia JSON em /app/data/
FEAT Frontend SPA Vanilla JS sem framework

Sentinel AgentsDocumentacao Completa

Inicio Rapido

1. Clonar o repositorio

2. Instalar dependencias

3. Iniciar o servidor

Arquitetura do Sistema

Fluxo de Execucao

Pipelines

16 Agentes Especializados

Jarvis

Beatrix

DaVinci

Pythia

Reacto

JavaMax

NodeNinja

Shield

Scribe

Terraform

CloudAWS

CloudAzure

KubeOps

Nexus

Neuron

Lexicon

Stack Tecnologica

Node.js 22 Alpine

Express 4.21

ws 8.18

JSON Persistence

Claude Code CLI

node-cron

Docker

Vanilla JS SPA

JWT + bcrypt

Estrutura de Diretorios

API -- Autenticacao

Request Body

Response (200)

API -- Agentes

API -- Execucao

WebSocket Events

API -- Comunicacao Inter-Agentes

Tipos de Mensagem

review_request

review_response

question / answer

task_delegation

recommendation

correction

notification

approval

Prioridades

API -- Revisoes

Agent Brain System

brain.js -- Analise e Categorizacao

Analise de Resultado

Selecao de Revisores

communication.js -- Message Bus

review-engine.js -- Motor de Revisao

Ate 5 Rodadas

Aprovacao Humana

Webhooks

Webhooks Ativos

Exemplo de Integracao

Agendamentos (Cron)

Kanban Workflow

Preparacao

Em Execucao

Em Revisao

Correcoes

Homologacao

Finalizado

Guia de Deploy

Docker Setup

Nginx + SSL

Comandos de Deploy

Variaveis de Ambiente

Changelog

Sentinel Agents
Documentacao Completa