🔍 Agent Loop - Detection Job

Data: 31/12/2025
Objetivo: Detectar decisões sem snapshot e monitorar saúde do Agent Loop

📊 Componentes Criados

1. View: vw_decisions_missing_snapshot

Lista todas as decisões que não têm snapshot de contexto.

Uso:

SELECT * FROM csuite_context.vw_decisions_missing_snapshot
WHERE age_category = 'TODAY'
LIMIT 20;

Campos:
- decision_log_id - ID da decisão
- decision_at - Quando a decisão foi tomada
- decision_code - Código da decisão
- decision_source_app - App que gerou a decisão
- decision_outcome - Resultado (ALLOW/RECOMMEND/ESCALATE/DENY)
- hours_since_decision - Idade da decisão em horas
- age_category - Categoria de idade (RECENT/TODAY/THIS_WEEK/OLD)

2. View: vw_agent_loop_health

Métricas consolidadas de saúde do Agent Loop.

Uso:

SELECT * FROM csuite_context.vw_agent_loop_health;

Métricas:
- total_decisions - Total de decisões
- decisions_with_snapshot - Decisões com snapshot
- decisions_missing_snapshot - Decisões sem snapshot
- snapshot_coverage_pct - % de cobertura de snapshots
- outcome_coverage_pct - % de cobertura de outcomes
- decisions_last_24h - Decisões nas últimas 24h
- missing_snapshot_last_24h - Sem snapshot nas últimas 24h

3. Procedure: sp_ctx_detect_missing_snapshots

Retorna lista de decisões sem snapshot (útil para backfill).

Parâmetros:
- p_org_id - ID da organização (0 = todas)
- p_hours_old - Filtrar por idade em horas (NULL = todas)
- p_limit - Limite de resultados (padrão: 100)

Uso:

-- Últimas 24h
CALL csuite_context.sp_ctx_detect_missing_snapshots(0, 24, 50);

-- Todas
CALL csuite_context.sp_ctx_detect_missing_snapshots(0, NULL, 100);

4. Script Python: scripts/agent_loop_detection_job.py

Job de detecção que pode ser executado via cron.

Funcionalidades:
- Mostra métricas de saúde
- Lista decisões sem snapshot (últimas 24h)
- Retorna código de saída 1 se houver alertas

Uso:

# Executar manualmente
python3 scripts/agent_loop_detection_job.py

# Via cron (a cada 6 horas)
0 */6 * * * cd /path/to/c-suite && python3 scripts/agent_loop_detection_job.py >> /var/log/csuite/agent_loop_detection.log 2>&1

Saída de exemplo:

============================================================
🔍 Agent Loop - Detection Job
============================================================

📊 Métricas de Saúde do Agent Loop:
------------------------------------------------------------
   Total de decisões: 150
   Com snapshot: 145
   Sem snapshot: 5
   Cobertura de snapshot: 96.67%
   Cobertura de outcome: 80.00%
   Decisões últimas 24h: 25
   Sem snapshot (24h): 2

   ⚠️  ALERTA: 2 decisões das últimas 24h sem snapshot!

🔍 Decisões sem Snapshot (últimas 24h):
------------------------------------------------------------
   Encontradas 2 decisões sem snapshot:

   1. Decision ID: sales.quote.evaluate
      Decision Log ID: 123
      Source: csuite-sales-manager
      Outcome: ALLOW
      Age: 3h atrás

   2. Decision ID: price.discount.check
      Decision Log ID: 124
      Source: csuite-customer-decisions
      Outcome: RECOMMEND
      Age: 8h atrás

============================================================
✅ Job concluído
============================================================

🎯 Próximos Passos

1. Configurar Cron Job

Adicionar ao crontab:

# Detecção a cada 6 horas
0 */6 * * * cd /home/ec2-user/enviroment/apps/c-suite && python3 scripts/agent_loop_detection_job.py >> /var/log/csuite/agent_loop_detection.log 2>&1

2. Integrar com Alertas

O job retorna código de saída 1 quando detecta alertas. Pode ser integrado com:
- Slack notifications
- Email alerts
- Monitoring systems (Prometheus, Grafana)

3. Backfill de Snapshots Antigos

Criar script de backfill que:
- Lê decisões sem snapshot via sp_ctx_detect_missing_snapshots
- Reconstrói contexto a partir de request_json em pg_decision_log
- Chama sp_ctx_snapshot_decision_context para criar snapshots retroativos

📝 Notas Técnicas

Performance

• Views são otimizadas com índices em decision_log_id
• Procedure usa LIMIT para evitar sobrecarga
• Job Python é leve e rápido (< 1s para 1000 decisões)

Alertas

Critérios de alerta:
- Cobertura de snapshot < 95%
- Decisões das últimas 24h sem snapshot > 0

Ações recomendadas:
- Investigar por que snapshots não estão sendo criados
- Verificar logs do instrumentation.py
- Fazer backfill se necessário

Última atualização: 31/12/2025