# Escalate to a human agent

This guide shows how to transfer a conversation from your AI agent to a human agent using the TAC SDK. You'll configure a Studio Flow for routing, create the built-in handoff tool, and register it with your LLM.

## Prerequisites

Before you begin, you need:

* A working TAC setup with a Voice or SMS channel configured (see [Add TAC to your agent](/docs/conversations/agent-connect/build-with-tac))
* A [Twilio Studio](/docs/studio) Flow that routes to your target system (for example, [Twilio Flex](/docs/flex))
* The Studio Flow SID (`FW...`) for that flow

## How handoff works

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 `POST`s 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.

## Configure the Studio Flow SID

Set the `TWILIO_STUDIO_HANDOFF_FLOW_SID` environment variable in your `.env` file:

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

> \[!NOTE]
>
> If your Conversation Configuration includes Voice captureRules, remove them before using the handoff tool. When TAC uses Conversation Relay, it hydrates voice conversations automatically. Having Voice captureRules active at the same time causes duplicate messages in the conversation thread after handoff.

## Add the handoff tool

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.

```python
from tac.tools import create_studio_handoff_tool
```

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

```python
HANDOFF_ATTRIBUTES = {
    "department": "support",
    "priority": "normal",
}

async def handle_message_ready(
    message: str,
    context: ConversationSession,
    memory: TACMemoryResponse | None,
) -> str:
    handoff_tool = create_studio_handoff_tool(
        tac, context, attributes=HANDOFF_ATTRIBUTES
    )

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

    # Your LLM can now call the handoff tool when needed

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.

## Common escalation triggers

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

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

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

## Test the handoff flow

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.

## Next steps

* [AI to human handoff](/docs/conversations/solution-blueprints/ai-to-human-handoff): Set up the full handoff flow from TAC to Flex through Studio.
* [Add TAC to your agent](/docs/conversations/agent-connect/build-with-tac): Add custom tools and knowledge search alongside handoff.
* [Channels](/docs/conversations/agent-connect/channels): Learn more about channel configuration and routing.