CAO Agent - Documentação Completa

📋 Visão Geral

O CAO Agent (Chief Administrative Officer) é um agente executivo do CSuite que supervisiona operações diárias e é responsável pelo desempenho geral da organização. Ele monitora operações diárias, avalia desempenho, coordena entre departamentos e otimiza eficiência administrativa.

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

🎯 Propósito

O CAO Agent existe para:

Supervisionar Operações: Monitorar operações diárias e status
Avaliar Desempenho: Avaliar desempenho geral da organização
Coordenar Departamentos: Coordenar entre departamentos
Otimizar Eficiência: Otimizar eficiência administrativa

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Daily Operations (operações diárias)
   ├─ Performance Overview (desempenho geral)
   ├─ Department Coordination (coordenação entre departamentos)
   ├─ Administrative Efficiency (eficiência administrativa)
   └─ Memory Query (precedentes administrativos)
   ↓
3. Determine Decision Type
   ├─ CAO.OPTIMIZE_OPERATIONS (otimizar operações)
   ├─ CAO.COORDINATE_DEPARTMENTS (coordenar departamentos)
   ├─ CAO.IMPROVE_EFFICIENCY (melhorar eficiência)
   └─ CAO.ESCALATE_ISSUES (escalar questões)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ OPTIMIZE_OPERATIONS
   ├─ COORDINATE_DEPARTMENTS
   ├─ IMPROVE_EFFICIENCY
   └─ ESCALATE_ISSUES
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

YAML Config: agents/cao/cao_agent.yaml - Configuração canônica
Script Python: workflows/scripts/cao_agent_daily_brief.py - Execução diária
Cron Setup: workflows/scripts/setup_cron_cao.sh - Configuração de cron

🔌 Integrações

1. Operations API

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

Endpoint	Descrição	Uso
`GET /api/operations/daily`	Operações diárias	Status e métricas de operações

2. Executive API

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

Endpoint	Descrição	Uso
`GET /v1/dashboard/summary/{org_id}`	Dashboard resumo	Visão geral de desempenho
`GET /v1/cases`	Casos pendentes	Casos que requerem coordenação
`POST /v1/memory/query`	Consultar memória	Precedentes administrativos

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 administrativas

📥 Payload de Entrada

Formato Padrão

{
  "org_id": 0,
  "as_of_date": "2025-01-04",
  "time_window_days": 7,
  "focus": {
    "themes": ["daily_operations", "performance_overview", "department_coordination", "administrative_efficiency"],
    "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: 7)
`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": "CAO.OPTIMIZE_OPERATIONS | CAO.COORDINATE_DEPARTMENTS | CAO.IMPROVE_EFFICIENCY | CAO.ESCALATE_ISSUES",
    "confidence": 0.85,
    "proposed_actions": [
      {
        "action": "OPTIMIZE_OPERATIONS",
        "reason": "Operações abaixo do ideal",
        "priority": "alta"
      }
    ]
  },
  "context": {
    "daily_operations": {
      "summary": "Resumo de operações diárias",
      "total_operations": 0,
      "operations_status": {},
      "bottlenecks": []
    },
    "performance_overview": {
      "summary": "Resumo de desempenho geral",
      "overall_performance": 0.85,
      "key_metrics": {},
      "trends": [],
      "alerts": []
    },
    "department_coordination": {
      "summary": "Resumo de coordenação",
      "coordination_cases": 0,
      "departments_involved": [],
      "coordination_issues": []
    },
    "administrative_efficiency": {
      "summary": "Resumo de eficiência",
      "efficiency_score": 0.85,
      "efficiency_indicators": [],
      "improvement_areas": []
    }
  },
  "execution": {
    "status": "completed",
    "actions": []
  },
  "opportunities": [
    {
      "type": "OPTIMIZE_OPERATIONS",
      "description": "Otimizar operações identificado",
      "impact": "alto | médio | baixo",
      "confidence": 0.85,
      "priority": "alta"
    }
  ],
  "recommendations": [
    {
      "action": "Otimizar operações diárias",
      "reason": "Operações abaixo do ideal",
      "priority": "alta",
      "administrative_impact": "alto"
    }
  ],
  "next_steps": [
    "Otimizar operações",
    "Coordenar departamentos",
    "Melhorar eficiência"
  ],
  "generated_at": "2025-01-04T09:20:00",
  "org_id": 0,
  "as_of_date": "2025-01-04"
}

🔄 Decision Types

CAO.OPTIMIZE_OPERATIONS

Descrição: Otimizar operações diárias

Condições:
- Operações abaixo do ideal
- Bottlenecks identificados
- Oportunidade de otimização
- Confidence >= 0.8

Ações:
- OPTIMIZE_OPERATIONS: Otimizar operações
- IMPROVE_EFFICIENCY: Melhorar eficiência (se necessário)

CAO.COORDINATE_DEPARTMENTS

Descrição: Coordenar entre departamentos

Condições:
- Casos que requerem coordenação
- Múltiplos departamentos envolvidos
- Oportunidade de coordenação
- Confidence >= 0.7

Ações:
- COORDINATE_DEPARTMENTS: Coordenar departamentos
- ESCALATE_ISSUES: Escalar questões (se necessário)

CAO.IMPROVE_EFFICIENCY

Descrição: Melhorar eficiência administrativa

Condições:
- Eficiência abaixo do ideal
- Oportunidades identificadas
- Alinhamento necessário
- Confidence >= 0.9

Ações:
- IMPROVE_EFFICIENCY: Melhorar eficiência
- OPTIMIZE_OPERATIONS: Otimizar operações (se necessário)

CAO.ESCALATE_ISSUES

Descrição: Escalar questões críticas

Condições:
- Questões críticas identificadas
- Requer atenção executiva
- Não pode ser resolvido automaticamente
- Confidence >= 0.7

Ações:
- ESCALATE_ISSUES: Escalar questões
- COORDINATE_DEPARTMENTS: Coordenar departamentos (se necessário)

🎛️ Autonomia

Níveis de Autonomia

Nível	Descrição	Condição
L0	Sempre recomendação	`COORDINATE_DEPARTMENTS`, `ESCALATE_ISSUES`, ou `confidence < 0.7`
L1	Otimizar operações automaticamente	`OPTIMIZE_OPERATIONS` e `confidence >= 0.8`
L2	Melhorar eficiência automaticamente	`IMPROVE_EFFICIENCY` 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_OPERATIONS_URL=https://csuite.internut.com.br/operations
CSUITE_MEMORY_URL=https://csuite.internut.com.br/executive

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

# Configuração
ORG_ID=0
TIME_WINDOW_DAYS=7

Cron Job

O CAO Agent executa diariamente às 09:20:

cd workflows/scripts
./setup_cron_cao.sh

Cron Entry:

20 9 * * * cd /path/to/workflows/scripts && /usr/bin/python3 cao_agent_daily_brief.py >> logs/cao_agent_cron.log 2>&1

🚀 Uso

Execução Manual

cd workflows/scripts
python3 cao_agent_daily_brief.py

Output

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

cao_brief_YYYYMMDD_HHMMSS.json

Formato do Brief no Slack

O brief é formatado com:
- Header com status de desempenho (🟢/🟡/🔴 baseado em overall_performance)
- Contexto administrativo
- Desempenho geral (score)
- Eficiência administrativa (score)
- Operações diárias (resumo)
- Oportunidades identificadas
- Recomendações prioritárias
- Próximos passos

🔍 Métricas Monitoradas

Daily Operations

Total Operations: Número total de operações
Operations Status: Status das operações
Performance Metrics: Métricas de performance
Bottlenecks: Gargalos identificados

Performance Overview

Overall Performance: Desempenho geral (0.0 a 1.0)
Key Metrics: Métricas principais
Trends: Tendências identificadas
Alerts: Alertas gerados
Action Items: Itens de ação

Department Coordination

Coordination Cases: Número de casos que requerem coordenação
Departments Involved: Departamentos envolvidos
Coordination Issues: Questões de coordenação

Administrative Efficiency

Efficiency Score: Score de eficiência (0.0 a 1.0)
Efficiency Indicators: Indicadores de eficiência
Improvement Areas: Áreas de melhoria

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

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

Erro: "Operations API retornou 404"

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

Erro: "Executive API retornou 404"

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

Brief não publicado no Slack

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

📚 Referências

YAML Config: agents/cao/cao_agent.yaml
Script Python: workflows/scripts/cao_agent_daily_brief.py
README: agents/cao/README.md
Operations API: csuite-operations/README.md
Executive API: csuite-executive/README.md

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

CAO Agent - Documentação Completa

📋 Visão Geral

🎯 Propósito

🏗️ Arquitetura

Fluxo de Execução

Componentes

🔌 Integrações

1. Operations API

2. Executive API

3. Policy Engine

📥 Payload de Entrada

Formato Padrão

Campos

📤 Payload de Saída

Formato Padrão

🔄 Decision Types

CAO.OPTIMIZE_OPERATIONS

CAO.COORDINATE_DEPARTMENTS

CAO.IMPROVE_EFFICIENCY

CAO.ESCALATE_ISSUES

🎛️ 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

Daily Operations

Performance Overview

Department Coordination

Administrative Efficiency

🛠️ Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Erro: "Operations API retornou 404"

Erro: "Executive API retornou 404"

Brief não publicado no Slack

📚 Referências

🔊 Text-to-Speech