Sales Agent - Documentação Completa

📋 Visão Geral

O Sales Agent é um agente autônomo do CSuite que converte intenção comercial em decisão executável com governança. Ele analisa contexto do cliente (RFM, histórico, crédito), avalia produtos e estoque, e gera decisões comerciais respeitando políticas.

Status: ✅ Template Implementado (v1.0.0) - Pronto para uso

🎯 Propósito

O Sales Agent existe para:

Converter Intenção em Decisão: Transformar intenção comercial em ações executáveis
Governar Decisões: Respeitar políticas de desconto, crédito e autonomia
Automatizar Vendas: Executar ações automaticamente quando confiança é alta
Escalar Complexidade: Escalar para humanos quando necessário

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Customer (RFM, segment, credit)
   ├─ Product (SKU, stock, base_price)
   ├─ Pricing (tier, max_discount)
   └─ History (last_quote, conversion_rate)
   ↓
3. Determine Decision Type
   ├─ SALES.QUOTE (RFM >= 80)
   ├─ SALES.FOLLOW_UP (RFM >= 60)
   └─ SALES.ESCALATION (RFM < 60)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ CREATE_QUOTE
   ├─ SEND_MESSAGE
   ├─ SCHEDULE_FOLLOWUP
   └─ ESCALATE_TO_HUMAN
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/sales/sales_agent.yaml - Configuração canônica
FastAPI Main: agents/sales/main.py - Entrypoint FastAPI
Context Builder: agents/sales/context.py - Constrói contexto
Decision Engine: agents/sales/decision.py - Motor de decisão
Execution Handler: agents/sales/execution.py - Executa ações
Policy Guardrails: agents/sales/policies.py - Validações locais

🔌 Integrações

1. Policy Engine

Base URL: https://csuite.internut.com.br/executive

Endpoint	Descrição	Uso
`POST /v1/policy/evaluate`	Avaliar decisão	Validação de políticas
`POST /v1/policy/decisions`	Histórico de decisões	Auditoria

2. Sales Decision API

Base URL: https://csuite.internut.com.br/sales-decision

Endpoint	Descrição	Uso
`POST /4c/decide`	Decisão 4C Lite	Decisões para revendas

3. Sales Manager API

Base URL: https://csuite.internut.com.br/sales-manager

Endpoint	Descrição	Uso
`GET /manager/today`	Tasks do dia	Lista de tasks
`POST /tasks/{task_id}/complete`	Completar task	Marcar task como concluída

4. Customer Decisions API

Base URL: https://csuite.internut.com.br/customer-decisions

Endpoint	Descrição	Uso
`POST /decide`	Decisão completa	Decisões de clientes

5. Pricing Agent

Base URL: https://csuite.internut.com.br/pricing

Endpoint	Descrição	Uso
`POST /run`	Calcular preço	Cálculo de preço final

📊 Decision Types

SALES.QUOTE

Condição: RFM score >= 80

Ações:
- CREATE_QUOTE - Criar orçamento
- SEND_MESSAGE - Enviar mensagem com orçamento

Autonomia: L2 (Follow-up automático)

SALES.FOLLOW_UP

Condição: RFM score >= 60 e < 80

Ações:
- SCHEDULE_FOLLOWUP - Agendar follow-up
- SEND_MESSAGE - Enviar mensagem de follow-up

Autonomia: L1 (Execução automática)

SALES.ESCALATION

Condição: RFM score < 60 ou confiança < 0.7

Ações:
- ESCALATE_TO_HUMAN - Escalar para humano

Autonomia: L0 (Sempre recomendação)

SALES.REJECT

Condição: Cliente sem crédito ou produto sem estoque

Ações:
- Nenhuma ação (rejeição silenciosa)

⚙️ Configuração

Variáveis de Ambiente

# URLs dos Serviços
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_SALES_DECISION_URL=https://csuite.internut.com.br/sales-decision
CSUITE_SALES_MANAGER_URL=https://csuite.internut.com.br/sales-manager
CSUITE_CUSTOMER_DECISIONS_URL=https://csuite.internut.com.br/customer-decisions
CSUITE_PRICING_URL=https://csuite.internut.com.br/pricing

# Database
DB_HOST=localhost
DB_USER=user
DB_PASSWORD=password
DB_NAME=csuite_agents

🚀 Execução

Via FastAPI

cd agents/sales
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Exemplo de Request

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 0,
    "customer": {
      "id": "123",
      "segment": "PREMIUM",
      "rfm_score": 85,
      "credit_status": "APPROVED"
    },
    "product": {
      "sku": "SKU-001",
      "stock": 10,
      "base_price": 10000
    },
    "pricing": {
      "price_tier": "A",
      "max_discount": 8
    },
    "history": {
      "last_quote_at": "2025-01-01",
      "conversion_rate": 0.3
    }
  }'

Exemplo de Response

{
  "status": "success",
  "agent": "CSuite.Sales.Agent",
  "result": {
    "decision": {
      "decision_type": "SALES.QUOTE",
      "confidence": 0.85,
      "proposed_actions": [
        {
          "type": "CREATE_QUOTE",
          "price": 9200.00,
          "discount_pct": 8.0
        },
        {
          "type": "SEND_MESSAGE",
          "message": "Orçamento especial: R$ 9.200,00"
        }
      ]
    },
    "context": {...},
    "execution": {
      "status": "EXECUTED",
      "actions": [...]
    },
    "decision_log_id": 12345,
    "run_id": 67890
  }
}

📋 Policies

Validações Locais

Confiança Mínima: 0.7
Decisões com confiança < 0.7 são escaladas
RFM Mínimo para Autonomia L1: 70
Clientes com RFM < 70 requerem aprovação humana
Desconto Máximo: 8%
Descontos acima de 8% são bloqueados
Preço Mínimo: > 0
Preços <= 0 são inválidos

Integração com Policy Engine

O Sales Agent integra com o Policy Engine para:
- Validação de políticas de desconto
- Validação de crédito
- Instrumentação de decisões (pg_decision_log)
- Criação de snapshots (ctx_decision_context_snapshot)
- Registro de outcomes (ctx_policy_outcomes)
- Registro de runs (agent_runs)

🔍 Troubleshooting

Erro: "Policy Engine não disponível"

Causa: Policy Engine não está acessível ou importação falhou

Solução:
- Verificar se csuite-executive está rodando
- Verificar caminho de importação em decision.py
- O agente funciona em modo standalone (sem Policy Engine)

Erro: "Confiança baixa"

Causa: RFM score baixo ou estoque indisponível

Solução:
- Verificar RFM score do cliente
- Verificar estoque do produto
- Decisão será escalada automaticamente

Erro: "Desconto máximo excedido"

Causa: Desconto calculado excede 8%

Solução:
- Verificar max_discount no payload
- Desconto será limitado a 8% automaticamente

📚 Documentação Relacionada

Guia de APIs Sales Decision: docs/guides/GUIA_USO_APIS_SALES_DECISION.md
Guia de APIs Sales Manager: docs/guides/GUIA_USO_APIS_SALES_MANAGER.md
Guia de APIs Customer Decisions: docs/guides/GUIA_USO_APIS_CUSTOMER_DECISIONS.md
Pricing Agent: docs/agent/PRICING_AGENT.md
Agent Loop v1: docs/agent/AGENT_LOOP_V1_SPEC.md

🎯 Próximos Passos

Melhorias Sugeridas

Integração com APIs Externas
[ ] Integrar CREATE_QUOTE com sistema de orçamentos real
[ ] Integrar SEND_MESSAGE com WhatsApp/Email
[ ] Integrar SCHEDULE_FOLLOWUP com sistema de agendamento
Melhorias de Decisão
[ ] Integrar com Pricing Agent para cálculo de preço
[ ] Usar Sales Decision API para decisões 4C Lite
[ ] Melhorar cálculo de confiança com ML
Testes e Deploy
[ ] Testes unitários
[ ] Testes de integração
[ ] Deploy em Docker Swarm
[ ] Documentação OpenAPI

Última atualização: 2025-01-04
Versão: 1.0.0