Skip to main content

Human-in-the-Loop (HITL)

Human-in-the-Loop (HITL) enables human oversight for AI decisions by pausing execution and requiring manual approval before proceeding. This is essential for regulatory compliance (EU AI Act Article 14, SEBI AI/ML, RBI FREE-AI) and high-risk decision oversight.

The require_approval Action​

AxonFlow supports a require_approval policy action that triggers HITL workflows:

# Example policy with require_approval
name: "High-Value Transaction Oversight"
pattern: "(amount|value|total).*\\$[1-9][0-9]{6,}"
action: require_approval
severity: high

Community vs Enterprise​

CapabilityCommunityEnterprise
require_approval action✅✅
Auto-approve (pass-through)✅-
HITL approval queue-✅
Customer Portal approval UI-✅
Multi-level approval workflows-✅
SLA management & escalation-✅
Approval audit trail-✅
Programmatic approval API-✅
HITL Queue SDK API-✅
Approval expiration (auto-expiry)-✅
MAP-HITL integration-✅
Community Behavior

In Community Edition, require_approval auto-approves immediately. This allows you to define HITL policies and test patterns, but actual human review requires Enterprise Edition.

HITL Workflow​

The following diagram shows the end-to-end approval flow when a request triggers the require_approval action:

In Community Edition, the "Approval Queue" step is skipped and the request is auto-approved immediately.

SLA Configuration​

Enterprise Edition supports SLA-based escalation for pending approvals. Configure timeout and escalation behavior to ensure requests are never stuck:

# axonflow-config.yaml
hitl:
  sla:
    default_timeout_minutes: 60        # Auto-escalate after 60 minutes
    escalation_action: "auto_approve"  # Options: auto_approve, auto_reject, escalate
    escalation_target: "manager"       # Role to escalate to (if escalate)
    reminder_interval_minutes: 15      # Send reminder every 15 minutes
  queue:
    max_pending_per_user: 50           # Max pending approvals per reviewer
    priority_order: "severity_desc"    # Order: severity_desc, fifo, lifo
SettingDefaultDescription
default_timeout_minutes60Time before escalation triggers
escalation_actionauto_rejectWhat happens on timeout
escalation_targetmanagerWho receives escalated requests
reminder_interval_minutes15Frequency of reminder notifications

Use Cases​

  • EU AI Act Article 14: Human oversight for high-risk AI systems
  • SEBI AI/ML Circular: High-value transaction oversight (>₹10 lakh)
  • RBI FREE-AI: Human review for sensitive banking operations
  • Admin Access: Require approval for privileged operations

Policy Actions Reference​

ActionDescriptionCommunityEnterprise
blockImmediately block request✅✅
require_approvalPause for human approvalAuto-approveFull queue
redactMask sensitive content✅✅
warnLog warning, allow request✅✅
logAudit only✅✅

Getting Started​

You can create policies with require_approval in Community to prepare for Enterprise:

curl -X POST http://localhost:8080/api/v1/policies/static \
  -H "Content-Type: application/json" \
  -H "X-Org-ID: your-tenant-id" \
  -d '{
    "name": "High-Value Transaction Oversight",
    "pattern": "(amount|value|total).*\\$[1-9][0-9]{6,}",
    "action": "require_approval",
    "severity": "high",
    "enabled": true
  }'

Working examples are available in the repository:

git clone https://github.com/getaxonflow/axonflow.git
cd axonflow/examples/hitl

Approval Expiration​

In Enterprise mode, stale approval requests are automatically expired to prevent abandoned requests from accumulating in the queue. The expiration process runs on a 1-hour interval by default and transitions any pending request that has exceeded its configured timeout to an expired state.

The expiration interval is configurable in your AxonFlow configuration:

# axonflow-config.yaml
hitl:
  expiration:
    interval_minutes: 60          # How often the expiration sweep runs (default: 60)
    default_ttl_minutes: 1440     # Default request lifetime before expiry (default: 1440 / 24 hours)

Expired requests are recorded in the audit log with an expired status and the reason for expiration. This ensures compliance audit trails remain complete even when no human action was taken.

SettingDefaultDescription
interval_minutes60How frequently the expiration sweep runs
default_ttl_minutes1440Maximum age of a pending request before it is auto-expired

HITL Queue SDK API​

The HITL Queue API is available in Enterprise mode across all four SDKs (Python, TypeScript, Go, Java). It allows programmatic management of human-in-the-loop approval requests.

List Pending Requests​

# Python
requests = await client.hitl.list_requests(status="pending", limit=25)
for req in requests:
    print(f"{req.request_id}: {req.policy_name} — {req.query[:80]}")
// TypeScript
const requests = await axonflow.hitl.listRequests({ status: 'pending', limit: 25 });
for (const req of requests) {
  console.log(`${req.requestId}: ${req.policyName} — ${req.query.substring(0, 80)}`);
}

Approve a Request​

# Python
result = await client.hitl.approve(request_id="req-abc-123", reason="Reviewed and safe")
// TypeScript
const result = await axonflow.hitl.approve({ requestId: 'req-abc-123', reason: 'Reviewed and safe' });

Reject a Request​

# Python
result = await client.hitl.reject(request_id="req-abc-123", reason="Contains prohibited content")
// TypeScript
const result = await axonflow.hitl.reject({ requestId: 'req-abc-123', reason: 'Contains prohibited content' });

Queue Statistics​

# Python
stats = await client.hitl.get_stats()
print(f"Pending: {stats.pending}, Approved: {stats.approved}, Rejected: {stats.rejected}")
// TypeScript
const stats = await axonflow.hitl.getStats();
console.log(`Pending: ${stats.pending}, Approved: ${stats.approved}, Rejected: ${stats.rejected}`);

The Go and Java SDKs provide equivalent methods. See the SDK-specific documentation for detailed API references.

Enterprise HITL Features​

Enterprise Edition

For full HITL functionality including approval queues, workflows, and compliance reporting:

Last updated on