CBO Agent - Documentação Completa

📋 Visão Geral

O CBO Agent (Chief Brand Officer) é um agente executivo do CSuite que protege e fortalece a imagem, experiência e promessa da marca. Ele monitora percepção da marca, consistência, posicionamento competitivo, feedback de clientes e experiência da marca.

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

🎯 Propósito

O CBO Agent existe para:

Proteger Imagem da Marca: Monitorar e proteger a percepção e reputação da marca
Fortalecer Experiência: Otimizar a experiência da marca em todos os pontos de contato
Garantir Consistência: Assegurar consistência de marca em todos os canais
Monitorar Posicionamento: Analisar posicionamento competitivo da marca
Detectar Riscos: Identificar riscos à reputação e oportunidades de fortalecimento

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Brand Perception (awareness, sentiment, NPS)
   ├─ Brand Consistency (score, touchpoints, inconsistências)
   ├─ Brand Positioning (market position, competitive rank, market share)
   ├─ Customer Feedback (total, positivo, negativo, temas)
   └─ Brand Experience (score, touchpoint satisfaction, gaps)
   ↓
3. Determine Decision Type
   ├─ CBO.STRENGTHEN_BRAND (oportunidade de fortalecimento)
   ├─ CBO.PROTECT_REPUTATION (risco à reputação)
   ├─ CBO.IMPROVE_CONSISTENCY (inconsistências detectadas)
   ├─ CBO.OPTIMIZE_EXPERIENCE (gaps de experiência)
   └─ CBO.ADJUST_POSITIONING (posicionamento inadequado)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ STRENGTHEN_BRAND_IMAGE
   ├─ PROTECT_BRAND_REPUTATION
   ├─ IMPROVE_BRAND_CONSISTENCY
   ├─ OPTIMIZE_BRAND_EXPERIENCE
   └─ ADJUST_BRAND_POSITIONING
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cbo/cbo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cbo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cbo.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 marca
`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 sentiment sobre marca

3. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Visão geral	Percepção da marca
`GET /api/csuite/trends`	Tendências	Posicionamento competitivo
`GET /api/csuite/opportunities`	Oportunidades	Experiência da marca

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	Riscos e oportunidades

5. CMO API

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

Endpoint	Descrição	Uso
`GET /api/brand/metrics`	Métricas de marca	Consistência de marca

⚙️ 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
CBO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/...

# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30

YAML Configuration

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

agent:
  agent_code: CBO_AGENT
  name: "CSuite CBO Agent"
  version: "1.0.0"
  status: "active"

  purpose:
    - "Proteger e fortalecer a imagem, experiência e promessa da marca"
    - "Monitorar percepção da marca (brand awareness, sentiment, NPS)"
    - "Analisar consistência de marca em todos os pontos de contato"
    # ...

📊 Tipos de Decisão

CBO.STRENGTHEN_BRAND

Quando: Oportunidade identificada para fortalecer a imagem da marca

Ações:
- STRENGTHEN_BRAND_IMAGE: Fortalecer imagem da marca
- Campanhas de brand awareness
- Melhorias de posicionamento

Autonomia: L1-L3 (dependendo da confiança)

CBO.PROTECT_REPUTATION

Quando: Risco identificado à reputação da marca

Ações:
- PROTECT_BRAND_REPUTATION: Proteger reputação
- Resposta a crises
- Mitigação de riscos

Autonomia: L3 (alto threshold, confiança ≥ 0.9)

CBO.IMPROVE_CONSISTENCY

Quando: Inconsistências detectadas na marca

Ações:
- IMPROVE_BRAND_CONSISTENCY: Melhorar consistência
- Padronização de mensagens
- Alinhamento de touchpoints

Autonomia: L1 (confiança ≥ 0.8)

CBO.OPTIMIZE_EXPERIENCE

Quando: Gaps identificados na experiência da marca

Ações:
- OPTIMIZE_BRAND_EXPERIENCE: Otimizar experiência
- Melhorias em pontos de contato
- Personalização de experiência

Autonomia: L2 (confiança ≥ 0.7)

CBO.ADJUST_POSITIONING

Quando: Posicionamento inadequado identificado

Ações:
- ADJUST_BRAND_POSITIONING: Ajustar posicionamento
- Reposicionamento estratégico
- Ajustes de mensagem

Autonomia: L0 (sempre recomendação)

🎚️ Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação - requer aprovação	`decision_type == ADJUST_POSITIONING OR confidence < 0.7`
L1	Melhorias automáticas de consistência	`decision_type == IMPROVE_CONSISTENCY AND confidence >= 0.8`
L2	Otimização automática de experiência	`decision_type == OPTIMIZE_EXPERIENCE AND confidence >= 0.7`
L3	Proteção automática de reputação	`decision_type == PROTECT_REPUTATION AND confidence >= 0.9`

📝 Schema de Payload

Input

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

Output

{
  "context": "Contexto atual da marca e reputação",
  "brand_perception": {
    "awareness_score": 75.5,
    "sentiment_score": 0.65,
    "nps_score": 45,
    "brand_mentions": 1250,
    "sentiment_trend": "melhorando"
  },
  "brand_consistency": {
    "consistency_score": 82.0,
    "touchpoints_analyzed": 15,
    "inconsistencies": [],
    "consistency_trend": "estável"
  },
  "brand_positioning": {
    "market_position": "líder",
    "competitive_rank": 1,
    "market_share": 35.2,
    "differentiation_score": 0.78
  },
  "risks": [
    {
      "type": "REPUTATION",
      "description": "Aumento de menções negativas em redes sociais",
      "severity": "médio",
      "impact": "Pode afetar percepção da marca"
    }
  ],
  "opportunities": [
    {
      "type": "STRENGTHEN_BRAND",
      "description": "Oportunidade de fortalecer presença em novo segmento",
      "impact": "alto",
      "confidence": 0.85
    }
  ],
  "recommendations": [
    {
      "action": "Lançar campanha de fortalecimento de marca",
      "reason": "Awareness está abaixo do ideal para o segmento",
      "priority": "alta",
      "expected_impact": "Aumento de 10% em brand awareness"
    }
  ],
  "next_steps": [
    "Monitorar sentiment diariamente",
    "Revisar consistência em novos touchpoints"
  ]
}

🚀 Uso

Daily Brief (Cron)

O CBO Agent executa um brief diário via cron às 09:10:

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

# Executar manualmente
python3 workflows/scripts/cbo_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/cbo_agent.log
- Cron: workflows/scripts/cbo_agent_cron.log

📈 Métricas Monitoradas

Percepção da Marca

Brand Awareness: Percentual de reconhecimento da marca
Brand Sentiment: Sentimento geral (positivo/negativo)
NPS Score: Net Promoter Score
Brand Mentions: Número de menções da marca
Sentiment Trend: Tendência do sentiment (melhorando/estável/piorando)

Consistência de Marca

Consistency Score: Score de consistência (0-100)
Touchpoints Analyzed: Número de pontos de contato analisados
Inconsistencies: Lista de inconsistências detectadas
Consistency Trend: Tendência da consistência

Posicionamento Competitivo

Market Position: Posição no mercado (líder, desafiante, etc.)
Competitive Rank: Ranking competitivo
Market Share: Participação de mercado (%)
Differentiation Score: Score de diferenciação (0-1)

Experiência da Marca

Experience Score: Score de experiência (0-100)
Touchpoint Satisfaction: Satisfação por ponto de contato
Experience Gaps: Gaps identificados na experiência

Feedback de Clientes

Total Feedback: Total de feedbacks recebidos
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 $CBO_BRIEF_WEBHOOK_URL

Brief não está sendo gerado

Solução: Verifique os logs:

tail -f workflows/scripts/cbo_agent.log

Cron não está executando

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

crontab -l | grep cbo_agent

📚 Referências

YAML Config: agents/cbo/cbo_agent.yaml
README: agents/cbo/README.md
Script Python: workflows/scripts/cbo_agent_daily_brief.py
Cron Setup: workflows/scripts/setup_cron_cbo.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