📚 Documentação Completa

Entenda como funciona a GeniAI Code Platform

🎯 O que é a GeniAI Code Platform?

A GeniAI Code Platform é uma plataforma de agentes de IA inteligentes para atendimento automatizado via WhatsApp. Ela conecta sua conta do Chatwoot com modelos de IA da OpenAI (GPT-4o) para criar atendentes virtuais personalizados.

💡 Em resumo: Você cria "robôs" com personalidades e conhecimentos específicos, e eles respondem automaticamente mensagens do WhatsApp usando inteligência artificial.

✨ Principais Recursos:

  • Agentes Personalizados: Crie atendentes com personalidade, tom e conhecimento específicos
  • Integração WhatsApp: Via Chatwoot (suporta WhatsApp Business API ou Evolution API)
  • IA Avançada: Powered by GPT-4o da OpenAI
  • Multi-Agente: Sistema de especialistas que se alternam automaticamente
  • Histórico de Conversas: Mantém contexto e memória das interações

🏗️ Como Funciona a Arquitetura?

📱 WhatsApp (Cliente envia mensagem)
↓
💬 Chatwoot (Recebe e gerencia conversas)
↓
🔗 Webhook (Envia para a plataforma)
↓
🤖 GeniAI Platform (Processa com IA)
↓
🧠 OpenAI GPT-4o (Gera resposta inteligente)
↓
💬 Chatwoot (Envia resposta)
↓
📱 WhatsApp (Cliente recebe resposta)

🔄 Fluxo Detalhado:

  1. Cliente envia mensagem via WhatsApp
  2. Chatwoot recebe a mensagem e cria/atualiza a conversa
  3. Webhook dispara e envia os dados para a GeniAI Platform
  4. Platform identifica qual agente deve responder (via token do webhook)
  5. Busca o histórico da conversa no banco de dados (contexto)
  6. Envia para OpenAI o system prompt + histórico + nova mensagem
  7. OpenAI gera resposta inteligente e contextualizada
  8. Resposta é enviada de volta ao Chatwoot via API
  9. Histórico é salvo no banco para manter contexto
  10. Cliente recebe a resposta no WhatsApp

🤖 Tipos de Agente

🎯 1. Agente Simples

✅ Use quando: Você precisa de um atendente com um único propósito bem definido.

Como funciona:

  • Você cria 1 agente com um system prompt específico
  • Todas as mensagens são processadas por esse agente
  • O agente mantém contexto da conversa (histórico)
  • Ideal para: SAC geral, suporte técnico, cobrança, agendamentos

Exemplo de System Prompt:

Você é Ana, atendente do SAC do Cartão de Todos.

Sua função:
- Ajudar clientes com dúvidas sobre cartão, faturas e pagamentos
- Ser empática, educada e humanizada
- Resolver problemas de forma prática

Regras:
- Sempre se apresente como Ana
- Use linguagem simples e clara
- Não invente informações
- Mantenha tom profissional mas amigável
📊 Quando usar Agente Simples:
  • Atendimento focado em um tema específico
  • Não precisa de especialização por área
  • Configuração rápida e simples

🔀 2. Multi-Agente (Orquestrador)

✅ Use quando: Você precisa de especialistas diferentes para áreas diferentes do atendimento.

Como funciona:

  • Você cria 1 agente orquestrador (gerente) + vários sub-agentes (especialistas)
  • O orquestrador analisa a mensagem e identifica a intenção do cliente
  • Roteia automaticamente para o sub-agente especializado correto
  • Os sub-agentes têm prompts específicos para suas áreas
  • Ideal para: Onboarding, suporte multi-departamento, vendas complexas

Estrutura:

📋 Agente Orquestrador (Pai)
├─ System Prompt: "Você analisa a mensagem e decide qual especialista deve responder"
├─ Função: Roteamento inteligente
└─ Sub-agentes disponíveis:

    🤖 Sub-Agente 1: Boas-vindas
    ├─ Descrição: "Recepciona novos clientes e dá boas-vindas"
    └─ Quando ativar: Cliente novo, saudações, primeira interação

    🤖 Sub-Agente 2: Cadastro
    ├─ Descrição: "Coleta dados cadastrais do cliente"
    └─ Quando ativar: Cliente quer se cadastrar, preencher formulário

    🤖 Sub-Agente 3: Pagamento
    ├─ Descrição: "Auxilia com pagamentos e negociações"
    └─ Quando ativar: Cliente quer pagar, parcelar, negociar dívida

    🤖 Sub-Agente 4: Suporte
    ├─ Descrição: "Resolve problemas técnicos e dúvidas"
    └─ Quando ativar: Cliente tem problema, dúvida técnica, reclamação

🔍 Como o Orquestrador Decide?

A mágica acontece via OpenAI Function Calling:

  1. O orquestrador recebe a mensagem do cliente
  2. A OpenAI analisa a mensagem junto com as descrições dos sub-agentes
  3. A IA decide qual sub-agente é mais adequado para responder
  4. O sistema executa automaticamente o sub-agente escolhido
  5. O sub-agente gera a resposta com seu prompt especializado
💡 Exemplo prático:
  • Cliente: "Oi, quero parcelar minha dívida"
  • Orquestrador analisa: Intenção = negociação de pagamento
  • Decisão: Roteia para Sub-Agente "Pagamento"
  • Sub-Agente Pagamento responde: "Olá! Vou te ajudar com o parcelamento..."
⚠️ Importante: Para usar Multi-Agente, você precisa:
  1. Criar o agente orquestrador no formulário (tipo: Multi-Agente)
  2. Depois, criar os sub-agentes direto no banco de dados (via Supabase)
  3. Os sub-agentes devem ter o campo parent_agent_id apontando para o orquestrador
Consulte o arquivo GUIA-MULTI-AGENTE.md no projeto para ver os SQLs.

🚀 Passo a Passo: Criar Seu Primeiro Agente

1️⃣ Configurar Chatwoot

  1. Tenha uma instância do Chatwoot funcionando
  2. Configure uma Inbox de WhatsApp (via Evolution API ou WhatsApp Business API)
  3. Anote:
    • Access Token: Profile Settings → Access Token
    • Account ID: Veja na URL: app.chatwoot.com/app/accounts/1/dashboard
    • Inbox ID: Settings → Inboxes → Sua Inbox → URL: .../inboxes/5/settings

2️⃣ Criar Agente na Platform

  1. Acesse Criar Agente
  2. Escolha o tipo:
    • Agente Simples: Para atendimento direto
    • Multi-Agente: Para sistema de especialistas
  3. Preencha os campos:
    • Nome Técnico: ID único (ex: sac-financeiro)
    • Nome de Exibição: Nome amigável (ex: "Ana - SAC Financeiro")
    • System Prompt: Instruções detalhadas para a IA (seja específico!)
    • Dados do Chatwoot: Token, Account ID, Inbox ID
  4. Clique em Criar Agente

3️⃣ Configurar Webhook no Chatwoot

  1. Após criar o agente, copie a Webhook URL gerada
  2. Acesse o Chatwoot: Settings → Inboxes → Sua Inbox → Settings
  3. Cole a URL no campo Webhook URL
  4. Salve

4️⃣ Testar

  1. Envie uma mensagem para o número do WhatsApp conectado
  2. A mensagem vai aparecer no Chatwoot
  3. O webhook dispara automaticamente
  4. O agente processa e responde
  5. Você recebe a resposta no WhatsApp!
✅ Pronto! Seu agente de IA está funcionando e respondendo automaticamente no WhatsApp.

❓ Perguntas Frequentes

Q: Posso ter múltiplos agentes?

R: Sim! Você pode criar quantos agentes quiser. Cada agente terá seu próprio webhook URL. Para usar múltiplos agentes, você pode criar múltiplas Inboxes no Chatwoot (um número para cada) ou usar o sistema Multi-Agente.

Q: Como o agente mantém contexto da conversa?

R: Todo histórico de mensagens é salvo no banco de dados (Supabase) na tabela conversations. A cada nova mensagem, o sistema busca o histórico e envia junto para a OpenAI, permitindo que a IA "lembre" da conversa anterior.

Q: Quanto custa usar a plataforma?

R: A plataforma em si é self-hosted (você hospeda). Os custos são:

  • OpenAI API: ~$0.01 por 1000 tokens (GPT-4o)
  • Chatwoot: Gratuito (self-hosted) ou pago (cloud)
  • WhatsApp: Custos da Meta ou Evolution API (gratuito)

Q: Posso usar outros modelos de IA?

R: Atualmente a plataforma está configurada para GPT-4o da OpenAI. Para usar outros modelos, você precisa modificar o código em src/services/openai.service.js.

Q: Como faço para criar sub-agentes no Multi-Agente?

R: Os sub-agentes precisam ser criados diretamente no banco de dados (Supabase) na tabela sub_agents. Consulte o arquivo GUIA-MULTI-AGENTE.md no projeto para ver os comandos SQL prontos.

Q: O agente funciona 24/7?

R: Sim! Desde que o servidor esteja rodando (via systemd service), o agente responde automaticamente a qualquer hora do dia ou da noite.

Q: Posso desativar um agente temporariamente?

R: Sim! Basta mudar o status do agente no banco de dados para inactive. Quando inativo, o webhook ainda recebe as mensagens, mas o agente não processa nem responde.

🛠️ Tecnologias Utilizadas

  • Backend: Node.js + Express
  • IA: OpenAI GPT-4o (via API)
  • Banco de Dados: Supabase (PostgreSQL)
  • WhatsApp: Chatwoot + Evolution API / WhatsApp Business API
  • Frontend: HTML, CSS, JavaScript (Vanilla)
  • Servidor: Nginx (reverse proxy) + Systemd

🆘 Precisa de Ajuda?

Se você encontrar problemas ou tiver dúvidas:

  • 📖 Consulte o arquivo GUIA-MULTI-AGENTE.md no projeto
  • 🔍 Verifique os logs do sistema: journalctl -u geniai-platform -f
  • 🗄️ Acesse o banco de dados via Supabase Dashboard
  • 💬 Entre em contato com o suporte técnico