Reference Variables

Learn how to use reference variables to store and reuse data from function responses

Reference variables let you store and reuse specific data returned from a function response.

Reference variables offer a powerful way to condition your GenerativeAgent tasks and functions on real data returned by your APIs—all without requiring code edits.

By properly naming, key-pathing, and optionally transforming your variables, you can build flexible, dynamic flows that truly adapt to each user’s situation.

Once a reference variable is created, you can use it to:

• Conditionally make other Functions available
• Set conditional logic in prompt instructions
• Compare values across different parts of your GenerativeAgent workflow
• Control Function exposure based on data from previous function calls.
• Toggle conditional instructions in your Task s prompt depending on returned data
• Extract and transform values without hard‐coding logic into prompts or code

Reference variables can be configured in the GenerativeAgent Tooling Function edit page under the “Reference vars ” option.

Define a Reference Variable

To create a reference variable in the GenerativeAgent UI:

1. Navigate to the Function’s settings
2. Find the “Reference vars (Optional)” section and click “Add”
3. Configure the following fields:

• Name
• Response Keypath
• Transform Expression (Optional)

Name

This is the identifier you’ll use to reference this variable in Jinja expressions.

vars.get("variable_name")

Response Keypath

This is the JSON path where the data will be extracted from, using dot notation.

// For a response like:
{
  "available_rooms": [...]
}
// Use keypath:
response.available_rooms

Transform Expression (Optional)

This is a Jinja expression to transform the extracted value. Common patterns include:

# Check for specific string value
val == "COMPLIANT"

    # Check boolean values
    val == true or val == false

# Check for non-empty arrays/strings
val is not none and val|length > 0

Once saved, GenerativeAgent will automatically update these variables whenever the Function executes successfully and returns data matching the specified keypath.

Reference variable names are not unique across the entire system.

If more than one Function defines a reference variable with the same name, whichever Function is called last may overwrite a variable’s value.

Reference variables are also used at runtime, meaning GenerativeAgent extracts the specified response data from each API call that returns successfully and updates the variable accordingly.

Example Condition

The following example calls a Condition on a CheckRoomAvailability Function.

1. Suppose a Reference Variable named rooms_available and defined with:
   • Response Keypath: response.available_rooms
   • Transform: val is not none and val|length > 0
2. The rooms_available variable will be True whenever the returned list has a length greater than zero. You can then write:
3. In a Function’s conditions (to make a function available for use, conditioned on the reference variable):
       conditions: vars.get("rooms_available")
   

4. In Task instructions using Jinja:
           {%- if vars.get("rooms_available") %}
           The requested rooms are available.  
           {%- else %}
           No rooms are currently available.  
           {%- endif %}
   

Tips and Best Practice

Here are some tips to enhance your experience with Reference Variables:

Prefix Variables

Consider prefixing variable names to avoid clashes if multiple teams define references.

Example: user_is_compliant vs. is_compliant

Short-circuit logic

Use short-circuit logic in transforms to avoid “NoneType cannot have length” errors

Example val is not none and val|length > 0

Functions consideration

Keep in mind that if multiple Functions define the same reference variable name, one may overwrite the other depending on the call order.