System Transfer Functions signal that control of the conversation should be transferred from GenerativeAgent to an external system. They can also return reference variables (e.g., a determined “intent,” or details about a charge) for further processing outside of GenerativeAgent. By using a System Transfer Function, you can:
  • End the conversation gracefully, indicating that GenerativeAgent is finished.
  • Hand control back to the calling application or IVR once a goal is met.
  • Send relevant conversation data (e.g., identified charges, subscription flags, or determined intent) for follow-up workflows.
To create a system transfer function:
  1. Create a function
  2. Define input parameters
  3. Set variables (optional)
  4. Save the function
  5. Use the function in a task
  6. Handle the system transfer event

​
Step 1: Create a New Function

Navigate to the Functions page and click “Create Function.”
  1. Select “System transfer” and click “Next: Function details”
    Set System Transfer Function
  2. Specify the Name and Purpose of the Function
    • Function Name: Provide a concise, unique name, using underscores (e.g., issue_refund_request).
    • Function Purpose: Briefly describe what the function does (e.g., “Takes the collected charge info and indicates a refund request should be processed”).
      • GenerativeAgent uses this description to determine if/when it should call the function.

​
Step 2: Define Input Parameters (JSON)

The input parameters are the values that GenerativeAgent needs to pass when calling this function to transfer control to the external system. Under “Input Parameters,” enter a valid JSON schema describing the required parameters. GenerativeAgent will gather the necessary information (from user messages or prior context) before calling the function.
Example Input Schema
{
  "type": "object",
  "required": [
    "line_item_number",
    "is_eligible_for_refund",
    "is_subscription"
  ],
  "properties": {
    "line_item_number": {
      "type": "string",
      "description": "The line item number associated with the charge"
    },
    "is_eligible_for_refund": {
      "type": "boolean", 
      "description": "Whether or not the line item is eligible for a refund"
    },
    "is_subscription": {
      "type": "boolean",
      "description": "Whether or not the charge is associated with a subscription"
    }
  }
}

​
Step 3: (Optional) Set Variables

Though System Transfer Functions typically return control to an external system, you can still configure one or more reference variables:
  • Configure variables to rename or transform parameter values for the external system
  • Use Jinja2 for transformations if needed
  • Toggle “Include return variable as part of function response” to make variables immediately available

​
Jinja2 Templates

Use Jinja2 to transform values before transfer. For example, to convert a string boolean to a proper boolean: 
true if params.get("is_subscription") == "True" else false
System Transfer Function

​
Step 4: Save Your Function

With your function defined, save it by clicking “Create Function”. After saving, you’ll see a detail page showing the JSON schema and any configured reference variables.

​
Step 5: Using the System Transfer Function in the Conversation

Once you have created your system transfer function, you must add the function to the task’s list of available functions for GenerativeAgent to use it. GenerativeAgent may call the function proactively, but we recommend you instruct GenerativeAgent to call the function explicitly. Always make sure to test your functions with Previewer to ensure they work as expected. Here’s how the function works within a task and conversation flow:
  1. GenerativeAgent collects the required parameters from the user (or context).
  2. (Optional) A “Message before Sending” can be displayed to the user, clarifying why GenerativeAgent is transferring control.
  3. Jinja2 transformations convert or combine inputs, if defined.
  4. GenerativeAgent calls the System Transfer Function, signaling that control returns to the external system.
    • All reference variables collected during the conversation are passed along.
    • If configured, the function’s specific variables also appear in the final response.

​
Best Practices

​
Step 6: Handle the System Transfer Event

When the function is called in your task, the conversation will be transferred to your system. This transfer is communicated via the generative agent events that are sent as part of the conversation handling. Each reference variable currently set are passed as referenceVariables, and any variables set in the function are passed as transferVariables.
Example System Transfer Event
{
  "generativeAgentMessageId": "bba4320f-de53-4874-83b4-6c8704d3620c",
  "externalConversationId": "33411121",
  "conversationId": "01HMVXRVSA1EGC0CHQTF1X2RN3",
  "type": "systemTransfer",
  "systemTransfer": {
    "referenceVariables": {
      "customerName": "John Smith",
      "accountNumber": "12345",
      "isActive": true
    },
    "transferVariables": {
      "line_item_number": "1234567890",
      "is_eligible_for_refund": true,
      "is_subscription": false
    },
    "currentTaskName": "handle_refund_requests"
  }
}

​
Next Steps

Task Best Practices

Learn more about best practices for task and function configuration.

Set Variable Functions

Learn how to store and manipulate conversation data with Set Variable Functions.

Connecting Your APIs

Connect your external systems to enable system transfers.

Previewer

Test your system transfer functions in real-time with the Previewer tool.