> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/operations-and-safety/operators.md). # Operators and Escalation The Developer Console's unified **Runs** surface is the operator entry point. Its **Live** tab is the urgency-ranked queue, and an eligible row or run detail page opens takeover controls for that exact run in place. Some situations require clinical judgment, emotional sensitivity, or authority that only a human can provide. The operator system handles the handoff between agent and human. When an operator joins a voice call, they enter the same conference as the caller and the agent. Listen mode does not transfer or reconnect the call. If the operator chooses to speak, the console requires an explicit confirmation before unmuting them and suppressing the agent's voice. For eligible text, SMS, email, and web runs, takeover pauses the agent while the operator authors replies, then resumes it when the operator hands control back. ```mermaid sequenceDiagram participant Caller participant Agent participant Operator participant Runs Note over Caller,Agent: Normal conversation Caller->>Agent: Speech audio Agent->>Caller: Response audio Note over Agent,Operator: Escalation triggered Agent-->>Runs: Live run + escalation context Operator->>Runs: Opens selected run Runs-->>Operator: Live transcript + takeover controls Operator->>Agent: Joins conference (listen mode) Note over Caller,Operator: Operator listening Caller->>Agent: Speech audio Agent->>Caller: Response audio Operator-->>Agent: Inject guidance (caller unaware) Note over Caller,Operator: Operator takes over Operator->>Caller: Speaks directly Note over Agent: Turn processing paused; human turns captured Note over Caller,Agent: Operator leaves Agent->>Caller: Resumes with captured handback context ``` ## How Escalation Policy Works Escalation behavior is authored in the agent's context graph and instructions. Teams define which user requests, safety boundaries, unavailable tools, or uncertain situations require a transfer, callback, refusal, or operator involvement. The current runtime does not provide a separate monitor-concept system that can replace those instructions. Runs Live shows eligible active work and uses available call signals to help order voice rows. An operator can choose a run, join in listen mode, and explicitly take over. Supported join paths emit escalation and operator-attribution events. Define a fallback for times when no operator is available. Depending on the workflow, that can mean a configured external transfer target, a callback task, emergency instructions, or a bounded response that does not continue beyond the agent's authority. ## Runs Live and Takeover Takeover is part of the unified Runs experience rather than a separate operator screen. ### Live Queue The **Live** tab requests running and paused runs across supported kinds. Active conversations can appear while they are in progress; framework list and history data is best-effort and normally becomes available at terminal completion rather than serving as authoritative real-time dispatch state. Voice calls are ranked with the shared urgency rule: matched escalation data contributes risk and immediacy when available, while elapsed wait time provides a fallback for a live call without matching escalation data. Non-call runs remain visible without being treated as urgent calls. Rows show the run type, entity, service, caller, status, outcome, turn count, direction, start time, and duration. A critical spotlight calls attention to the highest-priority eligible call. Selecting **Take over** from a row or run detail page opens a run-scoped drawer without navigating to another queue or resolving the call a second time. ### Operator Modes Voice operators work in one of two modes: * **Listen mode** - The operator hears the conversation but is muted at the telephony level, and the agent continues handling the call. The platform does not add operator speech or an audible join announcement; organizations remain responsible for any monitoring disclosures required by policy or law. * **Takeover mode** - After explicit confirmation, the operator is unmuted and speaks directly with the caller. Agent speech and turn processing are suspended; caller and operator speech is captured for handback context. When the operator switches back to listen mode or leaves, the agent resumes in the existing session. During takeover, the operator's speech is transcribed separately and recorded as operator turns when transcription succeeds. The retained call record can therefore include the human segment alongside agent and caller turns. ### Text-Channel Takeover For an eligible live text, SMS, email, or web run, the takeover drawer shows the conversation turns. The operator explicitly pauses the agent, authors the next reply, and can continue sending replies while driving the conversation. **Hand back** returns control to the agent. ### Connection Methods Operators connect to calls through one of two methods: * **Phone (PSTN)** - The platform dials the operator's phone number. When the operator answers, they are added to the conference. This works from a standard phone but adds a PSTN media leg whose latency depends on the carrier path. * **Browser (WebRTC)** - The operator connects through a web browser using the voice SDK. This avoids dialing the operator over PSTN and is intended for desktop operators with a headset. The browser flow requests an access token, registers the operator for the call, and connects with the provided token. Only one operator can be active on a call at a time. If a second operator attempts to join the same call, they receive a conflict error. The same operator joining the same call again receives the cached response (the join is idempotent). ### Run Context The takeover drawer identifies the caller and service and shows the live transcript for voice. The run detail page provides the channel-specific record behind the selected row, keeping the operator anchored to the run they chose. ### Guidance Injection Operators in listen mode can send text guidance to the agent without taking over the call. When delivery reaches the active session, the current voice runtime interrupts agent speech and frames the guidance for the agent's next response. The API can also report queued or failed delivery, so clients should inspect the returned status rather than assume the instruction was applied. This is useful when an operator sees the conversation going in the wrong direction and wants to steer the agent without adding operator audio to the call. For example, an operator monitoring a scheduling call could send "Ask for their insurance ID before confirming the appointment" for the agent to incorporate into its next response. Guidance messages are distinct from external events. External events carry factual information ("The appointment has been confirmed") and queue behind the agent's current speech. Guidance carries instructions ("Ask about their insurance") and interrupts because instructions are time-sensitive. Both event types use the active voice-session delivery path, which routes the event to the session handling the call. ## Silence Management Silence handling is a dedicated voice-runtime behavior. It does not depend on a composite risk score or a separate conversation-monitoring service. If the caller stops speaking, the silence monitor manages this with exponential backoff: 1. After **10 seconds** of silence, the agent generates a short check-in. 2. If there is still no response, the next threshold is **20 seconds**. 3. At the third unanswered threshold, capped at **40 seconds**, the agent generates a brief goodbye and ends the call. Check-in utterances have a 5-second staleness window. If the caller speaks during the check-in filler, the filler is discarded and the conversation continues normally. This prevents awkward overlaps where the agent says "Are you still there?" just as the caller starts talking. Caller speech resets the silence sequence. Safety and escalation behavior remains governed by the authored agent policy and explicit operator or forwarding workflows. ## Speaker Resolution With three participants in a conference (caller, agent, operator), the system resolves who is speaking at any given moment using a priority chain: 1. **Operator in takeover mode** - Highest priority. Agent audio is suppressed. 2. **Caller** - Barge-in detection applies. If the caller speaks during agent output, the agent stops. 3. **Agent** - Speaks when neither the operator nor the caller is active. Humans always take precedence over the agent, and the caller always takes precedence over the agent's output. ## Warm Hand-Off Warm forwarding is a service-level call-forwarding mode, separate from an operator joining through Runs. When the agent invokes `forward_call` and the resolved forwarding configuration uses `warm_transfer: true`, the runtime keeps the caller in the conference, dials the configured destination, and gives the agent a brief hand-off turn before connecting the caller to the person who answered. Cold forwarding remains available when a briefing is inappropriate, such as an IVR, voicemail, or emergency destination. ### Phase 1: Normal The agent and caller are in conversation as usual. Authored instructions decide when the agent should invoke `forward_call`; the runtime then resolves the destination from the supported forwarding inputs and service configuration. ### Phase 2: Briefing After the agent's current speech drains, the runtime temporarily holds the caller and dials the forwarding target. If someone answers, the caller is unheld and all three parties can hear the agent's short introduction of the caller's need. The hand-off is intentionally brief; it is not a guaranteed transfer of the full transcript, patient record, risk assessment, or recommended actions. Barge-in is disabled during the briefing phase so speech from the caller or forwarding target does not interrupt the agent's introduction. ### Phase 3: Connected After the briefing speech drains, the runtime removes the agent and leaves the caller connected to the forwarding target. If the target does not answer, the runtime returns the call to the agent so it can explain the result and continue helping. ```mermaid sequenceDiagram participant Patient participant Agent participant Destination Note over Patient,Agent: Phase 1: Normal Patient->>Agent: "Can I speak to someone?" Note over Patient,Destination: Phase 2: Briefing Agent->>Destination: Dials configured target Agent->>Patient: AI briefing (patient hears) Agent->>Destination: AI briefing (destination hears) Note over Patient,Destination: Phase 3: Connected Note over Agent: Removed from call Patient->>Destination: Direct conversation ``` `warm_transfer` defaults to `true` when a service forwarding configuration is created without an explicit value. Set it to `false` for a cold transfer. ## Deferred Transfer When the agent initiates a call transfer (for example, forwarding to a clinic's front desk), the transfer is deferred until the agent's goodbye message finishes playing. This prevents the caller from being redirected mid-sentence. If the caller speaks during the goodbye (barge-in), the transfer is cancelled and the conversation continues. If an operator joins the call during this window, the transfer is also cancelled. ## Operations Views Operators register with a profile that includes their name, skills, connection method (phone or browser), and role. Their status is tracked as online, busy, or offline. The Developer Console separates live intervention from historical review: * **Runs > Live** - Urgency-ranked live work and in-place takeover. * **Runs > All runs** - Filterable conversation and framework history. * **Runs > Overview** - Workspace totals and status distributions. * **Operator analytics and audit** - Escalation, response-time, handle-time, and attributed operator-action records exposed through the operator and analytics APIs. ## Escalation as Collaboration The agent handles the routine part, and the operator handles the part that needs human judgment. Both contribute to the same run record. After a voice takeover, the agent can resume with the captured caller and operator turns as handback context. Use escalation rates, response times, handle times, and fallback outcomes to inform staffing. Do not assume automation removes the need to staff authored escalation paths or maintain an unavailable-operator fallback. {% hint style="info" %} **Developer Guide** - For API endpoints and integration details, see the [Operators](https://docs.amigo.ai/developer-guide/platform-api/conversations/operators) reference in the developer guide. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/operations-and-safety/operators.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.