🧠 CSuite Next Best Action (NBA) Agent

Decisor contextual final que escolhe qual ação executar agora, usando outputs dos agentes especialistas + Policy Engine + governança existente.

🎯 Visão Geral

O NBA Agent é o ponto final de decisão do ecossistema CSuite. Ele recebe inputs de múltiplos agentes especialistas e decide a próxima melhor ação para cada situação.

Frase-Guia

Pricing decide quanto.
Credit decide se pode.
Offer decide o que.
NBA decide o que fazer agora.

🏗️ Arquitetura

[ Pricing Agent ] ─┐
[ Credit Agent  ] ─┼─▶ [ NBA Decision Engine ] ─▶ Execução / Task / Mensagem
[ Offer Builder ] ─┘

📊 Ações Suportadas

Código	Descrição	Canal
`SEND_WHATSAPP`	Enviar mensagem WhatsApp	whatsapp
`SCHEDULE_CALL`	Agendar ligação	phone
`APPLY_AUTOMATIC_OFFER`	Aplicar oferta automaticamente	portal
`ESCALATE_MANAGER`	Escalar para gerente	internal
`WAIT_NO_ACTION`	Aguardar sem ação	none
`CREATE_TASK_SELLER`	Criar tarefa para vendedor	crm
`BLOCK_ACTION`	Bloquear ação	none

📡 API Endpoints

Método	Endpoint	Descrição
GET	`/`	Info do serviço
GET	`/health`	Health check
POST	`/v1/nba/decide`	Decide próxima melhor ação
GET	`/v1/nba/actions`	Lista ações disponíveis
GET	`/v1/nba/action/{action_id}`	Consulta ação executada
POST	`/v1/nba/action/{action_id}/outcome`	Registra outcome

🔗 URLs de Acesso

Base URL: https://csuite-dev.vallery.com.br/nba
Swagger Docs: https://csuite-dev.vallery.com.br/nba/docs
OpenAPI Spec: https://csuite-dev.vallery.com.br/nba/openapi.json

📦 Exemplo de Uso

Request - Decidir Próxima Ação

curl -X POST "https://csuite-dev.vallery.com.br/nba/v1/nba/decide" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "uuid",
    "org_id": 1,
    "source": {
      "app": "leads-agent",
      "channel": "whatsapp",
      "user_id": "seller:123"
    },
    "subject": {
      "entity_type": "customer",
      "entity_ref": "CUST_000123",
      "seller_id": 123
    },
    "intent": {
      "goal": "convert",
      "horizon_hours": 48,
      "urgency": "high"
    },
    "context": {
      "signals": {
        "stalled": true,
        "sentiment": "neutral"
      },
      "attention": {
        "budget_ok": true
      }
    },
    "agent_outputs": {
      "pricing": { "status": "ok", "price": 1234.56, "margin_pct": 22.4 },
      "credit": { "status": "approved", "limit_available": 50000.0 },
      "offer": { "status": "ok", "offer_type": "bundle" }
    },
    "capabilities": {
      "can_send_whatsapp": true,
      "can_auto_execute": false
    }
  }'

Response

{
  "request_id": "uuid",
  "decision_log_id": 987654,
  "nba": {
    "action": "SEND_WHATSAPP",
    "autonomy_level": "L1",
    "confidence": 0.82,
    "why": {
      "primary_reason": "stalled negotiation + margin ok",
      "reasons": ["credit approved", "offer available"]
    },
    "execution": {
      "channel": "whatsapp",
      "template_ref": "WHATSAPP_CLOSE_01"
    }
  }
}

🔧 Configuração

Variáveis de Ambiente

Variável	Descrição	Default
`MYSQL_HOST`	Host do MySQL	localhost
`MYSQL_PORT`	Porta do MySQL	3306
`MYSQL_USER`	Usuário MySQL	-
`MYSQL_PASSWORD`	Senha MySQL	-
`MYSQL_DB`	Database	csuite_nba
`POLICY_ENGINE_BASE_URL`	URL do Policy Engine	-
`PRICING_API_URL`	URL do Pricing Agent	-
`CREDIT_API_URL`	URL do Credit Agent	-
`OFFERS_API_URL`	URL do Offer Agent	-

🔄 Integração com Outros Agentes

O NBA consome outputs dos seguintes agentes:

Pricing Agent (/pricing) - Decisões de preço e margem
Credit Agent (/credit) - Avaliação de crédito
Offer Builder (/offers) - Construção de ofertas

E valida decisões com:

Policy Engine (/executive) - Governança e políticas

Nba Agent