Risk Agent - Documentação Completa

📋 Visão Geral

O Risk Agent é um agente autônomo do CSuite que detecta, prioriza e mitiga riscos financeiros, operacionais e estratégicos. Ele monitora compliance, violações de políticas e gera alertas e recomendações de mitigação.

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

🎯 Propósito

O Risk Agent existe para:

1. Detectar Riscos: Identificar riscos financeiros, operacionais e estratégicos
2. Priorizar Riscos: Classificar riscos por severidade e impacto
3. Mitigar Riscos: Gerar ações de mitigação (bloqueios, alertas, revisões)
4. Monitorar Compliance: Verificar conformidade com políticas e regulamentações

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Signal (type, severity)
   ├─ Entity (type, ref)
   ├─ Trend (direction, velocity)
   └─ Policy (thresholds)
   ↓
3. Calculate Risk Score
   ├─ Severity score (high: 80, medium: 50, low: 30)
   └─ Velocity score (velocity * 20)
   ↓
4. Determine Decision Type
   ├─ RISK.BLOCK (risk_score >= 85)
   ├─ RISK.MONITOR (risk_score >= 60)
   └─ RISK.ALERT (risk_score < 60)
   ↓
5. Calculate Confidence
   ↓
6. Propose Actions
   ├─ BLOCK_OPERATION
   ├─ REQUEST_REVIEW
   └─ CREATE_ALERT
   ↓
7. Policy Validation
   ↓
8. Policy Engine Integration
   ↓
9. Execute Actions
   ↓
10. Record Outcome

Componentes

• YAML Config: agents/risk/risk_agent.yaml - Configuração canônica
• FastAPI Main: agents/risk/main.py - Entrypoint FastAPI
• Context Builder: agents/risk/context.py - Constrói contexto
• Decision Engine: agents/risk/decision.py - Motor de decisão
• Execution Handler: agents/risk/execution.py - Executa ações
• Policy Guardrails: agents/risk/policies.py - Validações locais

🔌 Integrações

1. Policy Engine

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

2. Context API

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

3. Executive API

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

📊 Decision Types

RISK.BLOCK

Condição: risk_score >= 85 (threshold high)

Ações:
- BLOCK_OPERATION - Bloquear operação

Autonomia: L3 (Bloqueio total automático)

RISK.MONITOR

Condição: 60 <= risk_score < 85 (threshold medium)

Ações:
- REQUEST_REVIEW - Solicitar revisão humana

Autonomia: L2 (Bloqueio parcial - requer revisão)

RISK.ALERT

Condição: risk_score < 60

Ações:
- CREATE_ALERT - Criar alerta de risco

Autonomia: L0/L1 (Apenas alerta / Monitoramento automático)

⚙️ Configuração

Variáveis de Ambiente

# URLs dos Serviços
CSUITE_POLICY_ENGINE_URL=https://csuite.internut.com.br/executive
CSUITE_CONTEXT_URL=https://csuite.internut.com.br
CSUITE_EXECUTIVE_URL=https://csuite.internut.com.br/executive

# Database
DB_HOST=localhost
DB_USER=user
DB_PASSWORD=password
DB_NAME=csuite_agents

🚀 Execução

Via FastAPI

cd agents/risk
./run_server.sh

Exemplo de Request

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 0,
    "signal": {
      "type": "CREDIT_RISK",
      "severity": "high"
    },
    "entity": {
      "type": "CUSTOMER",
      "ref": "12345"
    },
    "trend": {
      "direction": "up",
      "velocity": 0.7
    },
    "policy": {
      "thresholds": {
        "high": 85,
        "medium": 60,
        "low": 40
      }
    }
  }'

Exemplo de Response

{
  "status": "success",
  "agent": "CSuite.Risk.Agent",
  "result": {
    "decision": {
      "decision_type": "RISK.BLOCK",
      "confidence": 0.85,
      "proposed_actions": [
        {
          "type": "BLOCK_OPERATION",
          "reason": "Risk score alto: 94.0",
          "severity": "high"
        }
      ]
    },
    "context": {...},
    "execution": {
      "status": "EXECUTED",
      "actions": [...]
    },
    "decision_log_id": 12345,
    "run_id": 67890
  }
}

📋 Policies

Validações Locais

1. Confiança Mínima: 0.6

2. Decisões com confiança < 0.6 são escaladas

3. Severidade Válida: low, medium, high

4. Severidades inválidas são rejeitadas

5. Thresholds: Respeitar thresholds de política

6. Thresholds padrão: high=85, medium=60, low=40

Integração com Policy Engine

O Risk Agent integra com o Policy Engine para:
- Validação de políticas de risco
- Validação de compliance
- Instrumentação de decisões (pg_decision_log)
- Criação de snapshots (ctx_decision_context_snapshot)
- Registro de outcomes (ctx_policy_outcomes)
- Registro de runs (agent_runs)

🔍 Troubleshooting

Erro: "Policy Engine não disponível"

Causa: Policy Engine não está acessível ou importação falhou

Solução:
- Verificar se csuite-executive está rodando
- Verificar caminho de importação em decision.py
- O agente funciona em modo standalone (sem Policy Engine)

Erro: "Confiança baixa"

Causa: Severidade baixa ou velocidade baixa

Solução:
- Verificar severidade do sinal
- Verificar velocidade da tendência
- Decisão será escalada automaticamente

Erro: "Severidade inválida"

Causa: Severidade não está em [low, medium, high]

Solução:
- Usar apenas valores válidos: "low", "medium", "high"
- Validação será rejeitada automaticamente

📚 Documentação Relacionada

• Guia de APIs Context: docs/guides/GUIA_USO_APIS_CONTEXT.md
• Guia de APIs Executive: docs/guides/GUIA_USO_APIS_EXECUTIVE.md
• Agent Loop v1: docs/agent/AGENT_LOOP_V1_SPEC.md

🎯 Próximos Passos

Melhorias Sugeridas

1. Integração com APIs Externas
2. [ ] Integrar CREATE_ALERT com sistema de alertas real
3. [ ] Integrar BLOCK_OPERATION com sistema de bloqueios real
4. [ ] Integrar REQUEST_REVIEW com sistema de revisões

5. [ ] Integrar CLOSE_RISK com sistema de gestão de riscos

6. Melhorias de Decisão

7. [ ] Integrar com Context API para painel de riscos
8. [ ] Usar radar de sinais para detecção proativa

9. [ ] Melhorar cálculo de risk score com ML

10. Testes e Deploy

11. [ ] Testes unitários
12. [ ] Testes de integração
13. [ ] Deploy em Docker Swarm
14. [ ] Documentação OpenAPI

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