Skip to content

Human-in-the-Loop (HITL)

Human-in-the-Loop (HITL) provides an approval gate for high-risk agent operations. When a policy requires human authorization, AegisAI creates a HITL request that security analysts and admins can approve or reject.

Pending Approvals

The HITL page lists all pending approval requests:

Column Description
Requested Timestamp of the request
Agent Agent requesting the action
Action Operation to be performed
Resource Target resource
Reason Why approval is required
Status pending, approved, rejected

When HITL Triggers

HITL requests are created when:

  1. A policy check returns required_approval: true (via the hitl Rego template)
  2. Risk score exceeds the configured threshold
  3. The action matches a critical-operation rule (e.g., delete_data, export_phi)
sequenceDiagram
    participant Agent
    participant API
    participant Policy as Policy Engine
    participant HITL
    participant Analyst

    Agent->>API: POST /policies/check
    API->>Policy: Evaluate
    Policy-->>API: required_approval=true
    API-->>Agent: allowed=false, required_approval=true

    Agent->>API: POST /hitl/request
    API->>HITL: Create approval
    HITL-->>API: approval_id
    API-->>Agent: pending

    Note over Analyst: Dashboard notification
    Analyst->>API: POST /hitl/approve/{id}
    API->>HITL: Mark approved
    HITL-->>Agent: Action permitted

Requesting Approval

Agents request approval via the API:

curl -X POST http://localhost:8000/api/v1/hitl/request \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<uuid>",
    "action": "delete_data",
    "resource": "personal_data",
    "context": {
      "reason": "User requested account deletion",
      "records_affected": 1
    }
  }'

Approving and Rejecting

Approve

curl -X POST http://localhost:8000/api/v1/hitl/approve/<approval_id> \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"approver": "security-analyst@company.com"}'

Reject

curl -X POST http://localhost:8000/api/v1/hitl/reject/<approval_id> \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "approver": "security-analyst@company.com",
    "reason": "Insufficient justification for data deletion"
  }'

Check Status

curl http://localhost:8000/api/v1/hitl/status/<approval_id> \
  -H "X-API-Key: <your-api-key>"

List Pending

curl http://localhost:8000/api/v1/hitl/pending \
  -H "X-API-Key: <your-api-key>"

Dashboard Workflow

  1. A hitl.requested WebSocket event triggers a toast notification
  2. Navigate to HITL to review the request details
  3. Examine the agent, action, resource, and context
  4. Click Approve or Reject with an optional comment
  5. The agent can poll GET /hitl/status/{id} for the decision

HITL Policy Template

The hitl.rego template defines which actions require human approval:

  • Data deletion operations
  • Bulk data exports
  • PHI/PII access outside normal scope
  • Configuration changes to security policies
  • Cross-tenant operations

Customize the template or create tenant-specific policies that set required_approval: true.

Permissions

Role View Pending Approve Reject
Security Analyst ✅ ✅ ✅
Admin ✅ ✅ ✅
Super Admin ✅ ✅ ✅
Developer ❌ ❌ ❌
Viewer ❌ ❌ ❌

Best Practices

Recommendations

  1. Set SLAs — define maximum response time for pending approvals
  2. Document rejection reasons — aids agent developers in fixing workflows
  3. Audit all decisions — HITL approvals and rejections are logged
  4. Combine with policies — use HITL as a last gate, not the only control
  5. Monitor pending count — the Dashboard KPI card shows backlog size