Call Escalation

[jjleng]

Description

We need to implement a Call Escalation / Human Handoff feature that allows the AI voice agent to gracefully forward an active phone call to a human agent, a specific phone number, or a SIP destination.

Note: This feature is only applicable to active telephony sessions (PSTN/SIP via Twilio/Telnyx). WebRTC sessions (e.g., in-browser testing) are not supported since there is no underlying telephone network to bridge the route.

Implementation Requirements

1. Tooling Integration: Introduce a native escalate_call (or forward_call) tool into the agent's skill set so the LLM can decide when escalation is needed. This avoids conflict with our existing transfer_to node-routing tools within the agent graph. This tool should only be registered and available to the LLM if the session transport is Telephony.
2. Telephony Layer: Leverage Twilio/Telnyx APIs or SIP REFER methods at the voice-server layer to physically route the call to the destination number/SIP URI, bridging the connection and terminating the AI session.
3. Studio Web Configuration: Add an "Escalation" configuration block in the Studio Dashboard to allow users to easily set up escalation behaviors and define target numbers. The UI should note that this feature does not apply to the web testing client.
4. Agent Prompts: Provide default system prompt configurations that explicitly instruct the agent to trigger the escalate_call tool when a conversation hits defined escalation_triggers, the user becomes frustrated, or they explicitly ask for a human representative.