CGO Agent - Documentação Completa

📋 Visão Geral

O CGO Agent (Chief Growth Officer) é um agente executivo do CSuite que identifica e maximiza oportunidades de crescimento da organização. Ele monitora crescimento de receita, base de usuários, canais de aquisição, métricas de crescimento (CAC, LTV, MRR, ARR) e funil de conversão.

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

🎯 Propósito

O CGO Agent existe para:

Identificar Oportunidades de Crescimento: Análise contínua de oportunidades
Monitorar Crescimento de Receita: Receita, MRR, ARR e tendências
Monitorar Crescimento de Usuários: Base de usuários e assinantes
Otimizar Canais de Aquisição: Performance e otimização de canais
Analisar Funil de Conversão: Otimização de conversão
Monitorar Métricas de Crescimento: CAC, LTV, LTV/CAC ratio, payback period

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Revenue Growth (revenue, growth, MRR, ARR)
   ├─ User Growth (total users, new users, growth rate)
   ├─ Acquisition Channels (channels, CAC, LTV, performance)
   ├─ Growth Metrics (CAC, LTV, LTV/CAC, payback)
   └─ Conversion Funnel (stages, conversion rates, drop-offs)
   ↓
3. Determine Decision Type
   ├─ CGO.ACCELERATE_GROWTH (acelerar crescimento)
   ├─ CGO.OPTIMIZE_CHANNEL (otimizar canal)
   ├─ CGO.EXPAND_MARKET (expandir mercado)
   ├─ CGO.IMPROVE_CONVERSION (melhorar conversão)
   └─ CGO.SCALE_ACQUISITION (escalar aquisição)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ ACCELERATE_REVENUE_GROWTH
   ├─ OPTIMIZE_ACQUISITION_CHANNEL
   ├─ EXPAND_TO_NEW_MARKET
   ├─ IMPROVE_CONVERSION_FUNNEL
   └─ SCALE_USER_ACQUISITION
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cgo/cgo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cgo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cgo.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 crescimento
`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/segments`	Segmentação	Segmentos de clientes

3. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Visão geral	Crescimento de usuários
`GET /api/csuite/opportunities`	Oportunidades	Funil de conversão

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 gargalos

5. CFO-Ops API

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

Endpoint	Descrição	Uso
`GET /api/revenue`	Receita	Crescimento de receita
`GET /api/growth/metrics`	Métricas de crescimento	CAC, LTV, etc.

6. CRO API

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

Endpoint	Descrição	Uso
`GET /api/growth`	Crescimento	Canais de aquisição
`GET /api/revenue`	Receita	Receita e crescimento

⚙️ 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
CSUITE_CRO_URL=https://csuite.internut.com.br/cro

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

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

# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30

YAML Configuration

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

agent:
  agent_code: CGO_AGENT
  name: "CSuite CGO Agent"
  version: "1.0.0"
  status: "active"

  purpose:
    - "Identificar e maximizar oportunidades de crescimento da organização"
    - "Monitorar crescimento de receita, base de usuários e assinantes"
    # ...

📊 Tipos de Decisão

CGO.ACCELERATE_GROWTH

Quando: Oportunidade identificada para acelerar crescimento

Ações:
- ACCELERATE_REVENUE_GROWTH: Acelerar crescimento de receita
- Estratégias de crescimento
- Otimização de receita

Autonomia: L0 (sempre recomendação)

CGO.OPTIMIZE_CHANNEL

Quando: Canal de aquisição pode ser otimizado

Ações:
- OPTIMIZE_ACQUISITION_CHANNEL: Otimizar canal
- Ajuste de estratégia de canal
- Otimização de CAC

Autonomia: L1 (confiança ≥ 0.8)

CGO.EXPAND_MARKET

Quando: Oportunidade de expansão para novo mercado

Ações:
- EXPAND_TO_NEW_MARKET: Expandir para novo mercado
- Estratégias de expansão
- Análise de novos mercados

Autonomia: L0 (sempre recomendação)

CGO.IMPROVE_CONVERSION

Quando: Funil de conversão pode ser melhorado

Ações:
- IMPROVE_CONVERSION_FUNNEL: Melhorar funil
- Otimização de conversão
- Redução de drop-offs

Autonomia: L2 (confiança ≥ 0.7)

CGO.SCALE_ACQUISITION

Quando: Canal de alto desempenho identificado para escalar

Ações:
- SCALE_USER_ACQUISITION: Escalar aquisição
- Aumento de investimento
- Expansão de canal

Autonomia: L3 (confiança ≥ 0.9)

🎚️ Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação - requer aprovação	`decision_type == EXPAND_MARKET OR confidence < 0.7`
L1	Otimização automática de canais	`decision_type == OPTIMIZE_CHANNEL AND confidence >= 0.8`
L2	Melhoria automática de conversão	`decision_type == IMPROVE_CONVERSION AND confidence >= 0.7`
L3	Escalação automática de aquisição	`decision_type == SCALE_ACQUISITION AND confidence >= 0.9`

📝 Schema de Payload

Input

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

Output

{
  "context": "Contexto atual de crescimento da organização",
  "revenue_growth": {
    "revenue": 1250000.00,
    "revenue_growth": 15.5,
    "mrr": 104166.67,
    "arr": 1250000.00,
    "revenue_trend": "melhorando"
  },
  "user_growth": {
    "total_users": 5000,
    "new_users": 250,
    "user_growth": 5.3,
    "active_users": 3500,
    "user_growth_trend": "melhorando"
  },
  "acquisition_channels": {
    "channels": ["organic", "paid", "referral"],
    "best_channel": "organic",
    "cac_by_channel": {
      "organic": 50.00,
      "paid": 150.00,
      "referral": 30.00
    },
    "ltv_by_channel": {
      "organic": 500.00,
      "paid": 600.00,
      "referral": 450.00
    },
    "channel_performance": {
      "organic": 0.40,
      "paid": 0.35,
      "referral": 0.25
    }
  },
  "growth_metrics": {
    "cac": 100.00,
    "ltv": 550.00,
    "ltv_cac_ratio": 5.5,
    "payback_period": 2,
    "growth_rate": 12.5
  },
  "conversion_funnel": {
    "funnel_stages": ["awareness", "interest", "consideration", "purchase"],
    "conversion_rates": {
      "awareness": 0.60,
      "interest": 0.40,
      "consideration": 0.25,
      "purchase": 0.15
    },
    "drop_off_points": ["consideration"],
    "funnel_health": "bom"
  },
  "bottlenecks": [
    {
      "type": "CONVERSION",
      "description": "Taxa de conversão no estágio de consideração está baixa",
      "severity": "médio",
      "impact": "Pode limitar crescimento"
    }
  ],
  "opportunities": [
    {
      "type": "SCALE_ACQUISITION",
      "description": "Canal orgânico tem melhor LTV/CAC, oportunidade de escalar",
      "impact": "alto",
      "confidence": 0.85
    }
  ],
  "recommendations": [
    {
      "action": "Aumentar investimento em canal orgânico",
      "reason": "Melhor LTV/CAC ratio (10x vs 4x do pago)",
      "priority": "alta",
      "expected_impact": "Aumento de 30% em aquisição com melhor ROI"
    }
  ],
  "next_steps": [
    "Otimizar funil de conversão no estágio de consideração",
    "Escalar investimento em canal orgânico"
  ]
}

🚀 Uso

Daily Brief (Cron)

O CGO Agent executa um brief diário via cron às 09:35:

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

# Executar manualmente
python3 workflows/scripts/cgo_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/cgo_agent.log
- Cron: workflows/scripts/cgo_agent_cron.log

📈 Métricas Monitoradas

Crescimento de Receita

Revenue: Receita total
Revenue Growth: Taxa de crescimento de receita (%)
MRR: Monthly Recurring Revenue
ARR: Annual Recurring Revenue
Revenue Trend: Tendência da receita (melhorando/estável/piorando)

Crescimento de Usuários

Total Users: Total de usuários
New Users: Novos usuários no período
User Growth: Taxa de crescimento de usuários (%)
Active Users: Usuários ativos
User Growth Trend: Tendência do crescimento de usuários

Canais de Aquisição

Channels: Lista de canais ativos
Best Channel: Canal com melhor performance
CAC by Channel: Customer Acquisition Cost por canal
LTV by Channel: Lifetime Value por canal
Channel Performance: Performance relativa por canal

Métricas de Crescimento

CAC: Customer Acquisition Cost
LTV: Lifetime Value
LTV/CAC Ratio: Razão LTV/CAC (ideal > 3)
Payback Period: Período de payback (meses)
Growth Rate: Taxa de crescimento geral (%)

Funil de Conversão

Funnel Stages: Estágios do funil
Conversion Rates: Taxas de conversão por estágio
Drop Off Points: Pontos de abandono
Funnel Health: Saúde do funil (bom/médio/ruim)

🔍 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 $CGO_BRIEF_WEBHOOK_URL

Brief não está sendo gerado

Solução: Verifique os logs:

tail -f workflows/scripts/cgo_agent.log

Cron não está executando

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

crontab -l | grep cgo_agent

📚 Referências

YAML Config: agents/cgo/cgo_agent.yaml
README: agents/cgo/README.md
Script Python: workflows/scripts/cgo_agent_daily_brief.py
Cron Setup: workflows/scripts/setup_cron_cgo.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