Escalate to a human agent

Before you begin, you need:

• A working TAC setup with a Voice or SMS channel configured (see Add TAC to your agent)
• A Twilio Studio Flow that routes to your target system (for example, Twilio Flex)
• The Studio Flow SID (FW...) for that flow

The handoff flow differs by channel type:

Voice: Your agent's LLM calls the handoff tool. The tool builds a HandoffPayload with conversation context and stores it on the session. After the LLM's final response plays to the caller, the Voice channel sends a WebSocket end message with the payload. Twilio routes the call to your Studio Flow via the <Connect action> URL.

Digital (SMS, chat): Your agent's LLM calls the handoff tool. The tool POSTs the HandoffPayload directly to the Studio Flow Executions API, which starts a new flow execution for the customer.

In both cases, the HandoffPayload includes the conversation ID, memory store ID, profile ID, and any custom attributes you define. Your Studio Flow can reference these values to route the conversation.

Set the TWILIO_STUDIO_HANDOFF_FLOW_SID environment variable in your .env file:

TWILIO_STUDIO_HANDOFF_FLOW_SID=FWxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The SDK uses this SID to derive both the Studio Executions URL (for digital handoff) and the <Connect action> webhook URL (for voice handoff).

The create_studio_handoff_tool function returns a tool your LLM can call to trigger a handoff. It takes the TAC instance, the current conversation session, and optional routing attributes.

from tac.tools import create_studio_handoff_tool

In your message handler, create the tool and pass it to your LLM:

1
HANDOFF_ATTRIBUTES = {
2
    "department": "support",
3
    "priority": "normal",
4
}
5

6
async def handle_message_ready(
7
    message: str,
8
    context: ConversationSession,
9
    memory: TACMemoryResponse | None,
10
) -> str:
11
    handoff_tool = create_studio_handoff_tool(
12
        tac, context, attributes=HANDOFF_ATTRIBUTES
13
    )
14

15
    # Add to your LLM's tools alongside other tools
16
    tools = [handoff_tool, knowledge_tool]
17

18
    # Your LLM can now call the handoff tool when needed
19

20
tac.on_message_ready(handle_message_ready)

The attributes dictionary is optional. Use it to pass routing metadata your downstream system expects. For Flex, these surface as TaskRouter task attributes.

When the LLM calls this tool, it accepts a reason parameter (a string explaining why the conversation needs a human). The tool builds a HandoffPayload and delivers it to your Studio Flow.

Configure your agent's system prompt to recognize common escalation scenarios:

1
You are a helpful customer service agent. Escalate to a human agent when:
2
- The customer explicitly asks to speak with a human
3
- You cannot resolve the customer's issue after two attempts
4
- The conversation involves billing disputes or account security
5
- The customer expresses frustration or dissatisfaction

Your LLM uses this guidance along with the handoff tool to decide when to hand off.

1. Start your TAC server with the handoff tool configured and TWILIO_STUDIO_HANDOFF_FLOW_SID set.
2. Call your Twilio phone number (or send an SMS) and ask to speak with a human agent.
3. Verify that your agent calls the handoff tool.
4. For voice: confirm the caller hears the LLM's final response, then the call routes to your Studio Flow.
5. For digital: confirm the Studio Flow execution starts with the HandoffPayload in the flow data.
6. Check that the HandoffPayload includes your custom attributes, conversation ID, and profile ID.

• AI to human handoff: Set up the full handoff flow from TAC to Flex through Studio.
• Add TAC to your agent: Add custom tools and knowledge search alongside handoff.
• Channels: Learn more about channel configuration and routing.