CRO Agent - Documentação Completa

📋 Visão Geral

O CRO Agent (Chief Revenue Officer) é um agente autônomo do CSuite que maximiza receita e crescimento sustentável. Ele analisa receita por canal, produto e cliente, monitora performance de vendas, identifica segmentos estratégicos, previne churn e otimiza preços.

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

🎯 Propósito

O CRO Agent existe para:

Maximizar Receita: Analisar e otimizar receita por canal, produto e cliente
Crescimento Sustentável: Identificar oportunidades de crescimento
Performance de Vendas: Monitorar e otimizar performance de vendedores
Prevenção de Churn: Detectar e mitigar riscos de churn
Otimização de Preços: Colaborar com Pricing Agent para otimização

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Revenue (por canal, produto, cliente)
   ├─ Sales Performance (vendedores, metas)
   ├─ Segmentation (segmentos, estratégias)
   ├─ Churn (indicadores, taxa)
   └─ Pricing (oportunidades)
   ↓
3. Determine Decision Type
   ├─ CRO.PRIORITIZE_ACCOUNT (muitas tasks pendentes)
   ├─ CRO.ACTIVATE_CAMPAIGN (crescimento negativo)
   ├─ CRO.ADJUST_TARGET (ajuste de metas)
   └─ CRO.ESCALATE_CHURN (churn alto)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ PRIORITIZE_ACCOUNTS
   ├─ LAUNCH_GROWTH_CAMPAIGN
   ├─ ADJUST_SALES_TARGETS
   └─ CREATE_CHURN_ALERT
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cro/cro_agent.yaml - Configuração canônica
FastAPI Main: agents/cro/main.py - Entrypoint FastAPI
Context Builder: agents/cro/context.py - Constrói contexto
Decision Engine: agents/cro/decision.py - Motor de decisão
Execution Handler: agents/cro/execution.py - Executa ações
Policy Guardrails: agents/cro/policies.py - Validações locais

🔌 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	Lista de tasks
`GET /seller/{seller_id}/today`	Tasks por vendedor	Performance por vendedor
`POST /tasks/{task_id}/complete`	Completar task	Marcar task como concluída

3. Customer Decisions API

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

Endpoint	Descrição	Uso
`POST /decide`	Decisão completa	Decisões de clientes
`GET /segmentation`	Segmentação	Segmentos de clientes

4. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/overview`	Overview	Visão geral de receita
`GET /api/csuite/trends`	Tendências	Tendências de receita
`GET /api/csuite/opportunities`	Oportunidades	Oportunidades de crescimento

5. Pricing Agent

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

Endpoint	Descrição	Uso
`POST /run`	Calcular preço	Otimização de preços
`GET /api/market/context`	Market Intelligence	Inteligência macro e competitiva

6. Execution Bridge

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

Endpoint	Descrição	Uso
`POST /v1/execution/commit`	Commit de Ação	Execução autônoma registrada

📊 Decision Types

CRO.PRIORITIZE_ACCOUNT

Condição: Muitas tasks pendentes (> 100)

Ações:
- PRIORITIZE_ACCOUNTS - Priorizar contas para vendas

Autonomia: L2 (Priorização automática)

CRO.ACTIVATE_CAMPAIGN

Condição: Crescimento negativo (< -5%)

Ações:
- LAUNCH_GROWTH_CAMPAIGN - Lançar campanha de crescimento

Autonomia: L3 (Campanhas automáticas - alto threshold)

CRO.ADJUST_TARGET

Condição: Performance atual vs metas

Ações:
- ADJUST_SALES_TARGETS - Ajustar metas de vendas

Autonomia: L1 (Ajustes automáticos)

CRO.ESCALATE_CHURN

Condição: Taxa de churn alta (> 10%)

Ações:
- CREATE_CHURN_ALERT - Criar alerta de churn

Autonomia: L0 (Sempre recomendação)

CRO.EXECUTE_CONTRACT (Novo)

Condição: Oportunidade clara detectada com confiança > 0.95

Ações:
- commit_action via Execution Bridge

Autonomia: L4 (Execução Autônoma Guardada)

⚙️ Configuração

Variáveis de Ambiente

# URLs dos Serviços
CSUITE_POLICY_ENGINE_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

# Database
DB_HOST=localhost
DB_USER=user
DB_PASSWORD=password
DB_NAME=csuite_agents

🚀 Execução

Via FastAPI

cd agents/cro
./run_server.sh

Exemplo de Request

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 0,
    "as_of_date": "2025-01-04",
    "time_window_days": 30,
    "focus": {
      "themes": ["revenue", "sales_performance", "churn"]
    }
  }'

Exemplo de Response

{
  "status": "success",
  "agent": "CSuite.CRO.Agent",
  "result": {
    "decision": {
      "decision_type": "CRO.PRIORITIZE_ACCOUNT",
      "confidence": 0.75,
      "proposed_actions": [
        {
          "type": "PRIORITIZE_ACCOUNTS",
          "tasks_pending": 150,
          "sellers": [...]
        }
      ]
    },
    "context": {...},
    "execution": {
      "status": "EXECUTED",
      "actions": [...]
    },
    "decision_log_id": 12345,
    "run_id": 67890
  }
}

📋 Policies

Validações Locais

Confiança Mínima: 0.6
Decisões com confiança < 0.6 são escaladas
Dados Mínimos: Requer dados de receita ou vendas
Contexto vazio é rejeitado
Autonomia: Respeita níveis de autonomia por tipo de decisão
ESCALATE_CHURN sempre requer aprovação
ACTIVATE_CAMPAIGN requer confiança >= 0.9

Integração com Policy Engine

O CRO Agent integra com o Policy Engine para:
- Validação de políticas de receita
- Validação de autonomia
- Instrumentação de decisões (pg_decision_log)
- Criação de snapshots (ctx_decision_context_snapshot)
- Registro de outcomes (ctx_policy_outcomes)
- Registro de runs (agent_runs)

🔍 Troubleshooting

Erro: "Policy Engine não disponível"

Causa: Policy Engine não está acessível ou importação falhou

Solução:
- Verificar se csuite-executive está rodando
- Verificar caminho de importação em decision.py
- O agente funciona em modo standalone (sem Policy Engine)

Erro: "Confiança baixa"

Causa: Dados insuficientes ou qualidade baixa

Solução:
- Verificar disponibilidade de APIs (Sales Manager, Context, Customer Decisions)
- Verificar qualidade dos dados retornados
- Decisão será escalada automaticamente

Erro: "Dados de receita não disponíveis"

Causa: APIs de receita não estão respondendo

Solução:
- Verificar CSUITE_CONTEXT_URL
- Verificar endpoints /api/csuite/overview
- Agente continuará com dados disponíveis

📚 Documentação Relacionada

Guia de APIs Sales Manager: docs/guides/GUIA_USO_APIS_SALES_MANAGER.md
Guia de APIs Customer Decisions: docs/guides/GUIA_USO_APIS_CUSTOMER_DECISIONS.md
Guia de APIs Context: docs/guides/GUIA_USO_APIS_CONTEXT.md
Pricing Agent: docs/agent/PRICING_AGENT.md
Agent Loop v1: docs/agent/AGENT_LOOP_V1_SPEC.md

🎯 Próximos Passos

Melhorias Sugeridas

Integração com APIs Externas
[ ] Integrar _fetch_revenue_data com APIs reais
[ ] Integrar _fetch_segmentation com Customer Decisions API
[ ] Integrar _fetch_churn_indicators com Context API
[ ] Melhorar integração com Sales Manager API
Melhorias de Decisão
[ ] Adicionar previsão de vendas (forecasting)
[ ] Melhorar detecção de churn com ML
[ ] Integrar com Pricing Agent para otimização
Testes e Deploy
[ ] Testes unitários
[ ] Testes de integração
[ ] Deploy em Docker Swarm
[ ] Documentação OpenAPI

Última atualização: 2026-01-10
Versão: 1.1.0

Cro Agent