CCUO Agent - Documentação Completa

📋 Visão Geral

O CCUO Agent (Chief Customer Officer) é um agente executivo do CSuite que maximiza relacionamento total com clientes da organização. Ele monitora experiência do cliente (CX), satisfação, retenção, NPS, jornada do cliente e riscos de churn.

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

🎯 Propósito

O CCUO Agent existe para:

Maximizar Relacionamento: Gestão completa do relacionamento com clientes
Otimizar Experiência: Experiência do cliente (CX) em todos os pontos de contato
Aumentar Satisfação: Métricas de satisfação e retenção
Otimizar Jornada: Análise e otimização da jornada do cliente
Monitorar NPS: Net Promoter Score e métricas de relacionamento
Prevenir Churn: Detecção e prevenção de churn

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Customer Experience (CX score, touchpoints, gaps)
   ├─ Customer Satisfaction (satisfaction, retention)
   ├─ NPS Metrics (NPS score, promoters, detractors)
   ├─ Customer Journey (stages, friction points, drop-offs)
   └─ Churn Risk (churn rate, at-risk customers)
   ↓
3. Determine Decision Type
   ├─ CCUO.IMPROVE_EXPERIENCE (melhorar experiência)
   ├─ CCUO.PREVENT_CHURN (prevenir churn)
   ├─ CCUO.STRENGTHEN_RELATIONSHIP (fortalecer relacionamento)
   ├─ CCUO.OPTIMIZE_JOURNEY (otimizar jornada)
   └─ CCUO.INCREASE_SATISFACTION (aumentar satisfação)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ IMPROVE_CUSTOMER_EXPERIENCE
   ├─ PREVENT_CUSTOMER_CHURN
   ├─ STRENGTHEN_CUSTOMER_RELATIONSHIP
   ├─ OPTIMIZE_CUSTOMER_JOURNEY
   └─ INCREASE_CUSTOMER_SATISFACTION
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/ccuo/ccuo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/ccuo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_ccuo.sh - Configuração de cron

🔌 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 de relacionamento
`POST /v1/policy/decisions`	Histórico de decisões	Auditoria

2. Customer Decisions API

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

Endpoint	Descrição	Uso
`GET /api/customer/feedback`	Feedback de clientes	Análise de satisfação
`GET /api/customer/journey`	Jornada do cliente	Análise de jornada

3. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Visão geral	Experiência do cliente e NPS
`GET /api/csuite/trends`	Tendências	Tendências de relacionamento

4. Executive API

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

Endpoint	Descrição	Uso
`POST /v1/memory/query`	Consultar memória	Precedentes e casos similares
`GET /api/cases`	Casos abertos	Oportunidades e riscos

5. CFO-Ops API

Base URL: https://csuite.internut.com.br/cfo-ops

Endpoint	Descrição	Uso
`GET /api/churn`	Riscos de churn	Análise de churn
`GET /api/retention`	Retenção	Métricas de retenção

⚙️ Configuração

Variáveis de Ambiente

# URLs dos Serviços CSuite
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_CONTEXT_URL=https://csuite.internut.com.br
CSUITE_CUSTOMER_DECISIONS_URL=https://csuite.internut.com.br/customer-decisions
CSUITE_CFO_OPS_URL=https://csuite.internut.com.br/cfo-ops

# LLM
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

# Slack
CCUO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/...

# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30

YAML Configuration

O arquivo agents/ccuo/ccuo_agent.yaml contém a configuração canônica do agente:

agent:
  agent_code: CCUO_AGENT
  name: "CSuite CCUO Agent"
  version: "1.0.0"
  status: "active"

  purpose:
    - "Maximizar relacionamento total com clientes da organização"
    - "Monitorar experiência do cliente (CX) em todos os pontos de contato"
    # ...

📊 Tipos de Decisão

CCUO.IMPROVE_EXPERIENCE

Quando: Oportunidade identificada para melhorar experiência do cliente

Ações:
- IMPROVE_CUSTOMER_EXPERIENCE: Melhorar experiência
- Otimização de touchpoints
- Redução de fricção

Autonomia: L1 (confiança ≥ 0.8)

CCUO.PREVENT_CHURN

Quando: Risco de churn identificado

Ações:
- PREVENT_CUSTOMER_CHURN: Prevenir churn
- Ações preventivas
- Engajamento proativo

Autonomia: L3 (confiança ≥ 0.9)

CCUO.STRENGTHEN_RELATIONSHIP

Quando: Oportunidade de fortalecer relacionamento

Ações:
- STRENGTHEN_CUSTOMER_RELATIONSHIP: Fortalecer relacionamento
- Programas de relacionamento
- Engajamento estratégico

Autonomia: L0 (sempre recomendação)

CCUO.OPTIMIZE_JOURNEY

Quando: Jornada do cliente pode ser otimizada

Ações:
- OPTIMIZE_CUSTOMER_JOURNEY: Otimizar jornada
- Redução de pontos de fricção
- Melhoria de conversão

Autonomia: L2 (confiança ≥ 0.7)

CCUO.INCREASE_SATISFACTION

Quando: Satisfação pode ser aumentada

Ações:
- INCREASE_CUSTOMER_SATISFACTION: Aumentar satisfação
- Programas de satisfação
- Resolução de problemas

Autonomia: L0 (sempre recomendação)

🎚️ Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação - requer aprovação	`decision_type == STRENGTHEN_RELATIONSHIP OR confidence < 0.7`
L1	Melhorias automáticas de experiência	`decision_type == IMPROVE_EXPERIENCE AND confidence >= 0.8`
L2	Otimização automática de jornada	`decision_type == OPTIMIZE_JOURNEY AND confidence >= 0.7`
L3	Prevenção automática de churn	`decision_type == PREVENT_CHURN AND confidence >= 0.9`

📝 Schema de Payload

Input

{
  "org_id": 1,
  "as_of_date": "2025-01-05",
  "time_window_days": 30,
  "focus": {
    "themes": ["customer_experience", "satisfaction", "retention"],
    "constraints": []
  },
  "attention": {
    "max_recommendations": 3,
    "max_output_tokens": 1200
  }
}

Output

{
  "context": "Contexto atual de relacionamento com clientes",
  "customer_experience": {
    "cx_score": 82.5,
    "touchpoint_satisfaction": {
      "website": 0.85,
      "support": 0.78,
      "sales": 0.90
    },
    "experience_gaps": [],
    "cx_trend": "melhorando"
  },
  "customer_satisfaction": {
    "satisfaction_score": 4.2,
    "retention_rate": 88.5,
    "total_feedback": 1250,
    "positive_rate": 0.75,
    "negative_rate": 0.10,
    "satisfaction_trend": "melhorando"
  },
  "nps_metrics": {
    "nps_score": 45,
    "promoters": 550,
    "passives": 400,
    "detractors": 150,
    "nps_trend": "melhorando"
  },
  "customer_journey": {
    "journey_stages": ["awareness", "consideration", "purchase", "retention"],
    "friction_points": [],
    "drop_off_points": ["consideration"],
    "conversion_rate_by_stage": {
      "awareness": 0.60,
      "consideration": 0.40,
      "purchase": 0.25
    }
  },
  "churn_risk": {
    "churn_rate": 2.5,
    "at_risk_customers": 45,
    "high_risk_customers": 12,
    "churn_reasons": []
  },
  "risks": [
    {
      "type": "CHURN",
      "description": "Aumento de clientes em risco de churn",
      "severity": "médio",
      "impact": "Pode afetar retenção"
    }
  ],
  "opportunities": [
    {
      "type": "IMPROVE_EXPERIENCE",
      "description": "Oportunidade de melhorar experiência no touchpoint de suporte",
      "impact": "alto",
      "confidence": 0.85
    }
  ],
  "recommendations": [
    {
      "action": "Implementar programa de engajamento para clientes em risco",
      "reason": "Churn rate aumentou nos últimos 30 dias",
      "priority": "alta",
      "expected_impact": "Redução de 30% no churn rate"
    }
  ],
  "next_steps": [
    "Monitorar clientes em risco diariamente",
    "Revisar jornada do cliente em pontos de fricção"
  ]
}

🚀 Uso

Daily Brief (Cron)

O CCUO Agent executa um brief diário via cron às 09:25:

# Configurar cron
cd workflows/scripts
chmod +x setup_cron_ccuo.sh
./setup_cron_ccuo.sh

# Executar manualmente
python3 workflows/scripts/ccuo_agent_daily_brief.py

Verificar Cron Jobs

# Listar cron jobs
crontab -l

# Editar cron jobs
crontab -e

Logs

Os logs são salvos em:
- Console: Saída padrão
- Arquivo: workflows/scripts/ccuo_agent.log
- Cron: workflows/scripts/ccuo_agent_cron.log

📈 Métricas Monitoradas

Experiência do Cliente (CX)

CX Score: Score de experiência do cliente (0-100)
Touchpoint Satisfaction: Satisfação por ponto de contato
Experience Gaps: Gaps identificados na experiência
CX Trend: Tendência da experiência (melhorando/estável/piorando)

Satisfação e Retenção

Satisfaction Score: Score de satisfação (0-5)
Retention Rate: Taxa de retenção (%)
Total Feedback: Total de feedbacks recebidos
Positive Rate: Taxa de feedback positivo (%)
Negative Rate: Taxa de feedback negativo (%)
Satisfaction Trend: Tendência da satisfação

NPS e Relacionamento

NPS Score: Net Promoter Score (-100 a 100)
Promoters: Número de promotores
Passives: Número de passivos
Detractors: Número de detratores
NPS Trend: Tendência do NPS

Jornada do Cliente

Journey Stages: Estágios da jornada
Friction Points: Pontos de fricção identificados
Drop Off Points: Pontos de abandono
Conversion Rate by Stage: Taxa de conversão por estágio

Riscos de Churn

Churn Rate: Taxa de churn (%)
At Risk Customers: Clientes em risco
High Risk Customers: Clientes de alto risco
Churn Reasons: Razões de churn identificadas

🔍 Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução: Configure a variável de ambiente:

export OPENAI_API_KEY=sk-...
# ou adicione ao .env
echo "OPENAI_API_KEY=sk-..." >> workflows/scripts/.env

Erro: "Policy Engine retornou 404"

Solução: Verifique se o Policy Engine está rodando e a URL está correta:

curl https://csuite.internut.com.br/executive/v1/policy/evaluate

Erro: "Slack retornou 400 Bad Request"

Solução: Verifique se o webhook URL está correto e ativo:

echo $CCUO_BRIEF_WEBHOOK_URL

Brief não está sendo gerado

Solução: Verifique os logs:

tail -f workflows/scripts/ccuo_agent.log

Cron não está executando

Solução: Verifique se o cron está configurado:

crontab -l | grep ccuo_agent

📚 Referências

YAML Config: agents/ccuo/ccuo_agent.yaml
README: agents/ccuo/README.md
Script Python: workflows/scripts/ccuo_agent_daily_brief.py
Cron Setup: workflows/scripts/setup_cron_ccuo.sh

✅ Checklist de Implementação

[x] YAML de configuração criado
[x] README criado
[x] Script Python para daily brief criado
[x] Script de setup do cron criado
[x] Documentação completa criada
[ ] Testes manuais realizados
[ ] Cron configurado e testado
[ ] Variáveis de ambiente configuradas
[ ] Webhook do Slack configurado

Última atualização: 2025-01-05