Handoffs¶

Handoffs configure SIP call transfers for voice agents. They define how and where a call should be transferred, or whether it should be ended.

Handoffs are used when an agent needs to escalate, transfer, or terminate a voice interaction in a controlled way.

Handoffs are ADK-only

The Agent Studio UI does not currently expose an editor for config/handoffs.yaml. Define handoffs through the ADK and push them with poly push. Template references of the form {{ho:handoff_name}} only resolve inside ADK-managed files (rules.txt, topic actions, flow prompts) — pasting them into a UI-editable field does not work at runtime.

Location¶

Handoffs are defined in:

config/handoffs.yaml

They are listed under the handoffs key.

What a handoff contains¶

Each handoff includes the following fields:

Field	Description
`name`	Identifier for the handoff. Referenced in rules as `{{ho:handoff_name}}`.
`description`	Explains what the handoff does.
`is_default`	Whether this is the default handoff.
`sip_config`	Transfer method configuration.
`sip_headers`	Optional custom SIP headers as key/value pairs.

SIP config types¶

A handoff uses one of three SIP methods:

Method	Use	Fields
`invite`	Start an outbound new call	`phone_number`, `outbound_endpoint`, `outbound_encryption`
`refer`	Transfer an existing call	`phone_number`
`bye`	End the call	No extra fields

Notes¶

phone_number should use E.164 format
outbound_encryption can be TLS/SRTP or UDP/RTP

Example¶

handoffs:
  - name: escalation_handoff
    description: Transfer to a live agent for complex issues
    is_default: false
    sip_config:
      method: refer
      phone_number: "+15551234567"
    sip_headers:
      - key: X-Reason
        value: escalation

  - name: end_call
    description: End the call gracefully
    is_default: false
    sip_config:
      method: bye

How handoffs are used¶

In code

Call a handoff directly with conv.call_handoff(...).
In rules

Refer to a handoff using {{ho:handoff_name}}.
In topics and flows

Instruct the model to call a function that performs the handoff.

In code¶

You can trigger a handoff directly in code:

conv.call_handoff(destination="handoff_name", reason="transfer_reason")

In rules¶

A handoff can be referenced in rules.txt using:

{{ho:handoff_name}}

This is useful when rules need to explain when escalation or transfer should happen.

In topics and flows¶

Topics and flows should generally not perform raw transfer logic directly in prompt text. Instead, they should guide the model toward calling a function that performs the handoff.

For example:

Use {{fn:transfer_call}} when the user needs to be transferred to a specialist.

Round-trip behavior¶

After a push and pull, sip_headers: [] may be added to handoff entries that did not originally define it. This is injected by the platform and does not affect runtime behavior — the empty list is equivalent to no SIP headers. Expect this field to appear on round-trip if you did not include it yourself.

Best practices¶

use clear, descriptive handoff names
use E.164 format for phone numbers
create one handoff definition per transfer purpose
keep sip_headers minimal
only add custom SIP headers when the receiving system actually requires them

One purpose per handoff

Avoid reusing a single handoff for multiple destinations or business cases. Clear handoff names make rules and code easier to understand.

Functions

See how handoffs are typically triggered from deterministic logic. Open functions
Agent settings

Learn how handoffs are referenced in rules. Open agent settings
Conversation object reference (platform)

Full reference for conv.call_handoff — destination, reason, utterance, and SIP header overrides. Open conv object reference