FAQ do Instalador

FAQ

Arquitetura

Quais serviços compoe o Prodgy?

Serviço	Tecnologia	Porta	Função
API	Node.js / Express	4000	Backend principal (auth, workflows, dados)
Web	React / Vite	3000	Frontend SPA
Service	Node.js / BullMQ	5000	Processamento assíncrono de filas
Engine	Python / FastAPI / LangGraph	8001	Orquestração de IA
Studio	React / Vite	5173	Editor visual de workflows
Gateway	Node.js / Express / MCP SDK	3100	Servidor MCP para clientes externos
Agentic	Node.js / Express / AI SDK	3200	Orquestrador de agentes de IA
Assistant	C# / .NET 8	443/8445	Integração com Microsoft Teams
Docs	Astro / Starlight	4321	Documentação

Como os serviços se comunicam?

Via HTTP entre si, com Redis para filas e cache, e PostgreSQL (Supabase) para persistência. A autenticação entre serviços usa tokens via header X-Api-Key.

Quais bancos de dados são utilizados?

PostgreSQL 15+ (Supabase) com extensão pgvector para embeddings vetoriais
Redis 7+ com persistência AOF para filas, cache e dados temporários

Requisitos

Quais são os requisitos de software?

Componente	Versão
Node.js	18.0.0 ou superior
pnpm	8.0.0 ou superior
Turbo	2.0.0 ou superior
Python	3.13.x (apenas para Engine)
Poetry	1.8.0 ou superior (apenas para Engine)
.NET SDK	8.0.x (apenas para Assistant)
Docker	Última versão estável

Quais são os requisitos de hardware?

Dev/Staging: 4 vCPU, 8 GB RAM, 50 GB SSD
Produção: 8+ vCPU, 16+ GB RAM, 100+ GB SSD, Redis e PostgreSQL dedicados

Quais dependências externas são necessárias?

Provedor de IA (obrigatório, ao menos um): OpenAI, Anthropic ou Google
Serviço de email (obrigatório): SendGrid, Resend, SMTP, Microsoft 365 Graph ou Google Workspace
Integração Teams (opcional): Azure AD, Bot Framework, certificado SSL, Windows Server
Armazenamento S3: Supabase Storage ou compatível

Quais portas são utilizadas?

Internas: Service (5000), Gateway (3100), Agentic (3200), Engine (8001), Redis (6379), Redis Commander (8081)
Externas: API (4000), Web (3000), Studio (5173), Assistant (443/8445), Docs (4321)

Configuração de Ambiente

Quais variáveis de ambiente são compartilhadas?

As variáveis compartilhadas (raiz) incluem credenciais do Supabase (URL, anon key, service role key), URLs dos serviços, tokens de comunicação entre serviços, conexão Redis e URLs do frontend.

Cada serviço tem configuração própria?

Sim. Cada serviço possui variáveis específicas:

API: Supabase, CORS, chave de encriptação (mínimo 32 caracteres)
Web: URLs do frontend, Google Tag Manager, OAuth (prefixo VITE_ para variáveis públicas)
Service: Redis, concorrência de filas, max retries, comunicação com Engine
Engine: Supabase e credenciais da API
Gateway: URL e token da API, porta do servidor MCP
Agentic: URL e token da API, token de autenticação de serviço
Studio: URLs do frontend, analytics, OAuth
Assistant: arquivo JSON (appsettings.Production.json) com Azure AD, Teams Bot, Redis

Como gerencio secrets de forma segura?

Nunca comite .env ou appsettings.Production.json no repositório
Use um gerenciador de secrets (Azure Key Vault, HashiCorp Vault)
Gere tokens com alta entropia (mínimo 32 caracteres)
Mantenha tokens únicos por ambiente
Rotacione secrets periodicamente

Por que variáveis VITE_ são públicas?

Variáveis com prefixo VITE_ são incorporadas no bundle do frontend durante o build e ficam visíveis no navegador. Nunca coloque secrets nessas variáveis.

Deploy

Como faco o deploy dos serviços?

A maioria dos serviços usa deploy baseado em containers (Azure Container Apps, ECS, Kubernetes). Exceção: o Assistant roda em VM Windows dedicada.

Quais Dockerfiles estão disponíveis?

Cada serviço tem seu Dockerfile na raiz do respectivo diretório. Serviços Node.js usam node:18-alpine e o Engine usa python:3.13-slim. O TypeScript deve ser compilado antes do build Docker.

Como funciona o pipeline de CI/CD?

O pipeline Azure DevOps suporta 3 ambientes:

Ambiente	Trigger
Development	Branch `main`
Staging	Branch `staging`
Production	Tags git `v*`

O pipeline detecta mudanças e compila apenas os serviços afetados.

Como faco o deploy do Assistant (Teams)?

O Assistant requer deploy especial em VM Windows usando WinRM, NSSM como gerenciador de serviço e deploy de artefatos compilados do .NET.

O que devo verificar após o deploy?

Pre-deploy:

Variáveis de ambiente configuradas
Tokens de comunicação entre serviços
Banco de dados acessível

Pos-deploy:

Health checks de cada serviço
Comunicação entre serviços funcionando
Logs sem erros criticos
Dashboards operacionais

Gateway e Agentic

O que é o Gateway?

O Gateway é o servidor MCP (Model Context Protocol) do Prodgy. Ele permite que clientes MCP externos — como Claude Code, Cursor e Windsurf — acessem as ferramentas, integrações e base de conhecimento do Prodgy via protocolo MCP sobre HTTP.

O que é o Agentic?

O Agentic é o serviço de orquestração de agentes de IA do Prodgy. Ele executa agentes com suporte a múltiplos provedores de LLM (OpenAI, Azure OpenAI, Anthropic, Google) usando o Vercel AI SDK, com endpoints de streaming (SSE) e execução direta.

Quais portas o Gateway e o Agentic utilizam?

Gateway: porta 3100 (variável PRODGY_GATEWAY_PORT)
Agentic: porta 3200 (variável PRODGY_AGENTIC_PORT)

Ambos são serviços internos e não precisam ser expostos publicamente — a comunicação é feita via API.

Como o Gateway se autentica com a API?

O Gateway usa o token PRODGY_API_TOKEN via header X-Api-Key para chamadas de serviço. Além disso, cada requisição MCP de um usuário carrega o token do usuário no header Authorization: Bearer prodgy_xxx, permitindo que a API resolva permissões por usuário.

Como o Agentic se autentica?

O Agentic usa PRODGY_API_TOKEN para comunicar com a API, e recebe requisições autenticadas via PRODGY_AGENTIC_TOKEN no header X-API-Key.

O Agentic precisa de credenciais de LLM?

Não diretamente. Os provedores de LLM são configurados no nível da organização dentro do Prodgy. O Agentic resolve as credenciais automaticamente consultando a API interna.

O Gateway precisa de Redis ou banco de dados?

Não. O Gateway é stateless — ele se comunica exclusivamente com a API do Prodgy via HTTP. Não precisa de Redis, banco de dados ou armazenamento local.

Como monitoro o health do Gateway e do Agentic?

Ambos expõem um endpoint /health que pode ser usado para health checks. Inclua-os no checklist pós-deploy junto aos demais serviços.

Preciso expor o Gateway publicamente?

O Gateway precisa estar acessível pelos clientes MCP dos desenvolvedores. Se os desenvolvedores estão fora da rede interna, o Gateway deve ser exposto via HTTPS. Se estão na mesma rede, pode permanecer interno.

Solução de Problemas

Um serviço não está respondendo. O que verificar?

Verifique se o container está em execução
Confira as variáveis de ambiente (especialmente URLs e tokens)
Teste conectividade com Redis e PostgreSQL
Consulte os logs do serviço

A comunicação entre serviços está falhando. O que fazer?

Verifique se os tokens X-Api-Key estão corretos e idênticos em ambos os serviços. Confirme que as URLs de serviço estão acessíveis na rede interna.

O Engine (IA) está lento ou com erro. O que verificar?

Confirme as credenciais do provedor de IA (OpenAI, Anthropic, Google). Verifique limites de taxa do provedor é a conectividade com o Supabase.

Preciso escalar a infraestrutura. O que considerar?

Redis e PostgreSQL dedicados em produção
Escalar horizontalmente os serviços stateless (API, Web, Engine)
Monitorar consumo de CPU/RAM por serviço
Considerar filas separadas para workloads pesados no Service