CPO Agent - Documentação Completa

📋 Visão Geral

O CPO Agent (Chief Product Officer) é um agente executivo do CSuite que otimiza produtos e roadmap. Ele monitora performance de produtos, analisa feedback de clientes, avalia roadmap e identifica oportunidades de inovação.

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

🎯 Propósito

O CPO Agent existe para:

Monitorar Produtos: Acompanhar performance de produtos (vendas, margem, giro)
Analisar Feedback: Processar feedback de clientes sobre produtos
Avaliar Roadmap: Monitorar e priorizar roadmap de produtos
Inovar: Identificar oportunidades de inovação e desenvolvimento

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Product Performance (vendas, margem, giro)
   ├─ Customer Feedback (feedback de clientes)
   ├─ Product Roadmap (roadmap e priorização)
   ├─ Innovation Pipeline (pipeline de inovação)
   └─ Memory Query (precedentes de produtos)
   ↓
3. Determine Decision Type
   ├─ CPO.PRIORITIZE_ROADMAP (priorizar roadmap)
   ├─ CPO.LAUNCH_PRODUCT (lançar produto)
   ├─ CPO.IMPROVE_PRODUCT (melhorar produto)
   └─ CPO.INNOVATE (inovar)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ PRIORITIZE_ROADMAP
   ├─ LAUNCH_PRODUCT
   ├─ IMPROVE_PRODUCT
   └─ INNOVATE
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cpo/cpo_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cpo_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cpo.sh - Configuração de cron

🔌 Integrações

1. CFO-Ops

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

Endpoint	Descrição	Uso
`GET /api/products/performance`	Performance de produtos	Vendas, margem, giro

2. Customer Decisions

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

Endpoint	Descrição	Uso
`GET /api/feedback/products`	Feedback de produtos	Feedback de clientes sobre produtos

3. 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 produtos
`GET /v1/governance/policies/radar`	Policy Radar	Políticas de produtos

4. Executive API

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

Endpoint	Descrição	Uso
`POST /v1/memory/query`	Consultar memória	Precedentes de produtos

5. Product Systems (Opcional)

Base URL: Configurável via CSUITE_PRODUCT_URL

Endpoint	Descrição	Uso
`GET /api/roadmap`	Roadmap	Roadmap de produtos
`GET /api/innovation`	Inovação	Pipeline de inovação

📥 Payload de Entrada

Formato Padrão

{
  "org_id": 0,
  "as_of_date": "2025-01-04",
  "time_window_days": 30,
  "focus": {
    "themes": ["product_performance", "customer_feedback", "product_roadmap", "innovation_pipeline"],
    "constraints": []
  },
  "attention": {
    "max_recommendations": 3,
    "max_output_tokens": 1200
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`org_id`	integer	✅	ID da organização
`as_of_date`	string	✅	Data de referência (YYYY-MM-DD)
`time_window_days`	integer	❌	Janela de análise (padrão: 30)
`focus.themes`	array	❌	Temas de foco
`attention.max_recommendations`	integer	❌	Máximo de recomendações (padrão: 3)

📤 Payload de Saída

Formato Padrão

{
  "decision": {
    "decision_type": "CPO.PRIORITIZE_ROADMAP | CPO.LAUNCH_PRODUCT | CPO.IMPROVE_PRODUCT | CPO.INNOVATE",
    "confidence": 0.85,
    "proposed_actions": [
      {
        "action": "PRIORITIZE_ROADMAP",
        "product": "produto_1",
        "reason": "Alta demanda identificada",
        "priority": "alta"
      }
    ]
  },
  "context": {
    "product_performance": {
      "summary": "Resumo de performance de produtos",
      "top_performers": [],
      "underperformers": [],
      "performance_trends": []
    },
    "customer_feedback": {
      "summary": "Resumo de feedback de clientes",
      "positive_signals": [],
      "negative_signals": [],
      "feedback_trends": []
    },
    "product_roadmap": {
      "roadmap_status": "status do roadmap",
      "priorities": [],
      "blockers": [],
      "recommendations": []
    },
    "innovation_pipeline": {
      "pipeline_status": "status do pipeline",
      "innovation_opportunities": [],
      "development_priorities": []
    }
  },
  "execution": {
    "status": "completed",
    "actions": []
  },
  "opportunities": [
    {
      "type": "PRIORITIZE_ROADMAP",
      "description": "Priorizar roadmap identificado",
      "impact": "alto | médio | baixo",
      "confidence": 0.85,
      "product": "produto_1"
    }
  ],
  "recommendations": [
    {
      "action": "Priorizar desenvolvimento de produto_1",
      "reason": "Alta demanda identificada",
      "priority": "alta",
      "product_impact": "alto"
    }
  ],
  "next_steps": [
    "Priorizar roadmap",
    "Monitorar feedback",
    "Avaliar inovação"
  ],
  "generated_at": "2025-01-04T09:05:00",
  "org_id": 0,
  "as_of_date": "2025-01-04"
}

🔄 Decision Types

CPO.PRIORITIZE_ROADMAP

Descrição: Priorizar roadmap de produtos

Condições:
- Roadmap identificado
- Prioridades não claras
- Oportunidade de priorização
- Confidence >= 0.7

Ações:
- PRIORITIZE_ROADMAP: Priorizar roadmap
- IMPROVE_PRODUCT: Melhorar produto (se necessário)

CPO.LAUNCH_PRODUCT

Descrição: Lançar novo produto

Condições:
- Produto pronto para lançamento
- Demanda identificada
- Roadmap alinhado
- Confidence >= 0.7

Ações:
- LAUNCH_PRODUCT: Lançar produto
- PRIORITIZE_ROADMAP: Priorizar roadmap (se necessário)

CPO.IMPROVE_PRODUCT

Descrição: Melhorar produto existente

Condições:
- Feedback negativo identificado
- Performance abaixo do esperado
- Oportunidade de melhoria
- Confidence >= 0.8

Ações:
- IMPROVE_PRODUCT: Melhorar produto
- INNOVATE: Inovar (se necessário)

CPO.INNOVATE

Descrição: Inovar e desenvolver novos produtos

Condições:
- Oportunidade de inovação identificada
- Pipeline de inovação disponível
- Alinhamento estratégico
- Confidence >= 0.9

Ações:
- INNOVATE: Inovar
- PRIORITIZE_ROADMAP: Priorizar roadmap (se necessário)

🎛️ Autonomia

Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação	`PRIORITIZE_ROADMAP`, `LAUNCH_PRODUCT`, ou `confidence < 0.7`
L1	Melhorar produto automaticamente	`IMPROVE_PRODUCT` e `confidence >= 0.8`
L2	Inovar automaticamente	`INNOVATE` e `confidence >= 0.9`

⚙️ Configuração

Variáveis de Ambiente

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

# CSuite Services
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive
CSUITE_CUSTOMER_DECISIONS_URL=https://csuite.internut.com.br/customer-decisions
CSUITE_CFO_OPS_URL=https://csuite.internut.com.br/cfo-ops
CSUITE_MEMORY_URL=https://csuite.internut.com.br/executive
CSUITE_PRODUCT_URL=https://csuite.internut.com.br/product  # Opcional

# Webhook
CPO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/...

# Configuração
ORG_ID=0
TIME_WINDOW_DAYS=30

Cron Job

O CPO Agent executa diariamente às 09:05:

cd workflows/scripts
./setup_cron_cpo.sh

Cron Entry:

5 9 * * * cd /path/to/workflows/scripts && /usr/bin/python3 cpo_agent_daily_brief.py >> logs/cpo_agent_cron.log 2>&1

🚀 Uso

Execução Manual

cd workflows/scripts
python3 cpo_agent_daily_brief.py

Output

O brief é publicado no Slack e salvo em arquivo JSON:

cpo_brief_YYYYMMDD_HHMMSS.json

Formato do Brief no Slack

O brief é formatado com:
- Header com ícone de produtos (📦)
- Contexto de produtos
- Performance de produtos (resumo)
- Feedback de clientes (resumo)
- Roadmap (status)
- Oportunidades identificadas
- Recomendações prioritárias
- Próximos passos

🔍 Métricas Monitoradas

Product Performance

Total Products: Número total de produtos
Top Performers: Produtos com melhor performance
Underperformers: Produtos com performance abaixo do esperado
Avg Margin: Margem média
Performance Trends: Tendências de performance

Customer Feedback

Total Feedback: Número total de feedbacks
Positive Feedback: Feedback positivo
Negative Feedback: Feedback negativo
Feedback by Product: Feedback por produto
Top Complaints: Principais reclamações
Top Praises: Principais elogios

Product Roadmap

Roadmap Status: Status do roadmap
Priorities: Prioridades do roadmap
Blockers: Bloqueadores do roadmap
Product Policies: Políticas de produtos

Innovation Pipeline

Innovation Items: Itens de inovação
Innovation Opportunities: Oportunidades de inovação
Development Priorities: Prioridades de desenvolvimento

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução: Configure a variável de ambiente OPENAI_API_KEY ou LLM_API_KEY.

Erro: "CFO-Ops retornou 404"

Solução: Verifique se o csuite-cfo-ops está rodando e acessível.

Erro: "Customer Decisions retornou 404"

Solução: Verifique se o csuite-customer-decisions está rodando e acessível.

Erro: "Dados limitados de produtos"

Solução: Integre com sistemas de produtos externos via CSUITE_PRODUCT_URL para dados completos.

Brief não publicado no Slack

Solução:
1. Verifique se CPO_BRIEF_WEBHOOK_URL está configurada
2. Verifique se o webhook do Slack está válido
3. Verifique logs em cpo_agent.log

📚 Referências

YAML Config: agents/cpo/cpo_agent.yaml
Script Python: workflows/scripts/cpo_agent_daily_brief.py
README: agents/cpo/README.md
CFO-Ops: csuite-cfo-ops/README.md
Customer Decisions: csuite-customer-decisions/README.md

Última atualização: 2025-01-04

CPO Agent - Documentação Completa

📋 Visão Geral

🎯 Propósito

🏗️ Arquitetura

Fluxo de Execução

Componentes

🔌 Integrações

1. CFO-Ops

2. Customer Decisions

3. Policy Engine

4. Executive API

5. Product Systems (Opcional)

📥 Payload de Entrada

Formato Padrão

Campos

📤 Payload de Saída

Formato Padrão

🔄 Decision Types

CPO.PRIORITIZE_ROADMAP

CPO.LAUNCH_PRODUCT

CPO.IMPROVE_PRODUCT

CPO.INNOVATE

🎛️ Autonomia

Níveis de Autonomia

⚙️ Configuração

Variáveis de Ambiente

Cron Job

🚀 Uso

Execução Manual

Output

Formato do Brief no Slack

🔍 Métricas Monitoradas

Product Performance

Customer Feedback

Product Roadmap

Innovation Pipeline

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Erro: "CFO-Ops retornou 404"

Erro: "Customer Decisions retornou 404"

Erro: "Dados limitados de produtos"

Brief não publicado no Slack

📚 Referências

🔊 Text-to-Speech