🚀 TechSupport Pro - Multi-Agent System

Plataforma SaaS de Suporte Técnico com Sistema Multi-Agente de IA usando LangGraph e Google Gemini 2.5 Flash

📖 Índice

Sobre o Projeto
Tecnologias
Arquitetura
Requisitos
Instalação
Como Rodar
Como Testar
Documentação API
Estrutura de Pastas
Recursos

🎯 Sobre o Projeto

O TechSupport Pro é uma plataforma completa de atendimento técnico que utiliza Inteligência Artificial para automatizar e otimizar o suporte ao cliente através de um sistema de múltiplos agentes especializados.

💡 Problema que Resolve

❌ Atendimento manual lento e custoso
❌ Tickets criados desnecessariamente para perguntas simples
❌ Falta de triagem inteligente de problemas
❌ Respostas inconsistentes entre atendentes

✅ Nossa Solução

Sistema multi-agente que automaticamente classifica e roteia cada mensagem para o agente especializado:

🤖 FAQ Agent: Responde perguntas comuns instantaneamente
💬 General Support Agent: Investiga consultas ambíguas e complexas
🎫 Support Agent: Cria tickets para problemas que requerem atenção humana
🧠 Orchestrator: Classifica e roteia cada mensagem com IA

🛠 Tecnologias

Backend

FastAPI - Framework web moderno e rápido
LangGraph - Orquestração de agentes com state machine
Google Gemini 2.5 Flash - Modelo de IA generativa
SQLAlchemy (Async) - ORM para banco de dados
PostgreSQL/Neon - Banco de dados relacional
Pydantic V2 - Validação de dados
UV - Gerenciador de pacotes Python ultrarrápido

Frontend

React 19 - Biblioteca JavaScript moderna
TypeScript - Tipagem estática
Vite - Build tool extremamente rápido
Tailwind CSS v4 - Framework CSS utility-first
shadcn/ui - Componentes UI acessíveis
React Router - Roteamento SPA

Infraestrutura

Docker - Containerização
Git - Controle de versão

🏗 Arquitetura

Sistema Multi-Agente (LangGraph)

┌─────────────────────────────────────────────────────────────┐
│                    USUÁRIO ENVIA MENSAGEM                    │
└─────────────────────┬───────────────────────────────────────┘
                      ↓
        ┌─────────────────────────────┐
        │   🧠 ORCHESTRATOR AGENT     │
        │  (Classifica com Gemini)    │
        └─────────────┬───────────────┘
                      ↓
        ┌─────────────────────────────┐
        │   Análise de Intenção       │
        │   - Cumprimentos            │
        │   - Perguntas simples       │
        │   - Consultas ambíguas      │
        │   - Problemas técnicos      │
        └─────────────┬───────────────┘
                      ↓
        ┌─────────────┴─────────────┐
        │      ROTEAMENTO           │
        └───┬─────────┬─────────┬───┘
            ↓         ↓         ↓
    ┌───────────┐ ┌──────────┐ ┌─────────┐
    │ 💡 FAQ    │ │ 💬 GENERAL│ │ 🎫 SUPP │
    │  AGENT    │ │  SUPPORT  │ │   ORT   │
    │           │ │   AGENT   │ │  AGENT  │
    │ Busca KB  │ │ Investiga │ │ Cria    │
    │ Responde  │ │ Esclarece │ │ Ticket  │
    └───────────┘ └──────────┘ └─────────┘
            ↓         ↓         ↓
        ┌─────────────┴─────────────┐
        │   RESPOSTA AO USUÁRIO     │
        └───────────────────────────┘

Fluxo de Dados

Frontend (React)  →  FastAPI Backend  →  LangGraph  →  Gemini 2.5 Flash
      ↓                    ↓                ↓              ↓
   UI/UX            REST API          State Graph    Classificação IA
                                                           ↓
                                                    Knowledge Base
                                                    PostgreSQL/Neon

✅ Requisitos

Essenciais

Python 3.11+ (Download)
Node.js 18+ e pnpm (Download Node)
UV - Package manager Python (Instalação)
Git (Download)

Contas/APIs Necessárias

Google Gemini API Key - Criar chave gratuita
Neon PostgreSQL (ou PostgreSQL local) - Criar conta grátis

Opcional

Docker & Docker Compose - Para deploy containerizado

📦 Instalação

1️⃣ Clonar o Repositório

git clone https://github.com/seu-usuario/techsupport-multi-agents.git
cd techsupport-multi-agents

2️⃣ Instalar UV (se não tiver)

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

3️⃣ Configurar Backend

# Criar e ativar ambiente virtual
uv venv
.venv\Scripts\activate  # Windows
# ou
source .venv/bin/activate  # macOS/Linux

# Instalar dependências
uv sync

# Copiar arquivo de ambiente
copy .env.example .env  # Windows
# ou
cp .env.example .env  # macOS/Linux

4️⃣ Configurar Variáveis de Ambiente

Edite o arquivo .env com suas credenciais:

# Google Gemini API
GOOGLE_API_KEY=sua_chave_api_aqui

# Database (Neon PostgreSQL)
DATABASE_URL=postgresql+asyncpg://user:password@host/dbname

# Opcional - Configurações adicionais
ENVIRONMENT=development
LOG_LEVEL=INFO

🔑 Como obter API Key do Gemini:

Acesse: https://aistudio.google.com/apikey
Faça login com sua conta Google
Clique em "Create API Key"
Copie a chave e cole no .env

5️⃣ Inicializar Banco de Dados

O banco de dados é criado automaticamente ao iniciar a aplicação pela primeira vez.

Seed inicial (opcional):

# Para popular com dados de exemplo
uv run python src/db/migrations/seed.py

6️⃣ Configurar Frontend

cd frontend-tech-support

# Instalar pnpm (se não tiver)
npm install -g pnpm

# Instalar dependências
pnpm install

🚀 Como Rodar

Opção 1: Desenvolvimento Local (Recomendado)

Você precisará de 3 terminais abertos:

Terminal 1 - Backend (FastAPI)

# Ativar ambiente virtual
.venv\Scripts\activate  # Windows
# ou
source .venv/bin/activate  # macOS/Linux

# Iniciar servidor
uv run uvicorn src.api.main:app --reload --port 8000

✅ Backend rodando em: http://localhost:8000
📚 Swagger Docs em: http://localhost:8000/docs

Terminal 2 - Frontend (React + Vite)

cd frontend-tech-support

# Iniciar dev server
pnpm dev

✅ Frontend rodando em: http://localhost:5174

Terminal 3 - Logs/Testes (Opcional)

Use para executar testes, scripts ou visualizar logs adicionais.

Opção 2: Docker Compose

# Build e start
docker-compose up --build

# Parar
docker-compose down

✅ Aplicação completa em: http://localhost:3000

🧪 Como Testar

1. Teste Rápido via Chat UI

Acesse o frontend: http://localhost:5174
Clique em "Iniciar Chat"
Experimente estas mensagens:

Teste FAQ Agent:

"Como resetar minha senha?"
"Quais são os horários de atendimento?"
"O que é a TechSupport Pro?"

Teste General Support Agent:

"Preciso de ajuda"
"Tenho uma dúvida sobre o sistema"
"Olá, bom dia!"

Teste Support Agent (cria ticket):

"Não consigo fazer login há 3 dias. Tentei resetar a senha mas o email não chega. Erro: Connection timeout. URGENTE!"

2. Teste via API (Swagger UI)

Acesse: http://localhost:8000/docs
Clique em "POST /chat/message"
Clique em "Try it out"
Cole este JSON no Request Body:

{
  "message": "Como resetar minha senha?",
  "session_id": "test123"
}

Clique em "Execute"
Veja a resposta com metadata do agente utilizado

3. Teste via cURL

# Enviar mensagem
curl -X POST http://localhost:8000/chat/message \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Como resetar minha senha?",
    "session_id": "test123"
  }'

# Criar ticket
curl -X POST http://localhost:8000/tickets/ \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Erro ao fazer login",
    "description": "Sistema retorna erro 500",
    "priority": "HIGH"
  }'

# Listar Knowledge Base
curl http://localhost:8000/api/knowledge-base/

4. Testar Normalização de Texto

# Script de teste para validar busca com acentos
uv run python test_normalization.py

5. Testar Roteamento de Agentes

# Script que testa os 3 tipos de roteamento
uv run python reseed_kb.py

6. Verificar Logs de Debug

Os logs mostram detalhes do processamento:

[FAQ DEBUG] Query: como resetar senha
[FAQ DEBUG] Keywords extraídos: ['como', 'resetar', 'senha']
[FAQ DEBUG] Item: 'Como resetar senha?' - Score: 6
[FAQ DEBUG] ✅ Melhor match encontrado com score 6

7. Testes Automatizados (Futuro)

# Backend (pytest)
uv run pytest

# Frontend (vitest)
cd frontend-tech-support
pnpm test

📚 Documentação API

Swagger UI (Interativo)

URL: http://localhost:8000/docs
Teste todos os endpoints diretamente no navegador
Veja exemplos de requisições e respostas

ReDoc (Documentação Legível)

URL: http://localhost:8000/redoc
Documentação limpa ideal para referência

Principais Endpoints

Método	Endpoint	Descrição
`POST`	`/chat/message`	Enviar mensagem para sistema multi-agente
`GET`	`/chat/health`	Health check do serviço
`POST`	`/tickets/`	Criar novo ticket
`GET`	`/tickets/`	Listar todos os tickets
`GET`	`/tickets/{id}`	Buscar ticket específico
`GET`	`/api/knowledge-base/`	Listar itens da KB
`POST`	`/api/knowledge-base/`	Criar item na KB
`PUT`	`/api/knowledge-base/{id}`	Atualizar item da KB
`DELETE`	`/api/knowledge-base/{id}`	Deletar item da KB

📖 Veja documentação completa: SWAGGER_DOCS.md

📁 Estrutura de Pastas

techsupport-multi-agents/
├── 📂 src/                          # Código fonte backend
│   ├── 📂 agents/                   # Sistema multi-agente
│   │   ├── orchestrator.py          # Orquestrador LangGraph
│   │   ├── faq_agent.py            # Agente de perguntas frequentes
│   │   ├── support_agent.py        # Agente de criação de tickets
│   │   └── general_support_agent.py # Agente para consultas ambíguas
│   │
│   ├── 📂 api/                      # FastAPI REST API
│   │   ├── main.py                  # App principal com metadata
│   │   └── routes/
│   │       ├── chat.py              # Endpoints de chat
│   │       ├── tickets.py           # Endpoints de tickets
│   │       └── knowledge_base.py    # Endpoints da KB
│   │
│   ├── 📂 db/                       # Banco de dados
│   │   ├── db_connet.py            # Conexão async
│   │   ├── models.py               # Models SQLAlchemy
│   │   └── migrations/
│   │       └── seed.py             # Dados iniciais
│   │
│   └── 📂 utils/                    # Utilitários
│       └── text_utils.py           # Normalização de texto
│
├── 📂 frontend-tech-support/        # Frontend React
│   ├── src/
│   │   ├── components/             # Componentes React
│   │   ├── pages/                  # Páginas (Chat, Admin)
│   │   ├── services/               # APIs e serviços
│   │   ├── contexts/               # React Context (Theme)
│   │   └── styles/                 # CSS global
│   │
│   ├── package.json
│   └── vite.config.ts
│
├── 📄 pyproject.toml                # Dependências Python (UV)
├── 📄 uv.lock                       # Lockfile UV
├── 📄 .env                          # Variáveis de ambiente
├── 📄 .gitignore
└── 📄 README.md                     # Documentação do projeto

🎨 Recursos

✅ Funcionalidades Implementadas

Backend

Frontend

Interface de chat moderna
Painel administrativo da KB
Sistema de temas (claro/escuro/sistema)
Renderização de Markdown
Gerenciamento de sessões
Badge de protocolo de tickets
Loading states e error handling

🔜 Roadmap Futuro

Testes automatizados (pytest + vitest)
Autenticação de usuários (JWT)
Dashboard de analytics
Exportação de relatórios
Integração com Whatsapp
Monitoramento e observabilidade

🎯 Fluxo de Roteamento Completo

1. Usuário envia mensagem
        ↓
2. ORCHESTRATOR analisa com Gemini 2.5 Flash
        ↓
3. Classifica em 3 categorias:
   ├─ FAQ          → Cumprimentos, perguntas diretas na KB
   ├─ GENERAL_SUPPORT → Perguntas ambíguas, investigação necessária
   └─ SUPPORT      → Problemas técnicos detalhados (>30 palavras)
        ↓
4. Executa agente correspondente
   ├─ FAQ: Busca na KB com normalização e scoring
   ├─ GENERAL_SUPPORT: Responde de forma empática e investiga
   └─ SUPPORT: Cria ticket automaticamente
        ↓
5. Retorna resposta com metadata:
   - response: Texto da resposta
   - agent_used: Nome do agente (FAQ/GENERAL_SUPPORT/SUPPORT)
   - decision: Explicação do roteamento
   - confidence: Score de confiança (0.0-1.0)
   - tools_used: Ferramentas utilizadas
   - session_id: ID para continuar conversa

🤝 Contribuindo

Contribuições são bem-vindas!

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'Adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👥 Autores

Seu Nome - GitHub

🆘 Suporte

🐛 Issues: GitHub Issues
📖 Docs: http://localhost:8000/docs

🙏 Agradecimentos

FastAPI - Framework web incrível
LangChain - Ferramentas para LLMs
Google Gemini - Modelo de IA generativa
React - Biblioteca UI
Tailwind CSS - Framework CSS

⭐ Se este projeto te ajudou, considere dar uma estrela no GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
pyproject.toml		pyproject.toml
reseed_kb.py		reseed_kb.py
test_db_connection.py		test_db_connection.py
test_normalization.py		test_normalization.py
update_kb_keywords.py		update_kb_keywords.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

🚀 TechSupport Pro - Multi-Agent System

📖 Índice

🎯 Sobre o Projeto

💡 Problema que Resolve

✅ Nossa Solução

🛠 Tecnologias

Backend

Frontend

Infraestrutura

🏗 Arquitetura

Sistema Multi-Agente (LangGraph)

Fluxo de Dados

✅ Requisitos

Essenciais

Contas/APIs Necessárias

Opcional

📦 Instalação

1️⃣ Clonar o Repositório

2️⃣ Instalar UV (se não tiver)

3️⃣ Configurar Backend

4️⃣ Configurar Variáveis de Ambiente

5️⃣ Inicializar Banco de Dados

6️⃣ Configurar Frontend

🚀 Como Rodar

Opção 1: Desenvolvimento Local (Recomendado)

Terminal 1 - Backend (FastAPI)

Terminal 2 - Frontend (React + Vite)

Terminal 3 - Logs/Testes (Opcional)

Opção 2: Docker Compose

🧪 Como Testar

1. Teste Rápido via Chat UI

2. Teste via API (Swagger UI)

3. Teste via cURL

4. Testar Normalização de Texto

5. Testar Roteamento de Agentes

6. Verificar Logs de Debug

7. Testes Automatizados (Futuro)

📚 Documentação API

Swagger UI (Interativo)

ReDoc (Documentação Legível)

Principais Endpoints

📁 Estrutura de Pastas

🎨 Recursos

✅ Funcionalidades Implementadas

Backend

Frontend

🔜 Roadmap Futuro

🎯 Fluxo de Roteamento Completo

🤝 Contribuindo

📝 Licença

👥 Autores

🆘 Suporte

🙏 Agradecimentos

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages