ligbox-ops-platform/specs/030-agentic-ops-ui/contracts/agentic-ui-api.md

Contract — Agentic UI API v1.1 (Spec 030)

Extensão da API Spec 029. Base: /api/v1/agents.

Auth: igual 029 — JWT ops view (get_current_user + _ops_view).

---

GET /overview

Resumo para status bar.

Response 200:

{
  "tier": "t1",
  "ollama": true,
  "model": "qwen2.5:7b-instruct",
  "last_tick_at": "2026-06-20T06:32:02.723068+00:00",
  "last_tick_status": "degraded",
  "scenarios_total": 9,
  "scenarios_ok": 5,
  "incidents_open": {
    "critical": 0,
    "high": 2,
    "warn": 2,
    "info": 0
  },
  "worker_interval_sec": 600
}

---

GET /incidents

Lista deduplicada para mission board.

Query:

Param	Tipo	Default
status	open | ack | all	open
severity	string	—
agent_id	string	—
limit	int	50

Response 200:

{
  "incidents": [
    {
      "id": 1,
      "scenario_id": "vm123.finance.stack",
      "title": "FOSSBilling VM123 down",
      "severity": "high",
      "status": "open",
      "primary_agent": "sentinel",
      "agent_name": "Vigia",
      "occurrence_count": 12,
      "first_seen_at": "2026-06-19T23:45:16Z",
      "last_seen_at": "2026-06-20T06:32:02Z",
      "suggested_human_action": "Verificar docker compose VM123 finance stack",
      "thread_id": 47,
      "latest_finding_id": 253
    }
  ]
}

---

GET /incidents/{id}

Detalhe + runs recentes do cenário.

Response 200:

{
  "incident": { "...": "..." },
  "recent_runs": [
    {
      "run_id": 758,
      "status": "degraded",
      "started_at": "2026-06-20T06:25:34Z",
      "findings_count": 1
    }
  ],
  "thread_id": 47
}

---

POST /incidents/{id}/ack

Ack incidente, mensagens inbox associadas, e finding latest.

Response 200:

{
  "ok": true,
  "incident_id": 1,
  "thread_id": 47,
  "findings_acked": 1
}

RBAC: super_admin, ops_lead, technician, agentic_operator, devops, security_analyst (mesmo _ops_view).

---

Alteração no tick (runner)

Pseudo-lógica em notify_finding_to_operators:

1. Upsert agent_incidents ON scenario_id
   - increment occurrence_count
   - update last_seen_at, latest_finding_id, severity (max)
2. Reutilizar thread_id do incidente se open
3. Post message apenas se severity escalou OU first_seen OR human_action mudou

Evita 140 threads para 4 cenários.

---

Frontend consumption

// agentic-ops v2 boot
const [overview, incidents] = await Promise.all([
  agentsApi('/overview'),
  agentsApi('/incidents?status=open'),
]);

Fallback UI-A (sem backend): agrupar /findings?open_only=true por scenario_id no JS até UI-B deploy.