O que é o AI Router
O AI Router e o ponto único de controle de todas as chamadas de Inteligência Artificial do ConvertaFlow. Toda função que precisa chamar um modelo de linguagem (classificação de intenção, geração de fluxos, agentes de suporte, embeddings) passa obrigatoriamente pelo AI Router.
Isso garante que:
- O provedor e modelo de IA escolhido pelo cliente e respeitado em todas as funções
- Quando o cliente desativa uma função, ela para imediatamente de consumir tokens
- O controle e centralizado: configurar uma vez aplica em todo o sistema
Como funciona
Quando qualquer serviço do ConvertaFlow precisa chamar IA, ele passa pelo AI Router que executa 3 verificações na ordem:
1. Feature esta habilitada?
Verifica no Redis se o toggle da função esta ativado para o tenant. Se desativado, retorna imediatamente com zero tokens consumidos.
2. Qual provedor/modelo usar?
Busca a configuração BYOK (Bring Your Own Key) do tenant:
- Se o cliente configurou sua própria API Key → usa a chave dele
- Se não configurou → usa a chave da plataforma (com limites do plano)
3. Chamada ao LLM
Chama o provedor correto com o modelo escolhido pelo cliente, respeitando o budget de tokens da função.
Provedores suportados
| Provedor | Modelos disponíveis | Tier gratuito? |
|---|---|---|
| Google Gemini | 2.0 Flash, 2.0 Flash Lite, 1.5 Flash, 1.5 Pro | Sim (Flash) |
| OpenAI | GPT-4o, GPT-4o Mini, GPT-4.1 Mini | Não |
| Anthropic Claude | Haiku 4.5, Sonnet 4.6 | Não |
| Groq | Llama 3.3 70B, Llama 3.1 8B, Mixtral 8x7B | Sim |
| DeepSeek | Chat V3, Reasoner R1 | Não |
| Mistral | Large, Small | Não |
O cliente escolhe o provedor e modelo em IA & Agentes > Configuração IA. A escolha vale para todas as funções automaticamente.
Funções controladas pelo AI Router
Detecção de Intenção
- Toggle: Detecção de Intenção (em Minhas Funções IA)
- O que faz: Classifica automaticamente cada mensagem recebida em: compra, suporte, reclamação, curiosidade, saudação, outro
- Quando desativado: Nenhum token e consumido, badge de intenção não aparece no chat
- Budget: ~200 tokens por classificação (com cache de 5 minutos)
Agente IA no Chat
- Toggle: Agente IA no Chat (em Minhas Funções IA)
- O que faz: Permite que a IA responda automaticamente pelas conversas quando o atendente ativa o botao IA
- Quando desativado: Botao IA não aparece no chat, zero tokens
Geração de Fluxos com IA
- O que faz: Gera fluxos visuais de automação a partir de instruções em linguagem natural no Flow Builder
- Usa: O provedor/modelo configurado pelo cliente
Embeddings (Busca Semântica)
- O que faz: Gera vetores para busca inteligente na base de conhecimento, memórias de contato e resumos de conversa
- Nota: Sempre usa OpenAI text-embedding-3-small (compatível com pgvector). Se o cliente tem chave OpenAI configurada, usa a dele.
AI Support (Lia IA)
- O que faz: Agentes de suporte autonomo (CTO, CMO, CSO) que atendem via WebSocket
- Usa: O provedor configurado pelo cliente quando disponível
Auto-move no Pipeline
- Toggle: Auto-move no Pipeline (em Minhas Funções IA)
- O que faz: Move deals automaticamente quando a IA detecta intenção de compra com alta confianca
- Depende de: Detecção de Intenção estar ativada
Auto-prioridade em Reclamações
- Toggle: Auto-prioridade em Reclamações (em Minhas Funções IA)
- O que faz: Define prioridade "Alta" automaticamente quando detecta reclamação
- Depende de: Detecção de Intenção estar ativada
Configuração passo a passo
Configurar provedor de IA
- Va em IA & Agentes > Configuração IA
- Na secao "Provedores de IA", escolha um provedor
- Siga o tutorial para obter a API Key (ex: para Gemini, acesse aistudio.google.com)
- Cole a API Key e clique em Testar Conexão
- Se o teste passar (status "Conectado"), a chave esta pronta
Ativar/desativar funções
- Na mesma pagina, role até "Minhas Funções IA"
- Cada função tem um toggle independente
- Funções desativadas não consomem tokens — garantia absoluta
- O modelo usado por cada função segue o provedor configurado acima
- Clique em Salvar para aplicar
Escolher modelo por função
Ao lado de cada função em "Minhas Funções IA", existe um seletor de modelo. O padrão e o modelo do provedor ativo, mas você pode personalizar:
- Funções simples (intenção, auto-move): use modelos rápidos e baratos (Haiku, Flash, Mini)
- Funções complexas (agente no chat, geração de fluxos): use modelos mais capazes (Sonnet, GPT-4o)
Economia de tokens
O sistema economiza tokens de varias formas antes de chamar a IA:
- Feature desativada? → 0 tokens (toggle controla)
- Bot desativado para o contato? → 0 tokens
- Fluxo ativo respondendo? → 0 tokens (FlowBuilder já responde)
- Intent em cache (últimos 5 min)? → 0 tokens (reutiliza classificação anterior)
- Nada resolve? → Chama IA com budget controlado (~200-500 tokens)
O consumo aparece em IA & Agentes > AI Monitor.
BYOK — Bring Your Own Key
O que e
BYOK permite que o cliente use sua própria API Key de IA. O custo de tokens vai para a conta do cliente, não da plataforma.
Como funciona
- O cliente configura a chave em IA & Agentes > Configuração IA
- O sistema criptografa a chave com Fernet (nunca armazenada em texto puro)
- Todas as funções passam a usar a chave do cliente automaticamente
- Se a chave falhar, o sistema tenta usar a chave da plataforma como fallback
Beneficios para o cliente
- Gemini gratuito: Google oferece tier gratuito para Gemini Flash — classificação de intenção e geração de fluxos ficam gratis
- Groq gratuito: Llama e Mixtral no Groq também são gratuitos
- Controle total: O cliente ve o consumo direto no dashboard do provedor
- Sem limites de plano: Usando BYOK, o limite de tokens do plano não se aplica
Segurança
- API Keys criptografadas com Fernet (derivada da SECRET_KEY da aplicação)
- Keys nunca trafegam em logs ou respostas de API
- Apenas o hash mascarado e exibido na interface (ex:
AIza...xyz9) - Cache BYOK no Redis tem TTL de 24 horas (renovado a cada atualização)
- Isolamento por tenant: cada schema tem sua própria tabela de configurações
Arquivos relacionados
| Arquivo | Função |
|---|---|
| backend-python/app/services/ai/ai_router.py | Roteador central de IA (ponto único) |
| backend-python/app/api/ai.py | Endpoints /ai/process e /ai/classify |
| backend-python/app/api/ai_config.py | Endpoints BYOK (criar, testar, ativar) |
| backend-python/app/models/ai_config.py | Model AIProviderConfig + criptografia |
| backend-python/app/services/ai/token_economy.py | Motor de economia de tokens |
| backend-python/app/services/ai/intent_service.py | Classificador de intenção |
| backend-python/app/services/ai/embedding_service.py | Geração de embeddings |
| backend-python/app/services/flow/flow_ai_generator.py | Geração de fluxos com IA |
| ai-support/app/agents/base.py | Classe base dos agentes de suporte |
| ai-support/app/orchestrator/router.py | Orquestrador do AI Support |
| frontend/src/app/(dashboard)/ai/settings/page.tsx | Pagina de configuração IA |