Agent Script Pattern: Using List Variables

With list variables (also called collection variables), your agent can store and iterate over a collection of values. For example, you can create a list of questions that an interview agent must ask, or a list of objects to store an action’s output. A list can store any supported type such as strings, booleans, numbers, or objects.

You can use a list item anywhere you use a custom variable. To reference an item in your list, use [<item_number>]. List indexes start at 0, so the first item in your list is @variables.YourVariable[0].

1@variables.YourVariable[2]

Why Use This Pattern

Use list variables for:

Working through a sequence of items one at a time, such as interview questions, checklist items, or search results.
Storing multiple outputs from an action, such as a list of account records.
Tracking progress through a collection by pairing a list with an index variable.

Declare a List Variable

Declare a list variable in the variables block. Specify the list type in brackets []. You can initialize an empty list with =[], or set default values.

Declare List Variables

1variables:
2    # Declare a list of objects
3    CandidateList: mutable list[object] = []
4        description: "List of contacts returned from an action"
5    CompetencyQuestions: mutable list[string] = ["Tell me about a time you disagreed with a coworker.", "Tell me about one of your favorite shifts.", "What are the most important qualities in a candidate?"]
6        description: "List of questions to determine competency."

Use a List Item in Reasoning Instructions

In this example, if question 3 is “Tell me about your work history”, the prompt sent to the LLM is “Ask the candidate this question: Tell me about your work history”.

1reasoning:
2        instructions: ->
3            |Ask the candidate this question: {!@variables.CompetencyQuestions[0]}

Reference a List Item with a Variable

You can use a variable to reference a list item.

1reasoning:
2    instructions: ->
3        | Ask this question: {!@variables.questions[@variables.current_question]}

Use a List Item in Reasoning Logic

You can use a list item in conditional expressions.

1# In the variables section, define a list of booleans
2variables:
3    areAnswersCorrect: mutable list[boolean]
4        description: "True if the answer is correct, otherwise False"
5....
6# Later, as the user answers questions, record whether the answer was correct (not shown)
7...
8
9#  In a topic, if the THIRD answer is incorrect, end the interview
10    reasoning:
11        instructions: ->
12            # remember that lists are zero-indexed ;-)
13            if @variables.areAnswersCorrect[2] == "False":
14                transition to @topic.end_interview

Get the Length of a List

Use len(@variables.MyList) to get the number of items in a list. You can use len(@variables.MyList) in prompts, available when filters, and conditional expressions.

1# For example, the agent might say "this is question 5 of 7"
2reasoning:
3    instructions: ->
4        | This is question {!@variables.question_index + 1} of {!len(@variables.questions)}.

Iterate Through a List

Agent Script doesn’t have a for loop. Instead, iterate by incrementing the index variable after each turn.

This example asks each question in a list one at a time. After the agent records an answer, the index advances. When the index reaches the list length, the agent transitions to the next topic.

1variables:
2    questions: mutable list[object] = []
3        description: "Questions to ask the candidate"
4    question_index: mutable number = 0
5        description: "Current index in the questions list"
6    is_GetQuestions_run: mutable boolean = False
7        description: "Whether the action Get_Questions has been run"
8
9topic ask_questions:
10    description: "Ask the candidate questions one at a time."
11
12    reasoning:
13        instructions: ->
14            if @variables.is_GetQuestions_run == False:
15                run @actions.Get_Questions
16                    with JobScreeningRecordId=@variables.JobRecordID
17                    set @variables.questions = @outputs.AllScreeningQuestions
18                    set @variables.question_index = 0
19                    set @variables.is_GetQuestions_run = True
20            | Ask this question: {!@variables.questions[@variables.question_index]}

Tips

Pair a list with an index variable when you need to work through items one at a time.