Overview

Agent handoff lets one character seamlessly transfer an ongoing call to another character without dropping the connection. The user stays in the same LiveKit room; only the agent’s personality, system prompt, voice, and tools change.

Common use cases:

• Customer support bot escalating to a more specialised agent
• Sales bot handing off to a technical demo agent
• A general assistant routing to a domain-specific character

Configuration

Define which characters a character can hand off to by setting handoff_targets on the source character:

{
  "slug": "support-bot",
  "handoff_targets": [
    { "slug": "billing-specialist" },
    { "slug": "technical-expert" }
  ]
}

The agent automatically gains a handoff_agent tool with a target argument restricted to the slugs listed in handoff_targets.

How it works

1. The LLM calls handoff_agent with the target character’s slug:

   { "name": "handoff_agent", "arguments": { "target": "billing-specialist" } }

2. The worker fetches the target character’s full configuration from:

   GET /api/agents/{slug}/handoff-metadata/?session_id={session_id}

3. The worker loads the new character’s system prompt, voice, tools, and appearance.
4. The worker publishes a voice.agent_handoff message on the data channel:

   { "agent_name": "Billing Specialist" }

5. The widget shows a transition screen (“Connecting you to Billing Specialist…”)
6. The new agent greets the user and the conversation continues.

The user never re-connects — the LiveKit room stays open throughout.

Widget behaviour

When the widget receives a voice.agent_handoff message, it:

• Pauses the transcript
• Shows a loading indicator with the new agent’s name
• Resumes once the new agent starts speaking

The agent name displayed is taken from the agent_name field in the handoff payload.

Handoff metadata endpoint

This endpoint is called service-to-service (agent worker → backend). You don’t call it directly.

GET /api/agents/{slug}/handoff-metadata/?session_id={session_id}

Auth: X-API-Key: {AGENT_STACK_TOKEN_SECRET}

Response: Full session metadata bundle — same shape as the JWT session metadata — for the target character.

Best practices

• Keep handoff descriptions specific. The LLM needs enough context to decide when a handoff is appropriate:

  "Transfer to the billing specialist when the user has questions about invoices, 
   payments, subscription changes, or refunds. Do not hand off for general product 
   questions."

• Limit targets. List only the characters the agent should genuinely be able to reach. A long list dilutes the LLM’s routing accuracy.
• Set a greeting on the target. The target character’s greeting should acknowledge the transition:

  "Hi! I'm the billing specialist. I understand you have a question about your account — I'm happy to help."

• Don’t hand off mid-sentence. The LLM will naturally finish its current utterance before handing off. If you need to guarantee a clean handoff point, instruct the source agent to say “Let me transfer you now” before calling the tool.