Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Not every action can be decided by a static rule. ALLOW’s Human-in-the-Loop system routes ambiguous or sensitive actions to humans for real-time approval — and surfaces gaps in your rule coverage to your engineering team. When a HITL item is created, the agent pauses and waits for a human decision. The ALLOW dashboard shows pending items with full context: agent ID, target app, action, request context, and timestamp. Engineers approve or reject with an optional reason. The agent receives the decision and proceeds accordingly.

​
Two Categories

ALLOW creates HITL items in two distinct scenarios, each with a different audience.

​
End-User Approval

Triggered when a rule has effect: hitl. The vendor has explicitly decided that this class of action requires human sign-off before proceeding. The agent pauses and waits up to hitlTimeoutMs for a human to approve or reject. Use cases:
  • High-value financial transactions (charges above a threshold)
  • Data deletion or bulk data export
  • Permission or role changes
  • Any action that is irreversible or high-stakes

​
Engineer Notification

Triggered when no rule matches the intercepted request — an uncovered scenario. The action may be logged and the vendor’s engineering team is notified via the HITL queue so they can create a covering rule. This is ALLOW’s mechanism for discovering new API patterns your agents are using. Over time, as you create rules to cover each scenario, uncovered scenarios should approach zero. Use cases:
  • First time an agent calls a new API endpoint
  • New action patterns discovered after a code change
  • Gradual rule coverage expansion during rollout

​
HITL Queue

Pending approval items appear in the ALLOW dashboard under HITL Queue. Items are listed oldest-first (FIFO). Each item shows:
  • Agent ID and target app
  • HTTP action (method and path)
  • Request context (any fields your agent supplied)
  • Category: enduser (rule-triggered) or engineer (uncovered scenario)
  • Timestamp and expiry time
  • AI-recommended rule (for engineer-category items)
To respond, select Approve or Reject and optionally provide a reason. The decision is immediately reflected in the audit log and the waiting agent receives the result on its next poll cycle (every 2 seconds).

​
Mock Device Approval Flow

ALLOW supports approval from multiple device types — phone, chat, and SaaS dashboard. When an agent action requires human approval:
  1. The agent’s SDK intercepts the outbound request and sends it to the ALLOW backend for evaluation
  2. The backend creates a HITL queue item and notifies the configured channels
  3. The end user receives the approval request on their preferred device (phone push notification, Slack/Teams message, or the dashboard)
  4. The user reviews the action context and taps Approve or Reject
  5. The decision is recorded in the backend and propagated to the waiting SDK agent via Supabase Realtime broadcast
  6. The agent’s intercepted request either proceeds (approved) or returns an error (rejected)
The entire flow happens in real time — the agent is paused at step 2 and resumes at step 6. The default timeout is 5 minutes, configurable via hitlTimeoutMs (TypeScript) or hitl_timeout_ms (Python).

​
Disabling End-User Approvals

The enduser_hitl_enabled setting controls whether rules with effect: hitl route to the HITL queue or are auto-permitted. When disabled, the agent proceeds without human approval and the audit log records hitl_result: auto_permitted. Configure via the ALLOW dashboard under Settings, or via the API: 
PUT /allow/settings
Content-Type: application/json

{
  "enduser_hitl_enabled": false
}
When enduser_hitl_enabled is true (the default), effect: hitl rules pause the agent and queue a human approval request. When set to false, those rules are treated as effect: permit at runtime — no queue item is created and the agent is never paused. The audit log always records the outcome regardless of the setting. When auto-permitted due to this toggle, the log entry includes hitl_result: auto_permitted so you have a full record of which actions bypassed human review.
Disabling end-user approvals in production means all rules with effect: hitl will auto-permit without any human review. Only disable this setting in controlled environments (e.g., load testing, staging) or when you have compensating controls in place. Re-enable before going live with production traffic.

​
Handling Approvals in Your Agent

The visiq() harness manages the pause/resume cycle automatically — your agent code does not need any special logic to handle HITL. When a tool call triggers an approval_required decision at handleToolStart, the harness pauses the agent and polls for a human decision every 2 seconds. Once a decision arrives (or the timeout expires), execution resumes or throws. There is no additional code beyond the standard visiq() integration shown in the Quickstart. The HITL flow is fully transparent to your agent — including approvals from mock devices (phone, chat, SaaS dashboard).

​
Autopilot Mode

When Autopilot is enabled in vendor settings, ALLOW uses AI to automatically create draft rules for uncovered scenarios. The agent’s request is permitted and an engineer-category HITL item is created with the draft rule for review. This is useful during the initial rollout phase when your agent is calling many APIs for the first time. Instead of blocking every uncovered action, Autopilot builds coverage automatically while keeping engineers informed. Engineer workflow for Autopilot-generated rules: Autopilot creates draft rules with source: 'autopilot' and enabled: false. These rules are visible in the Rules page, marked with an Autopilot badge so they stand out from manually created rules. To activate a draft rule:
  1. Open the Rules page and filter by the Autopilot badge
  2. Review the rule conditions — confirm they accurately describe the intended behavior
  3. Optionally edit the conditions, effect, or priority before activating
  4. Toggle the rule to enabled
Once enabled, the rule enters the active bundle and is distributed to SDK instances within the next sync interval (default 30 seconds). Uncovered-scenario HITL items for that pattern will stop appearing.
Autopilot permits all uncovered actions by design. Enable it only in audit mode or in non-production environments until you have reviewed and validated the auto-generated rules.

​
No-Coverage Defaults

When no rule matches in enforce mode, behavior is controlled by the no-coverage default setting:
SettingBehavior
approveAuto-permit all uncovered actions — log for review, engineer HITL for visibility (default)
denyAuto-deny all uncovered actions — strict mode, engineer HITL for visibility
askRoute to HITL queue for end-user or engineer approval
Setting no-coverage default to approve in production means any new API pattern your agent encounters is automatically permitted. This can expose new attack surface. Use audit mode first to understand your agent’s behavior, then create rules before switching to enforce with approve or deny defaults.
The no-coverage default is configured at Settings in the ALLOW dashboard or via PUT /allow/settings.

​
Timeouts

The default HITL wait timeout is 5 minutes (300,000 ms). Configurable via:
  • SDK: hitlTimeoutMs init option or ALLOW_HITL_TIMEOUT_MS environment variable
  • Backend: hitl_timeout_seconds in vendor settings (30–86400 seconds)
When the timeout expires, the SDK’s behavior is controlled by failBehavior:
  • 'closed' (default) — the request is denied with reason "HITL approval timed out"
  • 'open' — the request is permitted
The audit log records hitl_result: timeout when a HITL item expires, capturing the full request context and the configured failBehavior outcome. Timed-out HITL items remain visible in the queue after expiry so engineers can review them and create a covering rule — the item is not automatically removed.
Timed-out items in the queue are display-only at that point — responding to them has no effect on the agent, which has already resumed (either denied or permitted, per failBehavior). They remain for audit and rule-creation purposes.

​
Notification Channels

HITL items generate notifications to alert engineers and end users when approvals are needed. Notification channels are configured per-vendor in Settings > Notification Channels. Supported channels:
  • Dashboard notifications — HITL items appear in the ALLOW dashboard queue in real time. Always active; no configuration required.
  • Slack — Posts a message to a Slack channel via an incoming webhook URL. Configure via Settings > Notification Channels or the API.
  • Microsoft Teams — Posts an adaptive card to a Teams channel via an incoming webhook URL.
  • Email — Sends an email to one or more recipient addresses.
Configure channels via PUT /allow/settings using the notification_channels field: 
[
  { "type": "slack", "config": { "webhook_url": "https://hooks.slack.com/services/..." } },
  { "type": "teams", "config": { "webhook_url": "https://outlook.office.com/webhook/..." } },
  { "type": "email", "config": { "address": "ops@company.com" } }
]
Multiple channels of the same type are supported — for example, two separate Slack webhooks for different channels, or multiple email addresses: 
[
  { "type": "slack", "config": { "webhook_url": "https://hooks.slack.com/services/T.../security-alerts" } },
  { "type": "slack", "config": { "webhook_url": "https://hooks.slack.com/services/T.../ops-team" } },
  { "type": "email", "config": { "address": "security@company.com" } },
  { "type": "email", "config": { "address": "ops@company.com" } }
]
Notifications fire for both enduser and engineer category HITL items. If you want different routing for each category, create two separate Slack channels and use a webhook router (e.g., Zapier, n8n) to fan out based on the category field in the webhook payload.