> ## Documentation Index > Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt > Use this file to discover all available pages before exploring further. # Human-in-the-Loop > Configure operator oversight, escalation, and approval workflows for your AI agents. # 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. | Setting | Options | Description | | ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Escalation Mode** | both, ai\_only, manual\_only | `both`: AI can trigger escalation + operators can take over manually. `ai_only`: only AI decides. `manual_only`: operators intervene from the dashboard only. | | **Escalation Instructions** | Text | Guides the AI on when to escalate (e.g., "escalate when the user asks about refunds"). | | **Escalation Started Message** | Text | Shown to the user when escalation begins. | | **Operator Joined Message** | Text | Shown when an operator claims the conversation. | ### Queue & Availability Controls what happens when operators are busy or offline. | Setting | Options | Description | | ------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Outside Hours Behavior** | queue, message\_only, fallback\_email | `queue`: create escalation and wait. `message_only`: show a message without escalating. `fallback_email`: queue and send email notification to a verified address. | | **Queue Timeout** | 60–86400 seconds | How long an escalation waits before expiring. Default: 300 (5 minutes). | | **Queued Message** | Text | Shown when operators are busy and user enters queue. | | **Outside Hours Message** | Text | Shown when queued outside operator working hours. | | **No Operators Message** | Text | Shown with `message_only` behavior when no operators are available. | | **Escalation Expired Message** | Text | Shown when the queue timeout is reached. AI resumes automatically. | When selecting **fallback\_email**, a verified email input appears below the config form. You must verify the email via OTP before it can receive escalation notifications. ### Approval Controls whether AI responses require human review before being sent. | Setting | Options | Description | | ----------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Approval Mode** | off, all, llm\_decides | `off`: no approval needed. `all`: every response is held for review. `llm_decides`: AI flags responses it thinks need review. | | **Approval Instructions** | Text | Only visible when mode is `llm_decides`. Guides the AI on what to flag. | | **Pending Approval Message** | Text | Shown while response is awaiting operator review. | | **Approval Rejected Message** | Text | Shown when an operator rejects a response. AI resumes. | ## 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.