🏠 Início / 📚 Documentação / Agent Loop E Plataforma / Scia Agent

Scia Agent

🤖 CSuite SCIA — Manual de Uso

Sales Conversation Intelligence Agent

Versão: 1.3.0
Última Atualização: 2026-02-01
Status: ✅ Operacional em Produção
Alinhamento PNL: 110% ✅ (Book Aligned)

📋 Índice

  1. Visão Geral
  2. URLs de Acesso
  3. Endpoints da API
  4. Fluxo de Processamento
  5. Tipos de Análise
  6. Exemplos de Uso
  7. Integração com WhatsApp
  8. Arquitetura
  9. Troubleshooting

🎯 Visão Geral

O CSuite SCIA (Sales Conversation Intelligence Agent) é um agente de inteligência conversacional que analisa conversas de WhatsApp entre vendedores e clientes, identifica sinais linguísticos e operacionais, e gera inteligência acionável para melhorar a performance de vendas.

Funcionalidades Principais

Modos de Operação

Modo Descrição
Produção Usa OpenAI GPT-4.1-mini para análise real
Dry-Run Se OPENAI_API_KEY vazio, retorna dados mock
Human-in-the-Loop NÃO envia mensagens automaticamente para clientes
Automático Celery Beat enfileira mensagens a cada 2 minutos

🔗 URLs de Acesso

Recurso URL
API Base https://csuite.internut.com.br/scia
Swagger/Docs https://csuite.internut.com.br/scia/docs
Health Check https://csuite.internut.com.br/scia/health
OpenAPI JSON https://csuite.internut.com.br/scia/openapi.json

📡 Endpoints da API

GET /scia/health

Health check do serviço.

Resposta:

{
  "status": "ok",
  "service": "csuite-scia",
  "env": "production",
  "ts": "2026-01-21T10:00:00.000000Z"
}

GET /scia/

Informações sobre o serviço e endpoints disponíveis.

Resposta:

{
  "service": "CSuite SCIA",
  "description": "Sales Conversation Intelligence Agent",
  "version": "1.2.0",
  "features": {
    "learning_style": "Detecta estilo representacional (visual/auditory/kinesthetic)",
    "auto_enqueue": "Celery Beat enfileira mensagens a cada 2 minutos",
    "rewrite": "Reescrita inteligente em 3 versões",
    "seller_coaching": "Perfil e coaching personalizado por vendedor"
  },
  "endpoints": {
    "health": "GET /health",
    "status": "GET /status",
    "docs": "GET /docs",
    "enqueue": "POST /enqueue",
    "process": "POST /process/{message_id}",
    "today": "GET /today/{seller_user_id}",
    "today_whatsapp": "GET /today/whatsapp/{seller_user_id}",
    "send_whatsapp": "POST /send/whatsapp/{seller_user_id}",
    "customer_analysis": "GET /customer/{phone}",
    "customer_summary": "GET /customer/{phone}/summary",
    "rewrite": "POST /rewrite",
    "rewrite_bulk": "POST /rewrite/bulk",
    "seller_profile": "GET /seller/{id}/profile",
    "seller_coaching": "GET /seller/{id}/coaching",
    "seller_compare": "GET /seller/{id}/compare"
  }
}

POST /scia/enqueue

Enfileira mensagens pendentes para processamento pelo Worker Celery.

Request:

curl -X POST https://csuite.internut.com.br/scia/enqueue

Resposta:

{
  "enqueued": 15,
  "message": "15 mensagens enfileiradas para processamento"
}

POST /scia/process/{message_id}

Processa uma mensagem específica (geralmente chamado pelo Worker).

Request:

curl -X POST https://csuite.internut.com.br/scia/process/12345

Resposta:

{
  "message_id": 12345,
  "status": "processed",
  "diagnosis": {
    "intent": "buying_signal",
    "sentiment": "positive",
    "urgency": "high",
    "recommended_action": "follow_up_24h"
  }
}

GET /scia/today/{seller_user_id}

Principal endpoint. Retorna as tarefas e insights do dia para um vendedor.

Parâmetros:
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| seller_user_id | int | ID do vendedor |
| sla_minutes | int (query) | SLA para follow-up (padrão: 30) |

Request:

curl "https://csuite.internut.com.br/scia/today/107?sla_minutes=30"

Resposta:

{
  "seller_user_id": 107,
  "date": "2026-01-21",
  "summary": {
    "total_tasks": 8,
    "follow_ups_overdue": 3,
    "closing_moments": 2,
    "stalled_negotiations": 3
  },
  "tasks": [
    {
      "type": "followup_overdue",
      "priority": "high",
      "customer": "João Silva",
      "phone": "5511999999999",
      "last_message_at": "2026-01-20T15:30:00",
      "hours_since_reply": 19,
      "suggested_action": "Retornar cliente - espera há 19 horas",
      "rationale": "Cliente demonstrou interesse em orçamento e aguarda resposta"
    },
    {
      "type": "closing_moment",
      "priority": "high",
      "customer": "Maria Souza",
      "phone": "5511888888888",
      "intent": "ready_to_buy",
      "suggested_action": "Oferecer condições de fechamento",
      "rationale": "Cliente perguntou sobre formas de pagamento e prazos"
    }
  ]
}

GET /scia/today/whatsapp/{seller_user_id}

Retorna as tarefas formatadas para envio via WhatsApp.

Request:

curl "https://csuite.internut.com.br/scia/today/whatsapp/107"

Resposta (texto formatado):

📋 *BRIEFING SCIA - 21/01/2026*

👤 Vendedor: João Vendedor (ID: 107)

📊 *RESUMO DO DIA*
• 🔴 Follow-ups Atrasados: 3
• 🟢 Momentos de Fechamento: 2
• 🟡 Negociações Travadas: 3
• 📈 Total de Tarefas: 8

─────────────────────

🔴 *FOLLOW-UPS ATRASADOS*

1️⃣ *Cliente:* João Silva
   📞 5511999999999
   ⏰ Aguardando há 19 horas
   💡 _Retornar cliente - demonstrou interesse em orçamento_

2️⃣ *Cliente:* Ana Costa
   📞 5511777777777
   ⏰ Aguardando há 25 horas
   💡 _Retornar sobre proposta enviada_

─────────────────────

🟢 *MOMENTOS DE FECHAMENTO*

1️⃣ *Cliente:* Maria Souza
   📞 5511888888888
   🎯 Intenção: Pronto para comprar
   💡 _Oferecer condições de fechamento_

─────────────────────

🟡 *NEGOCIAÇÕES TRAVADAS*

1️⃣ *Cliente:* Paulo Santos
   📞 5511666666666
   📅 Último contato: 5 dias atrás
   💡 _Reativar conversa com nova proposta_

─────────────────────

✅ *Boas vendas!*
🤖 _Gerado por CSuite SCIA_

POST /scia/send/whatsapp/{seller_user_id}

Envia o briefing diário para o WhatsApp do vendedor.

Request:

curl -X POST "https://csuite.internut.com.br/scia/send/whatsapp/107"

Resposta:

{
  "seller_user_id": 107,
  "status": "sent",
  "message": "Briefing enviado para o WhatsApp do vendedor",
  "sent_at": "2026-01-21T08:00:00Z"
}

Nota: Requer WHATSAPP_SEND_WEBHOOK configurado. Se vazio, opera em modo dry-run.

GET /scia/status

(v1.2.0) Retorna status do processamento SCIA.

Request:

curl "https://csuite.internut.com.br/scia/status"

Resposta:

{
  "status": "healthy",
  "messages_24h": {
    "pending": 0,
    "processing": 5,
    "completed": 194,
    "errors": 0,
    "processing_rate_pct": 58.4
  },
  "backlog_7d": 0,
  "nlp_analyses_24h": {
    "total": 150,
    "styles_detected": 3,
    "avg_close_score": 0.45,
    "avg_risk_score": 0.23
  },
  "automation": {
    "celery_beat": "enabled",
    "enqueue_interval": "every 2 minutes",
    "batch_size": 200
  }
}

POST /scia/rewrite

(v1.2.0) Reescreve uma mensagem do vendedor em 3 versões (PNL).

Request:

curl -X POST "https://csuite.internut.com.br/scia/rewrite" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Olá, temos esse produto disponível por R$ 1.500",
    "customer_phone": "5511999999999",
    "learning_style": "visual"
  }'

Resposta:

{
  "success": true,
  "customer_info": {
    "name": "João Silva",
    "stage": "negotiation",
    "learning_style": "visual"
  },
  "rewrite": {
    "original_message": "Olá, temos esse produto disponível por R$ 1.500",
    "version_objective": "Produto disponível: R$ 1.500. Estoque: 5 unidades. Prazo: 3 dias úteis.",
    "version_relational": "João, que bom falar com você! Temos exatamente o que você precisa...",
    "version_decision": "Aproveite: R$ 1.500 com frete grátis até sexta-feira. Posso reservar?",
    "recommended_version": "decision",
    "recommendation_reason": "Cliente em fase de negociação, CTA claro acelera decisão"
  }
}

GET /scia/seller/{id}/profile

(v1.2.0) Retorna perfil completo do vendedor com padrões de comportamento.

Request:

curl "https://csuite.internut.com.br/scia/seller/107/profile?days=30"

Resposta:

{
  "period_days": 30,
  "profile": {
    "seller_user_id": 107,
    "total_conversations": 45,
    "total_closings": 12,
    "close_rate_pct": 26.7,
    "strengths": ["Taxa de fechamento acima da média", "Bom desempenho em negotiation"],
    "weaknesses": ["Objeções não resolvidas: preço"],
    "coaching_tips": ["Estudar rebatimento de objeção 'preço'"]
  }
}

GET /scia/seller/{id}/coaching

(v1.2.0) Retorna dicas de coaching personalizadas.

Request:

curl "https://csuite.internut.com.br/scia/seller/107/coaching"

Resposta:

{
  "seller_user_id": 107,
  "summary": {"total_conversations": 45, "close_rate_pct": 26.7},
  "strengths": ["Alta taxa de fechamento", "Tempo de resposta rápido"],
  "areas_to_improve": ["Objeções de preço"],
  "priority_actions": [
    {"action": "Treinar rebatimento de objeções", "focus": ["preço"], "priority": "alta"}
  ]
}

GET /scia/seller/{id}/compare

(v1.2.0) Compara o vendedor com os top performers.

Request:

curl "https://csuite.internut.com.br/scia/seller/107/compare"

Resposta:

{
  "seller_user_id": 107,
  "your_metrics": {"conversations": 45, "closings": 12, "close_rate_pct": 26.7},
  "top_5_avg": {"close_rate_pct": 32.5},
  "comparison": {"vs_top_close_rate": -5.8, "rank": 3, "total_sellers": 10}
}

🔄 Fluxo de Processamento

┌─────────────────────────────────────────────────────────────────┐
│                    FLUXO DE PROCESSAMENTO SCIA                   │
└─────────────────────────────────────────────────────────────────┘

1. COLETA
   ┌──────────────┐
   │  WhatsApp    │──── Mensagens chegam no sistema ────▶
   │  Messages    │
   └──────────────┘
          │
          ▼
2. ENQUEUE
   ┌──────────────┐
   │ POST /enqueue│──── SP seleciona mensagens pendentes ────▶
   │              │     (sp_scia_pick_messages)
   └──────────────┘
          │
          ▼
3. PROCESSAMENTO ASSÍNCRONO
   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
   │    Redis     │───▶│   Celery     │───▶│   OpenAI     │
   │   (Broker)   │    │   Worker     │    │  GPT-4.1-mini│
   └──────────────┘    └──────────────┘    └──────────────┘
          │                   │
          │                   ▼
4. PERSISTÊNCIA             Salva em:
   ┌──────────────┐         - message_nlp
   │    MySQL     │         - message_responses
   │  (superbot)  │         - conversation_metrics_daily
   └──────────────┘
          │
          ▼
5. CONSULTA
   ┌──────────────┐
   │ GET /today/* │──── Views agregadas retornam tarefas ────▶
   │              │
   └──────────────┘
          │
          ▼
6. ENTREGA
   ┌──────────────┐
   │   WhatsApp   │◀─── Briefing formatado para vendedor
   │   Vendedor   │
   └──────────────┘

📊 Tipos de Análise

1. Follow-up Overdue 🔴

Detecta clientes que aguardam resposta do vendedor.

Campo Descrição
hours_since_reply Horas desde a última mensagem do cliente
sla_minutes SLA configurado (padrão: 30 min)
is_overdue Se excedeu o SLA

Critérios:
- Última mensagem foi do cliente
- Vendedor não respondeu dentro do SLA
- Conversa não está encerrada

2. Closing Moments 🟢

Identifica oportunidades de fechamento baseado em sinais linguísticos.

Sinal Exemplo
ready_to_buy "Vou fechar", "Pode fazer o pedido"
asking_payment "Quais as formas de pagamento?"
asking_deadline "Qual o prazo de entrega?"
price_objection_resolved "Entendi, esse preço está bom"

3. Stalled Negotiations 🟡

Encontra negociações que pararam sem fechamento.

Critério Descrição
days_since_contact Dias desde último contato
was_active Tinha mensagens frequentes antes
no_order Não gerou pedido

💻 Exemplos de Uso

Exemplo 1: Obter Tarefas do Dia

curl "https://csuite.internut.com.br/scia/today/107"

Exemplo 2: Processar Mensagens em Lote

# Enfileira todas as mensagens pendentes
curl -X POST https://csuite.internut.com.br/scia/enqueue

# Resposta
{
  "enqueued": 50,
  "message": "50 mensagens enfileiradas para processamento"
}

Exemplo 3: Briefing Matinal para Vendedor

# 1. Gera o briefing formatado
curl "https://csuite.internut.com.br/scia/today/whatsapp/107"

# 2. Envia para o WhatsApp do vendedor
curl -X POST "https://csuite.internut.com.br/scia/send/whatsapp/107"

Exemplo 4: Integração com Cron (Briefing Automático)

# Adicionar ao crontab
# Envia briefing diário às 08:00
0 8 * * * curl -X POST "https://csuite.internut.com.br/scia/send/whatsapp/107"

📱 Integração com WhatsApp

Configuração

Configure a variável WHATSAPP_SEND_WEBHOOK para habilitar envio de mensagens:

WHATSAPP_SEND_WEBHOOK=https://seu-webhook.com/send

Formato do Webhook

O SCIA envia um POST para o webhook com:

{
  "phone": "5511999999999",
  "message": "📋 *BRIEFING SCIA...*"
}

Modo Dry-Run

Se WHATSAPP_SEND_WEBHOOK estiver vazio, o endpoint /send/whatsapp/* retorna sucesso mas não envia de fato.

🏗️ Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                         ARQUITETURA SCIA                         │
└─────────────────────────────────────────────────────────────────┘

                    ┌─────────────────┐
                    │     Traefik     │
                    │  (Reverse Proxy)│
                    └────────┬────────┘
                             │ /scia
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Docker Swarm                               │
│  ┌──────────────────────┐    ┌────────────────────────────────┐ │
│  │ csuite-scia_csuite-  │    │ csuite-scia_csuite-scia-       │ │
│  │ scia (API)           │    │ worker (Celery)                │ │
│  │ - FastAPI            │    │ - Processa mensagens           │ │
│  │ - Endpoints REST     │    │ - Chama OpenAI                 │ │
│  │ - Swagger UI         │    │ - Salva resultados             │ │
│  └──────────┬───────────┘    └──────────────┬─────────────────┘ │
│             │                               │                    │
│             └───────────┬───────────────────┘                    │
│                         │                                        │
│                         ▼                                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                         Redis                             │   │
│  │                    (Message Broker)                       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ▼
         ┌───────────────────────────────────────┐
         │               MySQL                    │
         │           (schema: superbot)           │
         │                                        │
         │  Tables:                               │
         │  - message_nlp                         │
         │  - conversation_metrics_daily          │
         │                                        │
         │  Views:                                │
         │  - vw_msg_canonical                    │
         │  - vw_msg_with_seller                  │
         │  - vw_scia_followup_overdue            │
         │  - vw_scia_closing_moments             │
         │  - vw_scia_stalled_negotiations        │
         └───────────────────────────────────────┘

Serviços Docker Swarm

Serviço Descrição Porta
csuite-scia_csuite-scia API FastAPI 8000
csuite-scia_csuite-scia-worker Worker Celery -

🔧 Troubleshooting

Erro: "No messages to process"

Causa: Não há mensagens pendentes para processar.

Solução:
1. Verifique se há mensagens novas no sistema
2. Verifique a SP sp_scia_pick_messages
3. Verifique se o limite SCIA_ENQUEUE_LIMIT está correto

Erro: OpenAI Rate Limit

Causa: Muitas requisições para a API da OpenAI.

Solução:
1. Reduza o SCIA_ENQUEUE_LIMIT
2. Aumente o intervalo entre processamentos
3. Verifique sua cota na OpenAI

Erro: "Dry-run mode"

Causa: OPENAI_API_KEY não está configurada.

Solução:
1. Configure a variável em produção:
bash docker secret create openai_api_key /path/to/key.txt
2. Ou adicione ao .env em desenvolvimento

Erro: "WhatsApp not sent"

Causa: WHATSAPP_SEND_WEBHOOK não configurado.

Solução:
1. Configure o webhook de envio
2. Verifique se o endpoint do webhook está acessível

Ver Logs

# Logs da API
docker service logs -f csuite-scia_csuite-scia

# Logs do Worker
docker service logs -f csuite-scia_csuite-scia-worker

📊 Views SQL Utilizadas

vw_msg_canonical

Mensagens normalizadas com campos padronizados.

vw_msg_with_seller

Mensagens com seller_user_id associado.

vw_msg_text_final

Texto final da mensagem (inclui transcrições de áudio).

vw_scia_followup_overdue

-- Clientes aguardando resposta além do SLA
SELECT 
  phone,
  customer_name,
  last_message_at,
  hours_since_reply,
  seller_user_id
FROM vw_scia_followup_overdue
WHERE seller_user_id = 107
  AND hours_since_reply > 0.5  -- SLA 30 min

vw_scia_closing_moments

-- Oportunidades de fechamento
SELECT
  phone,
  customer_name,
  intent,
  last_message_at,
  seller_user_id
FROM vw_scia_closing_moments
WHERE seller_user_id = 107

vw_scia_stalled_negotiations

-- Negociações travadas
SELECT
  phone,
  customer_name,
  days_since_contact,
  seller_user_id
FROM vw_scia_stalled_negotiations
WHERE seller_user_id = 107

Views v1.2.0 - PNL e Vendedor

vw_scia_customer_style

-- Estilo representacional dominante por cliente
SELECT customer_phone, dominant_style, confidence_pct, approach_recommendation
FROM vw_scia_customer_style

vw_scia_seller_style_distribution

-- Distribuição de estilos por vendedor
SELECT seller_user_id, visual_pct, auditory_pct, kinesthetic_pct
FROM vw_scia_seller_style_distribution

vw_scia_processing_status

-- Status de processamento (monitoramento)
SELECT pending_24h, completed_24h, processing_rate_pct, backlog_7d
FROM vw_scia_processing_status

vw_scia_health_score

-- Health score automático com recomendações
SELECT health_status, health_score, recommendation
FROM vw_scia_health_score

vw_scia_seller_patterns

-- Padrões de comportamento por vendedor
SELECT seller_user_id, close_rate_pct, avg_close_score, high_risk_conversations
FROM vw_scia_seller_patterns

vw_scia_seller_ranking

-- Ranking de vendedores
SELECT seller_user_id, close_rate_pct, rank_close_rate, composite_rank
FROM vw_scia_seller_ranking

📝 Notas Importantes

  1. Human-in-the-Loop: O SCIA NÃO envia mensagens automaticamente para clientes. Ele apenas sugere ações para o vendedor.

  2. Modo Dry-Run: Se OPENAI_API_KEY estiver vazio, o sistema retorna dados mock para testes.

  3. Auditabilidade: Todos os diagnósticos incluem o campo rationale explicando o motivo da sugestão.

  4. Secrets Docker: Em produção, credenciais são lidas via arquivos do Docker Swarm (sufixo _FILE).

  5. (v1.2.0) Celery Beat: O enqueue agora é automático a cada 2 minutos via Celery Beat. O serviço csuite-scia-beat precisa estar rodando.

  6. (v1.2.0) Sistemas Representacionais (PNL): O campo learning_style detecta se o cliente é visual, auditivo ou cinestésico baseado em pistas linguísticas.

  7. (v1.2.0) Coaching por Vendedor: Os endpoints /seller/* fornecem análise de padrões e recomendações personalizadas.

📚 Referências

Dúvidas? Entre em contato com a equipe de desenvolvimento.

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir