CMO Agent - Documentação Completa

📋 Visão Geral

O CMO Agent (Chief Marketing Officer) é um agente executivo do CSuite que maximiza crescimento de marca, aquisição de clientes e ROI de campanhas. Ele analisa performance de campanhas, segmentação de clientes, canais de marketing, tendências de mercado e brand awareness.

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

🎯 Propósito

O CMO Agent existe para:

Maximizar Crescimento de Marca: Analisar e otimizar brand awareness e posicionamento
Aquisição de Clientes: Identificar e otimizar canais de aquisição
ROI de Campanhas: Monitorar e otimizar ROI de campanhas de marketing
Segmentação: Analisar e otimizar segmentação de clientes
Insights de Mercado: Identificar tendências, oportunidades e ameaças

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Campaign Performance (ROI, conversão, alcance)
   ├─ Customer Segmentation (segmentos, estratégias)
   ├─ Channel Performance (canais, ROI por canal)
   ├─ Market Insights (tendências, oportunidades)
   └─ Brand Metrics (awareness, posicionamento)
   ↓
3. Determine Decision Type
   ├─ CMO.LAUNCH_CAMPAIGN (oportunidade identificada)
   ├─ CMO.OPTIMIZE_SEGMENTATION (segmentação ineficiente)
   ├─ CMO.SCALE_CHANNEL (canal de alto desempenho)
   └─ CMO.ADJUST_POSITIONING (posicionamento inadequado)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ CREATE_CAMPAIGN
   ├─ OPTIMIZE_SEGMENTATION
   ├─ SCALE_CHANNEL
   └─ ADJUST_BRAND_POSITIONING
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cmo/cmo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cmo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cmo.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
`POST /v1/policy/decisions`	Histórico de decisões	Auditoria

2. Sales Manager API

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

Endpoint	Descrição	Uso
`GET /manager/today`	Tasks do dia	Performance de canais

3. Customer Decisions API

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

Endpoint	Descrição	Uso
`GET /api/customer/segments`	Segmentação	Segmentos de clientes

4. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Overview geral	Performance de campanhas
`GET /api/csuite/trends`	Tendências	Insights de mercado

5. Memory API

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

Endpoint	Descrição	Uso
`POST /v1/memory/query`	Consultar memória	Precedentes e casos similares

📥 Payload de Entrada

Formato

{
  "org_id": 0,
  "as_of_date": "2025-01-04",
  "time_window_days": 30,
  "focus": {
    "themes": ["campaigns", "segmentation", "channels", "brand", "market_insights"],
    "constraints": []
  },
  "attention": {
    "max_recommendations": 3,
    "max_output_tokens": 1200
  }
}

Campos Obrigatórios

org_id (integer): ID da organização
as_of_date (string): Data de referência (YYYY-MM-DD)

Campos Opcionais

time_window_days (integer): Janela de tempo em dias (padrão: 30)
focus.themes (array): Temas de foco
focus.constraints (array): Restrições
attention.max_recommendations (integer): Máximo de recomendações
attention.max_output_tokens (integer): Máximo de tokens de saída

📤 Payload de Saída

Formato

{
  "context": "Contexto atual de marketing e campanhas",
  "campaign_performance": {
    "active_campaigns": 5,
    "total_roi": 2.5,
    "conversion_rate": 0.15,
    "reach": 10000,
    "engagement_rate": 0.08
  },
  "customer_segmentation": {
    "segments": ["Premium", "Standard", "Basic"],
    "segment_growth": {
      "Premium": 0.25,
      "Standard": 0.10,
      "Basic": -0.05
    },
    "segment_roi": {
      "Premium": 3.5,
      "Standard": 2.0,
      "Basic": 1.2
    }
  },
  "channel_performance": {
    "channels": ["Email", "Social", "Paid"],
    "best_channel": "Email",
    "channel_roi": {
      "Email": 4.2,
      "Social": 2.8,
      "Paid": 1.5
    }
  },
  "market_insights": {
    "trends": ["Crescimento em segmento Premium", "Aumento de engajamento em Email"],
    "opportunities": ["Escalar campanha Email", "Otimizar segmento Basic"],
    "threats": ["Concorrência em segmento Standard"]
  },
  "brand_metrics": {
    "awareness_score": 0.75,
    "positioning": "Premium",
    "market_share": 0.15
  },
  "opportunities": [
    {
      "type": "SCALE_CHANNEL",
      "description": "Canal Email com ROI 4.2x - escalar investimento",
      "impact": "alto",
      "confidence": 0.85,
      "roi_estimate": 4.2
    }
  ],
  "recommendations": [
    {
      "action": "Escalar investimento em Email Marketing",
      "reason": "ROI de 4.2x, melhor canal identificado",
      "priority": "alta",
      "expected_roi": 4.2
    }
  ],
  "next_steps": [
    "Aumentar orçamento de Email em 30%",
    "Otimizar segmentação do segmento Basic",
    "Monitorar performance de campanha Social"
  ],
  "generated_at": "2025-01-04T08:30:00",
  "org_id": 0,
  "as_of_date": "2025-01-04"
}

🎯 Tipos de Decisão

CMO.LAUNCH_CAMPAIGN

Quando: Oportunidade de crescimento identificada, ROI estimado alto

Ações:
- CREATE_CAMPAIGN: Criar nova campanha de marketing

Autonomia: L3 (confidence >= 0.9)

CMO.OPTIMIZE_SEGMENTATION

Quando: Segmentação ineficiente, oportunidades de otimização

Ações:
- OPTIMIZE_SEGMENTATION: Otimizar segmentação de clientes

Autonomia: L1 (confidence >= 0.8)

CMO.SCALE_CHANNEL

Quando: Canal de alto desempenho identificado

Ações:
- SCALE_CHANNEL: Escalar investimento em canal

Autonomia: L2 (confidence >= 0.7)

CMO.ADJUST_POSITIONING

Quando: Posicionamento de marca inadequado

Ações:
- ADJUST_BRAND_POSITIONING: Ajustar posicionamento de marca

Autonomia: L0 (sempre recomendação)

🔒 Políticas e Validações

Políticas Locais

Confiança Mínima: 0.7 para ações automáticas
ROI Mínimo: 1.5x para campanhas
Segmentação: Validação de segmentos válidos
Canais: Validação de canais disponíveis

Policy Engine

Decision ID: cmo.marketing_optimization
Fallback: RECOMMEND se Policy Engine indisponível

📊 Métricas e KPIs

Campaign Performance

Active Campaigns: Número de campanhas ativas
Total ROI: ROI agregado de todas as campanhas
Conversion Rate: Taxa de conversão média
Reach: Alcance total
Engagement Rate: Taxa de engajamento

Customer Segmentation

Segments: Lista de segmentos identificados
Segment Growth: Crescimento por segmento
Segment ROI: ROI por segmento

Channel Performance

Channels: Lista de canais ativos
Best Channel: Canal de melhor desempenho
Channel ROI: ROI por canal

Brand Metrics

Awareness Score: Score de brand awareness (0-1)
Positioning: Posicionamento atual da marca
Market Share: Participação de mercado

🚀 Execução

Manual

cd workflows/scripts
python cmo_agent_daily_brief.py

Automática (Cron)

cd workflows/scripts
./setup_cron_cmo.sh

Horário configurado: 08:30 (diário)

Variáveis de Ambiente

OPENAI_API_KEY=sk-...
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_SALES_MANAGER_URL=https://csuite.internut.com.br/sales-manager
CSUITE_CUSTOMER_DECISIONS_URL=https://csuite.internut.com.br/customer-decisions
CSUITE_CONTEXT_URL=https://csuite.internut.com.br
CSUITE_PRICING_URL=https://csuite.internut.com.br/pricing
CMO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/...
ORG_ID=0
TIME_WINDOW_DAYS=30
LLM_MODEL=gpt-4o-mini

📝 Logs

Arquivos de Log

workflows/scripts/cmo_agent.log: Logs do agente
workflows/scripts/cmo_cron.log: Logs do cron
workflows/scripts/cmo_brief_YYYYMMDD_HHMMSS.json: Briefs gerados

Visualizar Logs

# Logs do agente
tail -f workflows/scripts/cmo_agent.log

# Logs do cron
tail -f workflows/scripts/cmo_cron.log

# Último brief gerado
ls -lt workflows/scripts/cmo_brief_*.json | head -1

🔧 Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução: Configure a variável de ambiente OPENAI_API_KEY no arquivo .env

Erro: "Policy Engine retornou 404"

Solução: Verifique se o Policy Engine está rodando e acessível em CSUITE_POLICY_ENGINE_URL

Erro: "Slack retornou 400"

Solução: Verifique se o webhook URL está correto e se o formato da mensagem está válido

Brief não está sendo publicado no Slack

Solução:
1. Verifique se CMO_BRIEF_WEBHOOK_URL está configurada
2. Verifique os logs em cmo_agent.log
3. Teste o webhook manualmente

📚 Documentação Relacionada

YAML Config: agents/cmo/cmo_agent.yaml
README: agents/cmo/README.md
Agentes Propostos: docs/agent/AGENTES_PROPOSTOS.md

✅ Status de Implementação

Data: 2025-01-04

✅ Script Python criado
✅ Cron job configurado (08:30)
✅ YAML de configuração criado
✅ README criado
✅ Documentação completa criada
✅ Integrações implementadas
✅ Publicação no Slack configurada

Pronto para uso em produção!

CMO Agent - Documentação Completa

📋 Visão Geral

🎯 Propósito

🏗️ Arquitetura

Fluxo de Execução

Componentes

🔌 Integrações

1. Policy Engine

2. Sales Manager API

3. Customer Decisions API

4. Context API

5. Memory API

📥 Payload de Entrada

Formato

Campos Obrigatórios

Campos Opcionais

📤 Payload de Saída

Formato

🎯 Tipos de Decisão

CMO.LAUNCH_CAMPAIGN

CMO.OPTIMIZE_SEGMENTATION

CMO.SCALE_CHANNEL

CMO.ADJUST_POSITIONING

🔒 Políticas e Validações

Políticas Locais

Policy Engine

📊 Métricas e KPIs

Campaign Performance

Customer Segmentation

Channel Performance

Brand Metrics

🚀 Execução

Manual

Automática (Cron)

Variáveis de Ambiente

📝 Logs

Arquivos de Log

Visualizar Logs

🔧 Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Erro: "Policy Engine retornou 404"

Erro: "Slack retornou 400"

Brief não está sendo publicado no Slack

📚 Documentação Relacionada

✅ Status de Implementação

🔊 Text-to-Speech