CCMO Agent - Documentação Completa

📋 Visão Geral

O CCMO Agent (Chief Commercial Officer) é um agente executivo do CSuite que define e executa estratégia comercial da organização. Ele monitora performance comercial, pipeline de vendas, análise de mercado, oportunidades comerciais e desenvolvimento de negócios.

Nota: CCMO = Chief Commercial Officer (diferente de CCO = Chief Content Officer)

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

🎯 Propósito

O CCMO Agent existe para:

Definir Estratégia Comercial: Estratégia comercial da organização
Monitorar Performance Comercial: Resultados de vendas e performance
Analisar Pipeline de Vendas: Pipeline e processos comerciais
Identificar Oportunidades: Oportunidades comerciais e novos negócios
Gerenciar Parcerias: Relacionamento com parceiros estratégicos
Analisar Mercado: Análise de mercado e concorrência

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Sales Performance (total sales, growth, win rate, deal size)
   ├─ Sales Pipeline (pipeline value, stages, deals, health)
   ├─ Market Analysis (trends, competitive landscape, opportunities, threats)
   ├─ Business Opportunities (commercial opportunities, leads, partnerships)
   └─ Revenue Data (commercial revenue, growth, segments)
   ↓
3. Determine Decision Type
   ├─ CCMO.OPTIMIZE_STRATEGY (otimizar estratégia)
   ├─ CCMO.IMPROVE_PIPELINE (melhorar pipeline)
   ├─ CCMO.DEVELOP_PARTNERSHIP (desenvolver parceria)
   ├─ CCMO.EXPAND_MARKET (expandir mercado)
   └─ CCMO.ACCELERATE_SALES (acelerar vendas)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ OPTIMIZE_COMMERCIAL_STRATEGY
   ├─ IMPROVE_SALES_PIPELINE
   ├─ DEVELOP_STRATEGIC_PARTNERSHIP
   ├─ EXPAND_COMMERCIAL_MARKET
   └─ ACCELERATE_COMMERCIAL_SALES
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/ccmo/ccmo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/ccmo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_ccmo.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 comerciais
`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 /api/sales/performance`	Performance comercial	Resultados de vendas
`GET /api/sales/pipeline`	Pipeline de vendas	Análise de pipeline

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`	Visão geral	Visão geral comercial
`GET /api/csuite/trends`	Tendências	Análise de mercado
`GET /api/csuite/opportunities`	Oportunidades	Oportunidades comerciais

5. 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 desafios

6. CRO API

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

Endpoint	Descrição	Uso
`GET /api/revenue`	Receita	Receita comercial
`GET /api/growth`	Crescimento	Crescimento comercial

⚙️ 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_SALES_MANAGER_URL=https://csuite.internut.com.br/sales-manager
CSUITE_CUSTOMER_DECISIONS_URL=https://csuite.internut.com.br/customer-decisions
CSUITE_CRO_URL=https://csuite.internut.com.br/cro

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

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

# Configurações
ORG_ID=1
TIME_WINDOW_DAYS=30

YAML Configuration

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

agent:
  agent_code: CCMO_AGENT
  name: "CSuite CCMO Agent"
  version: "1.0.0"
  status: "active"

  purpose:
    - "Definir e executar estratégia comercial da organização"
    - "Monitorar performance comercial e resultados de vendas"
    # ...

📊 Tipos de Decisão

CCMO.OPTIMIZE_STRATEGY

Quando: Estratégia comercial pode ser otimizada

Ações:
- OPTIMIZE_COMMERCIAL_STRATEGY: Otimizar estratégia
- Ajuste de estratégia comercial
- Otimização de processos

Autonomia: L1 (confiança ≥ 0.8)

CCMO.IMPROVE_PIPELINE

Quando: Pipeline de vendas pode ser melhorado

Ações:
- IMPROVE_SALES_PIPELINE: Melhorar pipeline
- Otimização de pipeline
- Redução de tempo por estágio

Autonomia: L2 (confiança ≥ 0.7)

CCMO.DEVELOP_PARTNERSHIP

Quando: Oportunidade de desenvolver parceria estratégica

Ações:
- DEVELOP_STRATEGIC_PARTNERSHIP: Desenvolver parceria
- Estratégias de parceria
- Análise de parceiros

Autonomia: L0 (sempre recomendação)

CCMO.EXPAND_MARKET

Quando: Oportunidade de expansão de mercado comercial

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

Autonomia: L0 (sempre recomendação)

CCMO.ACCELERATE_SALES

Quando: Oportunidade identificada para acelerar vendas

Ações:
- ACCELERATE_COMMERCIAL_SALES: Acelerar vendas
- Estratégias de aceleração
- Otimização de vendas

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 estratégia	`decision_type == OPTIMIZE_STRATEGY AND confidence >= 0.8`
L2	Melhoria automática de pipeline	`decision_type == IMPROVE_PIPELINE AND confidence >= 0.7`
L3	Aceleração automática de vendas	`decision_type == ACCELERATE_SALES AND confidence >= 0.9`

📝 Schema de Payload

Input

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

Output

{
  "context": "Contexto atual de estratégia comercial",
  "sales_performance": {
    "total_sales": 2500000.00,
    "sales_growth": 18.5,
    "deals_closed": 45,
    "deals_lost": 12,
    "win_rate": 78.9,
    "avg_deal_size": 55555.56,
    "performance_trend": "melhorando"
  },
  "sales_pipeline": {
    "pipeline_value": 5000000.00,
    "pipeline_stages": ["prospecting", "qualification", "proposal", "negotiation", "closed"],
    "deals_by_stage": {
      "prospecting": 20,
      "qualification": 15,
      "proposal": 10,
      "negotiation": 8,
      "closed": 45
    },
    "avg_time_by_stage": {
      "prospecting": 5,
      "qualification": 7,
      "proposal": 10,
      "negotiation": 14
    },
    "pipeline_health": "bom"
  },
  "market_analysis": {
    "market_trends": ["crescimento", "digitalização"],
    "competitive_landscape": {
      "market_share": 0.15,
      "competitors": 5
    },
    "market_opportunities": ["novo segmento", "expansão geográfica"],
    "market_threats": ["novo concorrente"]
  },
  "commercial_opportunities": {
    "total_opportunities": 25,
    "new_business_leads": 15,
    "partnership_opportunities": 5,
    "market_expansion": 5
  },
  "revenue_data": {
    "commercial_revenue": 2500000.00,
    "revenue_growth": 18.5,
    "revenue_by_segment": {
      "enterprise": 1500000.00,
      "smb": 1000000.00
    }
  },
  "challenges": [
    {
      "type": "PIPELINE",
      "description": "Tempo médio no estágio de negociação está alto",
      "severity": "médio",
      "impact": "Pode reduzir win rate"
    }
  ],
  "opportunities": [
    {
      "type": "ACCELERATE_SALES",
      "description": "Pipeline saudável com alta win rate, oportunidade de acelerar",
      "impact": "alto",
      "confidence": 0.85
    }
  ],
  "recommendations": [
    {
      "action": "Acelerar processo de negociação para reduzir tempo médio",
      "reason": "Win rate alto (78.9%) indica oportunidade de acelerar",
      "priority": "alta",
      "expected_impact": "Aumento de 20% em fechamentos mensais"
    }
  ],
  "next_steps": [
    "Otimizar processo de negociação",
    "Desenvolver parcerias estratégicas identificadas"
  ]
}

🚀 Uso

Daily Brief (Cron)

O CCMO Agent executa um brief diário via cron às 09:40:

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

# Executar manualmente
python3 workflows/scripts/ccmo_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/ccmo_agent.log
- Cron: workflows/scripts/ccmo_agent_cron.log

📈 Métricas Monitoradas

Performance Comercial

Total Sales: Vendas totais
Sales Growth: Taxa de crescimento de vendas (%)
Deals Closed: Negócios fechados
Deals Lost: Negócios perdidos
Win Rate: Taxa de vitória (%)
Avg Deal Size: Tamanho médio de negócio
Performance Trend: Tendência de performance (melhorando/estável/piorando)

Pipeline de Vendas

Pipeline Value: Valor total do pipeline
Pipeline Stages: Estágios do pipeline
Deals by Stage: Negócios por estágio
Avg Time by Stage: Tempo médio por estágio (dias)
Pipeline Health: Saúde do pipeline (bom/médio/ruim)

Análise de Mercado

Market Trends: Tendências de mercado
Competitive Landscape: Cenário competitivo
Market Opportunities: Oportunidades de mercado
Market Threats: Ameaças de mercado

Oportunidades Comerciais

Total Opportunities: Total de oportunidades
New Business Leads: Novos leads de negócios
Partnership Opportunities: Oportunidades de parceria
Market Expansion: Expansão de mercado

Receita Comercial

Commercial Revenue: Receita comercial total
Revenue Growth: Taxa de crescimento de receita (%)
Revenue by Segment: Receita por segmento

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

Brief não está sendo gerado

Solução: Verifique os logs:

tail -f workflows/scripts/ccmo_agent.log

Cron não está executando

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

crontab -l | grep ccmo_agent

📚 Referências

YAML Config: agents/ccmo/ccmo_agent.yaml
README: agents/ccmo/README.md
Script Python: workflows/scripts/ccmo_agent_daily_brief.py
Cron Setup: workflows/scripts/setup_cron_ccmo.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