Return values

When creating functions, you can specify return values to control the agent’s behavior dynamically. The return value can either be a string or a dictionary containing specific fields to guide the virtual agent.

String return

You can return a simple string, which will be used as the system prompt for the virtual agent:

return "Tell the caller that you cannot assist with their request"

Dictionary return

This feature is experimental and may change without warning.

Alternatively, you can return a dictionary to specify more detailed and deterministic instructions. The following fields can be used individually or in combination:

content

Equivalent to returning a string, this field specifies the system prompt:

return {
  "content": "Tell the caller that you cannot assist with their request"
}

utterance

Specifies the exact phrase the virtual agent will speak after executing the function:

return {
  "utterance": "I cannot assist with your request."
}

Note: If both content and utterance are returned:

• The agent will stream the utterance to the user and end the turn.
• The content rules will apply to the next turn.

handoff

Initiates a call handoff after the function executes. This follows the format of a handoff object:

return {
  "handoff": {
    "type": "CALL_CENTER",
    "reason": "SPEAK_TO",
    "refer": {
      "phone_number": "12345"
    }
  }
}

invite

Hands the call off using a SIP INVITE. Configuration fields depend on project telephony integration requirements:

return {
  "handoff": {
    "invite": {
      "phone_number": "<eg: 2222222>",
      "outbound_caller_id": conv.caller_number,
      "outbound_endpoint": "<ADD_YOUR_OUTBOUND_ENDPOINT_NAME>",
      "sip_headers": {
        "X-ANY_HEADER_NAME": "header"
      }
    }
  }
}

hangup

Ends the call after the function executes:

return {
  "hangup": True
}

listen Return Object

Configures the agent to listen on the next turn.

To use asr.timeout, you must include an utterance. Without it, the timeout won’t apply.

return {
  "utterance": "Can I help you with anything else?",
  "listen": {
    "asr": {
      "timeout": 20
    }
  }
}

ASR timeout doesn’t apply to DTMF-only input. If using both channels, make sure you include an utterance so the ASR settings take effect.

variant

Switches the conversation to a different variant:

return {
  "variant": "orleans"
}