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 regular variable. To reference an item in your list, use [<item_numer>]. List indexes start at 0, so the first item in your list is @variables.YourVariable[0].

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 in the variables block. Specify the list type in brackets []. You can initialize an empty list with =[], or set default values.

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".

You can use a variable to reference a list item.

You can use a list item in conditional expressions.

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.

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.

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