Operations Agent - Documentação Completa

📋 Visão Geral

O Operations Agent é um agente autônomo do CSuite que mantém execução estável e previsível de processos operacionais. Ele gerencia retries, reassignments e escalações automáticas, detectando e mitigando gargalos operacionais.

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

🎯 Propósito

O Operations Agent existe para:

Manter Estabilidade: Garantir execução estável e previsível de processos
Gerenciar Retries: Reexecutar processos com backoff exponencial
Reatribuir Recursos: Reatribuir processos quando recursos estão indisponíveis
Escalar Problemas: Escalar para intervenção humana quando necessário

🏗️ Arquitetura

Fluxo de Execução

1. Recebe Payload
   ↓
2. Build Context
   ├─ Process (type, sla, attempts)
   ├─ Resource (id, capacity, status)
   └─ History (failures, latency)
   ↓
3. Determine Decision Type
   ├─ OPS.DISPATCH (recurso disponível, sem falhas)
   ├─ OPS.RETRY (falhas anteriores, attempts < 3)
   ├─ OPS.REASSIGN (recurso indisponível)
   └─ OPS.ESCALATE (attempts >= 3)
   ↓
4. Calculate Confidence
   ↓
5. Propose Actions
   ├─ TRIGGER_PROCESS
   ├─ RETRY
   ├─ REASSIGN
   └─ OPEN_INCIDENT
   ↓
6. Policy Validation
   ↓
7. Policy Engine Integration
   ↓
8. Execute Actions
   ↓
9. Record Outcome

Componentes

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

🔌 Integrações

1. 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
`POST /v1/policy/decisions`	Histórico de decisões	Auditoria

2. Operations API

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

Endpoint	Descrição	Uso
`GET /dashboard`	Dashboard operacional	Visão consolidada
`GET /operations/decisions/pending`	Decisões pendentes	Lista de decisões
`POST /operations/decisions/{decision_id}/execute`	Executar decisão	Execução de decisões

3. Context API

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

Endpoint	Descrição	Uso
`GET /api/csuite/events`	Eventos operacionais	Eventos recentes
`GET /api/csuite/trends`	Tendências	Tendências operacionais
`GET /api/csuite/signals`	Sinais	Sinais detectados

📊 Decision Types

OPS.DISPATCH

Condição: Recurso disponível, sem falhas anteriores, attempts < 3

Ações:
- TRIGGER_PROCESS - Disparar processo

Autonomia: L2/L3 (Rebalanceamento/Self-healing)

OPS.RETRY

Condição: Falhas anteriores, attempts < 3

Ações:
- RETRY - Reexecutar com backoff exponencial

Autonomia: L1 (Retry automático)

OPS.REASSIGN

Condição: Recurso indisponível ou sobrecarregado

Ações:
- REASSIGN - Reatribuir para outro recurso

Autonomia: L2 (Rebalanceamento automático)

OPS.ESCALATE

Condição: attempts >= 3 ou múltiplas falhas

Ações:
- OPEN_INCIDENT - Abrir incidente para intervenção humana

Autonomia: L0 (Manual)

⚙️ Configuração

Variáveis de Ambiente

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

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

🚀 Execução

Via FastAPI

cd agents/ops
./run_server.sh

Exemplo de Request

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 0,
    "process": {
      "type": "ORDER_PROCESSING",
      "sla": 3600,
      "attempts": 1
    },
    "resource": {
      "id": "worker-001",
      "capacity": 100,
      "status": "available"
    },
    "history": {
      "failures": 0,
      "latency": 500
    }
  }'

Exemplo de Response

{
  "status": "success",
  "agent": "CSuite.Operations.Agent",
  "result": {
    "decision": {
      "decision_type": "OPS.DISPATCH",
      "confidence": 0.85,
      "proposed_actions": [
        {
          "type": "TRIGGER_PROCESS",
          "resource_id": "worker-001"
        }
      ]
    },
    "context": {...},
    "execution": {
      "status": "EXECUTED",
      "actions": [...]
    },
    "decision_log_id": 12345,
    "run_id": 67890
  }
}

📋 Policies

Validações Locais

Confiança Mínima: 0.6
Decisões com confiança < 0.6 são escaladas
Limite de Retries: 3 tentativas
Após 3 tentativas, processo é escalado
SLA: Respeitar SLA do processo
Processos que excedem SLA são priorizados

Integração com Policy Engine

O Operations Agent integra com o Policy Engine para:
- Validação de políticas de SLA
- Validação de limites de retries
- 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: Muitas tentativas ou falhas anteriores

Solução:
- Verificar histórico de falhas
- Verificar status do recurso
- Decisão será escalada automaticamente

Erro: "Limite de retries excedido"

Causa: Processo já teve 3 ou mais tentativas

Solução:
- Processo será escalado automaticamente
- Incidente será aberto para intervenção humana

📚 Documentação Relacionada

Guia de APIs Operations: docs/guides/GUIA_USO_APIS_OPERATIONS.md
COO Agent: docs/agent/COO_AGENT.md (usado como base)
Agent Loop v1: docs/agent/AGENT_LOOP_V1_SPEC.md

🎯 Próximos Passos

Melhorias Sugeridas

Integração com APIs Externas
[ ] Integrar TRIGGER_PROCESS com sistema de processos real
[ ] Integrar RETRY com sistema de retry real
[ ] Integrar REASSIGN com sistema de load balancing
[ ] Integrar OPEN_INCIDENT com sistema de incidentes
Melhorias de Decisão
[ ] Integrar com Operations API para dashboard
[ ] Usar Context API para eventos e tendências
[ ] Melhorar cálculo de confiança com ML
Testes e Deploy
[ ] Testes unitários
[ ] Testes de integração
[ ] Deploy em Docker Swarm
[ ] Documentação OpenAPI

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

Ops Agent