CCO Agent - Documentação Completa

📋 Visão Geral

O CCO Agent (Chief Content Officer) é um agente executivo do CSuite que otimiza criação e distribuição de conteúdo digital multi-canal. Ele monitora performance de conteúdo, estratégia por canal, calendário editorial, tendências de conteúdo e ROI de conteúdo.

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

🎯 Propósito

O CCO Agent existe para:

Otimizar Criação de Conteúdo: Estratégia e produção de conteúdo digital
Distribuição Multi-Canal: Publicação e distribuição em múltiplos canais
Monitorar Performance: Engajamento, alcance e conversão de conteúdo
Gerenciar Calendário Editorial: Planejamento e publicação de conteúdo
Identificar Tendências: Formatos e temas de conteúdo em alta
Maximizar ROI: Retorno sobre investimento em conteúdo

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Content Performance (engajamento, alcance, conversão)
   ├─ Channel Performance (performance por canal)
   ├─ Editorial Calendar (agendado, publicado, pendente)
   ├─ Content Trends (tendências, formatos)
   └─ Customer Feedback (feedback sobre conteúdo)
   ↓
3. Determine Decision Type
   ├─ CCO.CREATE_CONTENT (oportunidade de criação)
   ├─ CCO.OPTIMIZE_DISTRIBUTION (otimizar distribuição)
   ├─ CCO.ADJUST_CALENDAR (ajustar calendário)
   ├─ CCO.SCALE_CHANNEL (escalar canal)
   └─ CCO.IMPROVE_FORMAT (melhorar formato)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ CREATE_CONTENT_PIECE
   ├─ OPTIMIZE_CONTENT_DISTRIBUTION
   ├─ ADJUST_EDITORIAL_CALENDAR
   ├─ SCALE_CONTENT_CHANNEL
   └─ IMPROVE_CONTENT_FORMAT
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cco/cco_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cco_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cco.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 conteúdo
`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 sobre conteúdo

3. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Visão geral	Performance de canais
`GET /api/csuite/trends`	Tendências	Tendências de conteúdo

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. CMO API

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

Endpoint	Descrição	Uso
`GET /api/content/metrics`	Métricas de conteúdo	Performance de conteúdo
`GET /api/content/calendar`	Calendário editorial	Calendário e publicaçã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_CMO_URL=https://csuite.internut.com.br/cmo

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

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

# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30

YAML Configuration

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

agent:
  agent_code: CCO_AGENT
  name: "CSuite CCO Agent"
  version: "1.0.0"
  status: "active"

  purpose:
    - "Otimizar criação e distribuição de conteúdo digital multi-canal"
    - "Monitorar performance de conteúdo (engajamento, alcance, conversão)"
    # ...

📊 Tipos de Decisão

CCO.CREATE_CONTENT

Quando: Oportunidade identificada para criar novo conteúdo

Ações:
- CREATE_CONTENT_PIECE: Criar novo conteúdo
- Planejamento de conteúdo
- Criação baseada em tendências

Autonomia: L0 (sempre recomendação)

CCO.OPTIMIZE_DISTRIBUTION

Quando: Distribuição de conteúdo pode ser otimizada

Ações:
- OPTIMIZE_CONTENT_DISTRIBUTION: Otimizar distribuição
- Ajuste de canais
- Otimização de timing

Autonomia: L2 (confiança ≥ 0.7)

CCO.ADJUST_CALENDAR

Quando: Calendário editorial precisa de ajustes

Ações:
- ADJUST_EDITORIAL_CALENDAR: Ajustar calendário
- Reagendamento de conteúdo
- Preenchimento de gaps

Autonomia: L1 (confiança ≥ 0.8)

CCO.SCALE_CHANNEL

Quando: Canal de alto desempenho identificado

Ações:
- SCALE_CONTENT_CHANNEL: Escalar canal
- Aumento de frequência
- Expansão de formato

Autonomia: L3 (confiança ≥ 0.9)

CCO.IMPROVE_FORMAT

Quando: Formato de conteúdo pode ser melhorado

Ações:
- IMPROVE_CONTENT_FORMAT: Melhorar formato
- Teste de novos formatos
- Otimização de formatos existentes

Autonomia: L0 (sempre recomendação)

🎚️ Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação - requer aprovação	`decision_type == CREATE_CONTENT OR confidence < 0.7`
L1	Ajustes automáticos de calendário	`decision_type == ADJUST_CALENDAR AND confidence >= 0.8`
L2	Otimização automática de distribuição	`decision_type == OPTIMIZE_DISTRIBUTION AND confidence >= 0.7`
L3	Escalação automática de canais	`decision_type == SCALE_CHANNEL AND confidence >= 0.9`

📝 Schema de Payload

Input

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

Output

{
  "context": "Contexto atual de conteúdo e distribuição",
  "content_performance": {
    "total_content": 45,
    "total_engagement": 12500,
    "total_reach": 85000,
    "total_conversions": 320,
    "avg_engagement_rate": 14.7,
    "avg_reach": 1888,
    "conversion_rate": 2.5,
    "performance_trend": "melhorando"
  },
  "channel_performance": {
    "channels": ["social", "email", "blog"],
    "best_channel": "social",
    "channel_engagement": {
      "social": 8500,
      "email": 3000,
      "blog": 1000
    },
    "channel_reach": {
      "social": 60000,
      "email": 20000,
      "blog": 5000
    }
  },
  "editorial_calendar": {
    "scheduled_content": 12,
    "published_content": 45,
    "pending_content": 3,
    "calendar_gaps": [],
    "calendar_health": "bom"
  },
  "content_trends": {
    "trending_topics": ["IA", "Sustentabilidade", "Produtividade"],
    "trending_formats": ["vídeo", "infográfico", "artigo"],
    "content_trends": [],
    "format_performance": {
      "vídeo": 0.18,
      "infográfico": 0.15,
      "artigo": 0.12
    }
  },
  "opportunities": [
    {
      "type": "CREATE_CONTENT",
      "description": "Oportunidade de criar conteúdo sobre IA",
      "impact": "alto",
      "confidence": 0.85
    }
  ],
  "recommendations": [
    {
      "action": "Aumentar frequência de publicação em redes sociais",
      "reason": "Canal com melhor performance",
      "priority": "alta",
      "expected_impact": "Aumento de 20% em engajamento"
    }
  ],
  "next_steps": [
    "Criar conteúdo sobre IA",
    "Otimizar distribuição em email"
  ]
}

🚀 Uso

Daily Brief (Cron)

O CCO Agent executa um brief diário via cron às 09:15:

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

# Executar manualmente
python3 workflows/scripts/cco_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/cco_agent.log
- Cron: workflows/scripts/cco_agent_cron.log

📈 Métricas Monitoradas

Performance de Conteúdo

Total Content: Número total de conteúdos publicados
Total Engagement: Total de engajamento (likes, shares, comments)
Total Reach: Total de alcance
Total Conversions: Total de conversões
Avg Engagement Rate: Taxa média de engajamento (%)
Avg Reach: Alcance médio por conteúdo
Conversion Rate: Taxa de conversão (%)
Performance Trend: Tendência de performance (melhorando/estável/piorando)

Performance por Canal

Channels: Lista de canais ativos
Best Channel: Canal com melhor performance
Channel Engagement: Engajamento por canal
Channel Reach: Alcance por canal

Calendário Editorial

Scheduled Content: Conteúdo agendado
Published Content: Conteúdo publicado
Pending Content: Conteúdo pendente
Calendar Gaps: Gaps no calendário
Calendar Health: Saúde do calendário (bom/médio/ruim)

Tendências de Conteúdo

Trending Topics: Tópicos em alta
Trending Formats: Formatos em alta
Content Trends: Tendências gerais de conteúdo
Format Performance: Performance por formato

Feedback de Clientes

Total Feedback: Total de feedbacks sobre conteúdo
Positive Rate: Taxa de feedback positivo (%)
Negative Rate: Taxa de feedback negativo (%)
Main Themes: Principais temas do feedback

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

Brief não está sendo gerado

Solução: Verifique os logs:

tail -f workflows/scripts/cco_agent.log

Cron não está executando

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

crontab -l | grep cco_agent

📚 Referências

YAML Config: agents/cco/cco_agent.yaml
README: agents/cco/README.md
Script Python: workflows/scripts/cco_agent_daily_brief.py
Cron Setup: workflows/scripts/setup_cron_cco.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