CXO Agent - Documentação Completa
📋 Visão Geral
O CXO Agent (Chief Experience Officer) é um agente executivo do CSuite que otimiza experiência geral dos produtos e serviços da organização. Ele monitora experiência do usuário (UX), jornada do usuário, feedback de experiência, métricas de produtos e interface (UI).
Status: ✅ Implementado (v1.0.0) - Pronto para uso
🎯 Propósito
O CXO Agent existe para:
- Otimizar Experiência do Usuário (UX): Experiência em produtos e serviços
- Otimizar Jornada: Análise e otimização da jornada do usuário
- Melhorar Interface (UI): Otimização de interface e usabilidade
- Analisar Feedback: Feedback de experiência de usuários
- Detectar Problemas: Problemas de experiência e propor soluções
- Maximizar Satisfação: Satisfação com produtos e serviços
🏗️ Arquitetura
Fluxo de Execução
1. Recebe Payload
↓
2. Build Context
├─ User Experience (UX score, usability, satisfaction)
├─ User Journey (stages, friction points, drop-offs)
├─ Experience Feedback (feedback, UX issues, UI issues)
├─ Product Metrics (usage, adoption, satisfaction)
└─ UI Metrics (UI satisfaction, usability, accessibility)
↓
3. Determine Decision Type
├─ CXO.IMPROVE_UX (melhorar experiência do usuário)
├─ CXO.OPTIMIZE_JOURNEY (otimizar jornada)
├─ CXO.FIX_FRICTION (corrigir pontos de fricção)
├─ CXO.ENHANCE_UI (aprimorar interface)
└─ CXO.INCREASE_SATISFACTION (aumentar satisfação)
↓
4. Calculate Confidence
↓
5. Propose Actions
├─ IMPROVE_USER_EXPERIENCE
├─ OPTIMIZE_USER_JOURNEY
├─ FIX_EXPERIENCE_FRICTION
├─ ENHANCE_USER_INTERFACE
└─ INCREASE_EXPERIENCE_SATISFACTION
↓
6. Policy Validation
↓
7. Policy Engine Integration
↓
8. Execute Actions
↓
9. Record Outcome
Componentes
- YAML Config:
agents/cxo/cxo_agent.yaml- Configuração canônica - Script Python:
workflows/scripts/cxo_agent_daily_brief.py- Execução diária - Cron Setup:
workflows/scripts/setup_cron_cxo.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 experiência |
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 feedback de experiência |
GET /api/customer/journey |
Jornada do cliente | Análise de jornada do usuário |
3. Context API
Base URL: https://csuite.internut.com.br
| Endpoint | Descrição | Uso |
|---|---|---|
GET /api/csuite/overview |
Visão geral | Experiência do usuário |
GET /api/csuite/opportunities |
Oportunidades | Métricas de UI |
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 problemas |
5. CPO API
Base URL: https://csuite.internut.com.br/cpo
| Endpoint | Descrição | Uso |
|---|---|---|
GET /api/product/metrics |
Métricas de produtos | Uso e adoção de produtos |
GET /api/product/feedback |
Feedback de produtos | Feedback sobre produtos |
⚙️ 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_CPO_URL=https://csuite.internut.com.br/cpo
# LLM
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini
# Slack
CXO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/...
# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30
YAML Configuration
O arquivo agents/cxo/cxo_agent.yaml contém a configuração canônica do agente:
agent:
agent_code: CXO_AGENT
name: "CSuite CXO Agent"
version: "1.0.0"
status: "active"
purpose:
- "Otimizar experiência geral dos produtos e serviços da organização"
- "Monitorar experiência do usuário (UX) em produtos e serviços"
# ...
📊 Tipos de Decisão
CXO.IMPROVE_UX
Quando: Oportunidade identificada para melhorar experiência do usuário
Ações:
- IMPROVE_USER_EXPERIENCE: Melhorar experiência
- Otimização de fluxos
- Redução de complexidade
Autonomia: L1 (confiança ≥ 0.8)
CXO.OPTIMIZE_JOURNEY
Quando: Jornada do usuário pode ser otimizada
Ações:
- OPTIMIZE_USER_JOURNEY: Otimizar jornada
- Redução de etapas
- Melhoria de navegação
Autonomia: L2 (confiança ≥ 0.7)
CXO.FIX_FRICTION
Quando: Pontos de fricção identificados
Ações:
- FIX_EXPERIENCE_FRICTION: Corrigir fricção
- Remoção de barreiras
- Simplificação de processos
Autonomia: L3 (confiança ≥ 0.9)
CXO.ENHANCE_UI
Quando: Interface pode ser aprimorada
Ações:
- ENHANCE_USER_INTERFACE: Aprimorar interface
- Melhorias visuais
- Acessibilidade
Autonomia: L0 (sempre recomendação)
CXO.INCREASE_SATISFACTION
Quando: Satisfação pode ser aumentada
Ações:
- INCREASE_EXPERIENCE_SATISFACTION: Aumentar satisfação
- Melhorias de produto
- Melhorias de serviço
Autonomia: L0 (sempre recomendação)
🎚️ Níveis de Autonomia
| Nível | Descrição | Condição |
|---|---|---|
| L0 | Sempre recomendação - requer aprovação | decision_type == ENHANCE_UI OR confidence < 0.7 |
| L1 | Melhorias automáticas de UX | decision_type == IMPROVE_UX AND confidence >= 0.8 |
| L2 | Otimização automática de jornada | decision_type == OPTIMIZE_JOURNEY AND confidence >= 0.7 |
| L3 | Correção automática de fricção | decision_type == FIX_FRICTION AND confidence >= 0.9 |
📝 Schema de Payload
Input
{
"org_id": 1,
"as_of_date": "2025-01-05",
"time_window_days": 30,
"focus": {
"themes": ["user_experience", "ux_ui", "journey"],
"constraints": []
},
"attention": {
"max_recommendations": 3,
"max_output_tokens": 1200
}
}
Output
{
"context": "Contexto atual de experiência de produtos e serviços",
"user_experience": {
"ux_score": 85.5,
"usability_score": 82.0,
"product_satisfaction": 4.3,
"service_satisfaction": 4.1,
"ux_trend": "melhorando"
},
"user_journey": {
"journey_stages": ["onboarding", "usage", "support"],
"friction_points": ["onboarding"],
"drop_off_points": [],
"conversion_rate_by_stage": {
"onboarding": 0.75,
"usage": 0.90,
"support": 0.85
},
"time_by_stage": {
"onboarding": 15,
"usage": 5,
"support": 10
}
},
"experience_feedback": {
"total_feedback": 850,
"positive_rate": 0.78,
"negative_rate": 0.12,
"ux_issues": [],
"ui_issues": ["navigation"]
},
"product_metrics": {
"product_usage": {
"daily_active_users": 1250,
"monthly_active_users": 5000
},
"feature_adoption": {
"feature_a": 0.65,
"feature_b": 0.45
},
"product_satisfaction": 4.2,
"product_issues": []
},
"ui_metrics": {
"ui_satisfaction": 4.0,
"ui_issues": ["navigation"],
"usability_score": 82.0,
"accessibility_score": 88.0
},
"problems": [
{
"type": "UI",
"description": "Navegação confusa identificada",
"severity": "médio",
"impact": "Pode afetar usabilidade"
}
],
"opportunities": [
{
"type": "IMPROVE_UX",
"description": "Oportunidade de melhorar onboarding",
"impact": "alto",
"confidence": 0.85
}
],
"recommendations": [
{
"action": "Simplificar processo de onboarding",
"reason": "Taxa de conversão no onboarding está abaixo do ideal",
"priority": "alta",
"expected_impact": "Aumento de 20% na conversão"
}
],
"next_steps": [
"Revisar fluxo de onboarding",
"Testar nova interface de navegação"
]
}
🚀 Uso
Daily Brief (Cron)
O CXO Agent executa um brief diário via cron às 09:30:
# Configurar cron
cd workflows/scripts
chmod +x setup_cron_cxo.sh
./setup_cron_cxo.sh
# Executar manualmente
python3 workflows/scripts/cxo_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/cxo_agent.log
- Cron: workflows/scripts/cxo_agent_cron.log
📈 Métricas Monitoradas
Experiência do Usuário (UX)
- UX Score: Score de experiência do usuário (0-100)
- Usability Score: Score de usabilidade (0-100)
- Product Satisfaction: Satisfação com produtos (0-5)
- Service Satisfaction: Satisfação com serviços (0-5)
- UX Trend: Tendência da experiência (melhorando/estável/piorando)
Jornada do Usuário
- 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
- Time by Stage: Tempo médio por estágio
Feedback de Experiência
- Total Feedback: Total de feedbacks sobre experiência
- Positive Rate: Taxa de feedback positivo (%)
- Negative Rate: Taxa de feedback negativo (%)
- UX Issues: Problemas de UX identificados
- UI Issues: Problemas de UI identificados
Métricas de Produtos
- Product Usage: Uso de produtos
- Feature Adoption: Adoção de funcionalidades
- Product Satisfaction: Satisfação com produtos
- Product Issues: Problemas de produtos identificados
Métricas de Interface (UI)
- UI Satisfaction: Satisfação com interface
- UI Issues: Problemas de UI identificados
- Usability Score: Score de usabilidade
- Accessibility Score: Score de acessibilidade
🔍 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 $CXO_BRIEF_WEBHOOK_URL
Brief não está sendo gerado
Solução: Verifique os logs:
tail -f workflows/scripts/cxo_agent.log
Cron não está executando
Solução: Verifique se o cron está configurado:
crontab -l | grep cxo_agent
📚 Referências
- YAML Config:
agents/cxo/cxo_agent.yaml - README:
agents/cxo/README.md - Script Python:
workflows/scripts/cxo_agent_daily_brief.py - Cron Setup:
workflows/scripts/setup_cron_cxo.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