AI to human handoff

This guide focuses on implementing a seamless handoff connecting your virtual agent built with Twilio Agent Connect (TAC) to your live human agents in Twilio Flex. This integration ensures that when an end-user needs to escalate from the virtual agent to a human, the transition is completely smooth and contextual.

The customer stays in the same call or chat window, and your human agent is immediately equipped with an AI-generated summary of the interaction. This is achieved by a packaged escalation tool in TAC that executes the handoff with context to a Studio flow that can be built using the dedicated Studio template. The Studio flow helps to orchestrate the conversation from your virtual agent and your human agent in Twilio Flex.

• Twilio Studio
• Flex account with Flex UI version 2.17.1 or later to support the seamless handoff and the summary
• A functional phone number for Voice and SMS and a sender for Chat

• Twilio Agent Connect
• Phone Numbers for Voice / SMS
• Conversations (Classic) - For SMS and Chat based virtual agents
• Conversation Orchestrator
• Conversation Intelligence
• Studio
• Flex

The following sections will help you to set up the virtual agent to handoff flow across products

Follow the Twilio Agent Connect Quickstart guide to set up a virtual agent linked with Conversation services.

To learn more about how to setup the handoff tool and flow in Twilio Agent Connect, refer to the Escalate to a human agent guide.

The above guide contains details of the handoff flow including registering the handoff tool that works with Studio and Flex. The Studio and Flex specific steps are detailed in their dedicated section.

Refer to the following sample implementation of the handoff flow.

Run the following command to execute this implementation instead of the default example in the Twilio Agent Connect Quickstart guide.

uv run python getting_started/examples/features/handoff.py

You can also provide additional attributes as part of the handoff data. These will be available in Studio and in Flex and can be used for routing.

Note: If you want to build and integrate a Voice-based virtual agent only, you can skip this step.

By default, Twilio Flex is likely configured to send all incoming customer messages directly to a live agent through a standard Studio flow or a webhook. You might need to disconnect this so that the virtual agent gets to handle the conversation first.

1. Go to Flex > Channel Management > Messaging tab in Twilio Console.
2. Disconnect your messaging address from the existing Flex Studio flow or webhook address.

You need to set your existing Conversations (Classic) Service SID (for example, ISxxxxxxxx) as part of the Conversation Orchestrator configuration. Keep the service SID handy and update in the Conversation Orchestrator configuration in the next step.

The following steps involve updating the Conversation Orchestrator configuration to ensure that the Conversation updates with the latest communications and the handoff flow executes as intended.

Note: If you had not set the Conversation Orchestrator as part of the Twilio Agent Connect quickstart you can do that using the Conversation Orchestrator quickstart as well.

1. Go to the Conversation Configuration that you set up earlier.
2. Navigate to the Channel Traffic tab.
3. Remove existing senders from the Automatically captured traffic section.

This step is required to avoid duplicates as for Voice channel, ConversationRelay is responsible for ensuring that the Conversation stays updated. For SMS and Chat, the connection to Conversations (Classic) would take care of ensuring the sync of communications and participants. This will be configured in the next step.

Note: If you want to build and integrate a Voice-based virtual agent only, you can skip this step.

To ensure your virtual agent and your Flex Conversations (Classic)-based contact center stay perfectly in sync, you need to tell the Conversation Orchestrator which Conversations (Classic) service you are using with Flex.

1. Go to the Conversation Configuration that you set up earlier.
2. Go to the Channel Traffic tab.
3. Select Add Messaging and Chat Traffic.
4. Scroll to Connect Conversations service or Flex.
5. Select the checkmark for Connect Conversations API service or Flex and enter the Conversations (Classic) Service SID that you're using.
6. Click Save Changes.

1. Ensure the Basic timeout for channel type Voice (calls) has its "Closed" timeout set to On hangup.
2. Go to the Conversation Configuration that you set up earlier.
3. Click Edit on the Conversation lifecycle and timeouts section under the Overview tab.
4. For Channel type - Voice (calls) set On hangup as the "Closed" timeout value.
5. For SMS and Chat, continue with the default configurations.

Update the Conversation Intelligence service configurations to ensure that the summary gets generated when a conversation becomes inactive or when it ends. Complete the following steps:

1. Create an Intelligence configuration by selecting Add New in the Intelligence configuration section of Conversation Intelligence.
2. Go to the Intelligence configuration that you created.
3. Select Create Rule from the Rules section in the Details tab.
4. Select Summary as the language operator and proceed to the next steps of the wizard.
5. Select the trigger At conversation end and leave the Webhook action empty.
6. Skip the Add Context step to leave it empty.
7. Create another rule with Summary as the language operator. Keep the trigger as Conversation moved to inactive.
8. Leave the Webhook action empty and skip the Add Context step to leave it empty.

TAC must generate the structured handoff schema that allows Studio and Flex to resolve the full conversation context.

Twilio provides an out-of-the-box Studio template that handles the complex routing logic required to transition a chat from an AI to a human.

1. Go to Twilio Studio in your Twilio Console and create a new Flow.
2. Select the Twilio Agent Connect - Agent Handoff template.
3. Update the Workflow, Task Channel* and Attributes in the Send to Flex widgets for the Voice or Messaging flows as applicable.
4. Save and publish this flow.
5. Update the Twilio Agent Connect environment variable TWILIO_STUDIO_HANDOFF_FLOW_SID with the Studio Flow SID of this flow.

These are the widgets set up in the template to complete the flow:

For Voice, the flow consists of the following steps:

1. Set Variables Widget: Responsible for setting the attributes received as part of the handoff data in context to be eventually set as task attributes through the SendToFlex Widget.
2. SendToFlex Widget: Pass the context into Flex Task attributes and route it to a human agent in Flex based on the set Task workflow and attributes.

For SMS and Chat, the flow consists of the following steps:

1. HTTP Request Widget (fetch conversationSid): Send a GET request to /v2/Conversations/{conversationId}/Participants. Parse the channelId from the customer participant to obtain the v1 conversationSid.
2. HTTP Request Widget (fetch serviceSid): Send a GET request to /v2/Conversations/{conversationId}. Parse the serviceSid from the conversationsV1Bridge object.
3. ResumeConversation Widget: Use the retrieved SIDs to attach the existing conversation to the Studio execution. This widget:
   • Validates the Conversations (Classic) session.
   • Adds an onMessageAdded webhook to route messages to Studio.
   • Populates the flow.channel context required by downstream widgets.
4. SendToFlex Widget: Pass the context into Flex Task attributes through the Interactions API.

Note: Upon execution, SendToFlex updates the conversation status to handed-off. This triggers the deletion of the onMessageAdded webhook to prevent "dual-delivery" interference once the human agent is active.

To surface the virtual agent summary on the Flex Agent UI, enable the following opt-in features from Flex > Contact Center Settings > Opt-in features > Beta tab:

• For Voice-based virtual agents, enable the following feature: Virtual agent summary for voice.
• For Messaging-based virtual agents, enable the following feature: Virtual agent summary for messaging.

After you enable these features, agents can view the summary when selecting an incoming task or post-acceptance while actively working on the particular task.

• Agent Connect: Connect AI agents with handoff capabilities
• Conversation Intelligence: Provide human agents with real-time insights
• Conversation Orchestrator: Track conversation state across AI and human participants
• Studio: Build and manage communication workflows using a low-code/no-code visual builder
• Flex: Build your digital engagement center for customer support and sales teams