Skip to main content

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-onlyThe 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:
FieldDescription
nameIdentifier for the handoff. Referenced in rules as {{ho:handoff_name}}.
descriptionExplains what the handoff does.
is_defaultWhether this is the default handoff.
sip_configTransfer method configuration.
sip_headersOptional custom SIP headers as key/value pairs.

​
SIP config types

A handoff uses one of three SIP methods:
MethodUseFields
inviteStart an outbound new callphone_number, outbound_endpoint, outbound_encryption
referTransfer an existing callphone_number
byeEnd the callNo 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 handoffAvoid 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.

Agent settings

Learn how handoffs are referenced in rules.

Conversation object reference (platform)

Full reference for conv.call_handoff — destination, reason, utterance, and SIP header overrides.
Last modified on July 9, 2026