# AI to human handoff

## Overview

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.

## Prerequisites

* [Twilio Studio](/docs/studio)
* [Flex account](/docs/flex) 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

## Systems involved in the solution

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

## Setup

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

### Twilio Agent Connect

Follow the [Twilio Agent Connect Quickstart guide](/docs/conversations/agent-connect/quickstart) 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](/docs/conversations/agent-connect/escalate-to-human-agent).

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](https://github.com/twilio/twilio-agent-connect-python/blob/main/getting_started/examples/features/handoff.py) of the handoff flow.

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

```bash
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.

### Conversations (Classic)

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

#### Remove existing integrations from Conversations (Classic) Address Configuration

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.

#### Note the Conversation Service SID

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.

### Conversation Orchestrator

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](/docs/conversations/orchestrator/quickstart) as well.

#### Remove automatically captured traffic

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.

#### Link Conversation Orchestrator to your Flex environment

*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**.

#### Update Conversation lifecycle and timeouts

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 Intelligence configuration for Conversation Intelligence

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.

### Set up the Studio Flow

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.

### Enable summary for virtual agent on Flex

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.

## Related products

* [Agent Connect](/docs/conversations/agent-connect): Connect AI agents with handoff capabilities
* [Conversation Intelligence](/docs/conversations/intelligence): Provide human agents with real-time insights
* [Conversation Orchestrator](/docs/conversations/orchestrator): Track conversation state across AI and human participants
* [Studio](/docs/studio): Build and manage communication workflows using a low-code/no-code visual builder
* [Flex](/docs/flex): Build your digital engagement center for customer support and sales teams