COO Agent - Documentação Completa

📋 Visão Geral

O COO Agent é um agente executivo autônomo do CSuite que protege execução operacional e eficiência da organização. Ele gera briefs operacionais diários analisando SLA, exceções, gargalos e eficiência operacional.

Status: ✅ Implementado (v1.1.0) - Suporte a Gatilhos Reativos

🎯 Propósito

O COO Agent existe para:

Proteger Execução: Monitorar SLA e garantir execução eficiente
Identificar Gargalos: Detectar gargalos antes que virem crise
Gerenciar Exceções: Monitorar e priorizar exceções operacionais
Otimizar Workflows: Analisar workflows e recomendar melhorias

🏗️ Arquitetura

Fluxo de Execução

1. Policy Gate
   ↓
2. Coleta de Dados
   ├─ Operations API (dashboard, decisões, execuções)
   ├─ Context API (eventos, tendências, alertas)
   ├─ Executive Dashboard (KPIs)
   └─ Memory API (precedentes)
   ↓
3. Geração de Brief (LLM) - Suporte a payloads reativos (ex: SKU em ruptura)
   ↓
4. Publicação (Slack)
   ↓
5. Salvamento (JSON)

### Gatilhos Reativos (Event-Driven)
- **Webhook Receiver**: `/v1/webhooks/inventory/rupture` no `csuite-operations`.
- **Fluxo**: Ruptura detectada → Injeção na Shared Memory → Trigger imediato do COO Agent com contexto do SKU.

Componentes

YAML Config: agents/coo/coo_agent.yaml - Configuração canônica
Python Script: workflows/scripts/coo_agent_daily_brief.py - Execução principal
Workflows: n8n e LangGraph (opcional)

🔌 Integrações

1. CSuite Operations

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

Endpoint	Descrição	Uso
`GET /dashboard`	Dashboard consolidado	Visão geral operacional
`GET /operations/decisions/pending`	Decisões pendentes	Ações aguardando execução
`GET /operations/decisions/executions`	Histórico de execuções	Análise de performance

2. CSuite Context

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

Endpoint	Descrição	Uso
`GET /api/csuite/events`	Eventos recentes	Eventos operacionais
`GET /api/csuite/trends`	Tendências	Tendências operacionais
`GET /api/csuite/alerts/critical`	Alertas críticos	Alertas prioritários

3. CSuite Executive

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

Endpoint	Descrição	Uso
`POST /v1/policy/evaluate`	Policy Gate	Validação de execução
`POST /v1/memory/query`	Memory API	Precedentes operacionais

4. CSuite Context Dashboard

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

Endpoint	Descrição	Uso
`GET /api/executive/dashboard/kpis`	KPIs operacionais	Métricas agregadas

📊 Output Schema

Estrutura do Brief

{
  "context": "string - Análise contextual da situação operacional",
  "operational_summary": {
    "pending_decisions": "integer - Decisões pendentes",
    "active_workflows": "integer - Workflows ativos",
    "exception_count": "integer - Quantidade de exceções",
    "sla_violations": "integer - Violações de SLA"
  },
  "sla_status": {
    "on_time_rate": "number - Taxa de pontualidade (%)",
    "delayed_count": "integer - Quantidade de atrasos",
    "critical_delays": "array - Atrasos críticos"
  },
  "exceptions": [
    {
      "type": "string - Tipo de exceção",
      "severity": "string - HIGH|MEDIUM|LOW",
      "description": "string - Descrição",
      "count": "integer - Quantidade"
    }
  ],
  "bottlenecks": [
    {
      "area": "string - Área do gargalo",
      "description": "string - Descrição",
      "impact": "string - Impacto"
    }
  ],
  "recommendations": [
    {
      "action": "string - Ação recomendada",
      "justification": "string - Justificativa",
      "priority": "string - HIGH|MEDIUM|LOW"
    }
  ],
  "memory_updates": ["string - Atualizações de memória"],
  "should_escalate": "boolean - Se deve escalar",
  "escalation_reason": "string - Razão da escalação"
}

⚙️ Configuração

Variáveis de Ambiente

Criar/editar workflows/scripts/.env:

# URLs dos Serviços
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_CONTEXT_URL=https://csuite.internut.com.br

# LLM
OPENAI_API_KEY=sk-your-key-here
LLM_MODEL=gpt-4o-mini

# Webhook Slack
COO_BRIEF_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Configurações
ORG_ID=0
TIME_WINDOW_DAYS=7

🚀 Execução

Execução Manual

cd workflows/scripts
python coo_agent_daily_brief.py

Execução Automática (Cron)

cd workflows/scripts
./setup_cron_coo.sh

Ou adicionar manualmente:

crontab -e
# Adicionar:
20 8 * * * cd /path/to/workflows/scripts && /path/to/venv/bin/python coo_agent_daily_brief.py >> coo_cron.log 2>&1

Horário sugerido: 08:20 (após CFO Agent às 08:15)

📝 Logs e Outputs

Logs

Log do agente: workflows/scripts/coo_agent.log
Log do cron: workflows/scripts/coo_cron.log

Briefs Gerados

Formato: workflows/scripts/coo_brief_YYYYMMDD_HHMMSS.json
Conteúdo: Brief completo em JSON
Publicação: Slack (se configurado)

🔍 Troubleshooting

Erro: "OPENAI_API_KEY não configurada"

Solução:

# Adicionar ao .env
echo "OPENAI_API_KEY=sk-your-key-here" >> workflows/scripts/.env

Erro: Endpoints retornando 404

Causa: Serviços podem não estar rodando ou URLs incorretas

Solução:
- Verificar se serviços estão ativos
- Confirmar URLs no .env
- O agente continua mesmo com alguns endpoints falhando (graceful degradation)

Brief não está sendo publicado no Slack

Solução:
1. Verificar COO_BRIEF_WEBHOOK_URL no .env
2. Confirmar que webhook do Slack está ativo
3. Verificar logs: tail -f workflows/scripts/coo_agent.log

📚 Documentação Relacionada

Guia de APIs Operations: docs/guides/GUIA_USO_APIS_OPERATIONS.md
CEO Agent: docs/agent/CEO_AGENT.md
CFO Agent: docs/agent/CFO_AGENT.md
Agentes Propostos: docs/agent/AGENTES_PROPOSTOS.md

🎯 Próximos Passos

Fase 1: Completar Implementação Base

[x] YAML de configuração
[x] Script Python principal
[x] README básico
[x] Documentação completa
[ ] Testes automatizados
[ ] Workflows n8n/LangGraph (opcional)

Fase 2: Melhorias

[ ] Integração com mais endpoints
[ ] Dashboard de execuções
[ ] Métricas e observabilidade
[ ] Deploy em Docker Swarm

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

Coo Agent