​

Human-in-the-Loop (HITL)

The HITL system lets human operators monitor, intervene in, and approve AI agent conversations. Configure when and how conversations escalate to humans, what users see during the process, and how approvals work.

​

Configuring HITL

Navigate to your agent’s Tools tab and click Escalate to Human to open the HITL configuration page. Settings are organized into three sections:

​

Escalation

Controls when and how conversations transfer to a human operator.

​

Queue & Availability

Controls what happens when operators are busy or offline.

​

Approval

Controls whether AI responses require human review before being sent.

​

Operator Dashboard

The Operator Dashboard is available at /operator in the sidebar. It provides:

• Stats bar: Pending escalations, active conversations, pending approvals, resolved today
• Escalation queue: Priority-sorted list of waiting escalations with one-click claim
• Quick actions: Live Conversations, Approval Queue, History
• Real-time updates: WebSocket-powered live feed of events

​

Status Management

Operators can set their availability status: Online, Busy, Away, or Offline. When an operator comes online, any queued escalations are automatically assigned to them if they have capacity.

​

Browser Notifications

The dashboard requests browser notification permission on first visit. When enabled, operators receive push notifications for:

• New escalations
• Escalation assignments
• New user messages in active conversations
• Responses awaiting approval

​

Notification Bell

A bell icon appears next to the Operator nav item in the sidebar for all operator-role users. It shows a red badge with the count of pending items and a dropdown of recent alerts — visible from any page, not just the dashboard.

​

How Escalation Works

1. The AI decides to escalate (or an operator takes over manually)
2. User sees the Escalation Started message
3. If an operator is available → auto-assigned, user sees Operator Joined
4. If no operators → user sees Queued message and waits
5. Operator claims from dashboard → sends messages directly to user
6. Operator hands back or closes → AI resumes (or conversation ends)
7. If queue timeout expires → user sees Expired message, AI resumes

​

Concurrency Safety

Multiple operators can work simultaneously without conflicts. All claim and approval operations use atomic database updates — if two operators click “claim” at the same time, only one succeeds and the other sees an “already claimed” message.