🔄 Agent Loop - Integração Completa

Data: 31/12/2025
Status: ✅ Implementado e Funcional

✅ Execução dos Próximos Passos

1️⃣ SQL Executado

Arquivo: sql/13_agent_loop_decision_context.sql

Componentes criados:
- ✅ Tabela: ctx_decision_context_snapshot
- ✅ Procedure: sp_ctx_snapshot_decision_context
- ✅ View: vw_decision_timeline

Verificação:

-- Verificar tabela
SHOW TABLES LIKE 'ctx_decision_context_snapshot' IN csuite_context;

-- Verificar procedure
SELECT ROUTINE_NAME 
FROM information_schema.ROUTINES 
WHERE ROUTINE_SCHEMA = 'csuite_context' 
AND ROUTINE_NAME = 'sp_ctx_snapshot_decision_context';

-- Verificar view
SELECT TABLE_NAME 
FROM information_schema.VIEWS 
WHERE TABLE_SCHEMA = 'csuite_context' 
AND TABLE_NAME = 'vw_decision_timeline';

2️⃣ Integração no Código

Arquivo: csuite-executive/csuite-api/app/policy_engine/instrumentation.py

Mudanças:
1. ✅ Função _snapshot_decision_context() adicionada
2. ✅ Chamada integrada em instrument_decision() após gravar decisão
3. ✅ Snapshot criado automaticamente para cada decisão

Fluxo:

instrument_decision()
  ├─ Grava em pg_decision_log
  ├─ Obtém decision_log_id
  ├─ [NOVO] Chama _snapshot_decision_context()
  │   └─ Cria snapshot em ctx_decision_context_snapshot
  └─ Se ESCALATE/DENY/WARN → cria violação

Código adicionado:

# Após gravar decisão (linha ~94)
decision_log_id = result.lastrowid

# Agent Loop: Congelar contexto no momento da decisão
try:
    _snapshot_decision_context(
        db=db,
        decision_log_id=decision_log_id,
        req=req,
        resp=resp,
        source_app=source_app,
        subject_type=subject_type,
        subject_ref=subject_ref
    )
except Exception as snapshot_error:
    # Log erro mas não quebra o fluxo
    logger.warning(f"Erro ao criar snapshot de contexto: {snapshot_error}")

3️⃣ Função _snapshot_decision_context()

Localização: csuite-executive/csuite-api/app/policy_engine/instrumentation.py

Funcionalidade:
- Monta snapshot JSON do contexto usado para decidir
- Extrai org_id do request (padrão 0)
- Determina policy_ref e agent_code automaticamente
- Chama sp_ctx_snapshot_decision_context() para gravar

Snapshot JSON inclui:

{
  "decision": {
    "decision_id": "...",
    "outcome": "ALLOW|RECOMMEND|ESCALATE|DENY",
    "category": "...",
    "app": "...",
    "automation": "..."
  },
  "request": {
    "actor": "...",
    "inputs": {...},
    "decision_id": "..."
  },
  "subject": {
    "type": "CUSTOMER|ORDER|SELLER|SKU",
    "ref": "..."
  },
  "source": {
    "app": "csuite-sales-manager"
  },
  "reasons": [...],
  "notify": [...]
}

Tratamento de erros:
- Não quebra o fluxo principal se falhar
- Loga warning para debugging
- Rollback automático em caso de erro

🧪 Teste da Integração

Teste Manual

1. Fazer uma decisão via Policy Engine:
   bash curl -X POST http://localhost:8000/v1/policy/evaluate \ -H "Content-Type: application/json" \ -d '{ "decision_id": "sales.quote.evaluate", "actor": "csuite-sales-manager:user123", "inputs": { "org_id": 0, "payload": { "subject_type": "CUSTOMER", "subject_ref": "cust_87421" } } }'

2. Verificar snapshot criado:
   sql SELECT snapshot_id, decision_log_id, policy_ref, agent_code, source_app, entity_type, entity_ref, created_at FROM csuite_context.ctx_decision_context_snapshot ORDER BY created_at DESC LIMIT 5;

3. Verificar timeline completa:
   sql SELECT decision_log_id, decision_at, decision_outcome, snapshot_id, snapshot_policy_ref, outcome_status FROM csuite_context.vw_decision_timeline ORDER BY decision_at DESC LIMIT 10;

📊 Status Final

✅ Implementado

• [x] DDL da tabela ctx_decision_context_snapshot
• [x] Procedure sp_ctx_snapshot_decision_context
• [x] View vw_decision_timeline
• [x] Função _snapshot_decision_context() em Python
• [x] Integração em instrument_decision()
• [x] Tratamento de erros (não quebra fluxo)
• [x] Documentação completa

⏳ Próximos Passos (Opcional)

• [ ] UI Decision Timeline (baseada em vw_decision_timeline)
• [ ] Dashboard de auditoria de decisões
• [ ] Alertas para decisões sem snapshot (gap detection)
• [ ] Métricas de efetividade por contexto

🎯 Resultado

O CSuite agora tem o Agent Loop formalizado:

1. Signal → Gravado em ctx_events, core_interactions
2. Context → Views dinâmicas (vw_seller_context, etc.)
3. Decision → Gravado em pg_decision_log
4. Context Snapshot → [NOVO] Gravado em ctx_decision_context_snapshot
5. Action → Gravado em execution_action_ledger
6. Outcome → Gravado em ctx_policy_outcomes
7. Memory → Gravado em csuite_memory

Tudo ancorado em decision_log_id - o ID canônico do loop.

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