Loops

The Loops page allows you to define iterative operations that your AI agent can perform. Loops are essential for processing collections of data (like lists of customers or orders), retrying operations, or executing a set of actions until a specific condition is met.

Prerequisites

Before you can manage Loops, ensure the following:

1. You are logged into the application.
2. Your user role has the necessary permissions (owner, admin, editor, or loops).
3. You have an Account and an Agent selected from the sidebar.

Page Overview

The page provides functionalities to:

• Add new loop configurations.
• Use an AI assistant to suggest loop designs.
• List existing loops associated with the selected agent.
• Edit, duplicate, or delete existing loops.
• Use a dedicated JSON editor for loop flows.

Creating a New Loop

To create a new loop, click on the "New Loop" expander.

Helper Buttons

• AI Suggest Configuration: Opens a dialog where you can describe your goal, and the AI will architect the loop structure, variables, and flow for you.
• Add Variable: Opens a dialog to create a new variable without leaving the page.
• Lookup Names: Opens a lookup dialog to find the exact names of existing Prompts, APIs, Variables, etc.

Configuration Fields

• Loop Name: A unique, descriptive name for the loop.
• Max Iterations: A safety limit on the total number of times the loop can run (0 for no limit).
• Loop Status: A toggle to enable or disable the loop.
• Loop Description: Optional notes about the loop's purpose.
• Agent(s): Select which agents are permitted to use this loop.
• Loop Type:
  • For: Executes a fixed number of times.
  • For Each: Iterates over a collection (list or dictionary).
  • While: Continues as long as a condition is true.
  • Do While: Executes at least once, then continues while a condition is true.
  • Until: Continues until a condition becomes true.

Iteration Settings (Conditional)

If For Each is selected: - Datasource Type: Choose list (array) or dict (object). - Datasource Variable: The variable containing the data to iterate over (e.g., {var["customer_list"]}). - Iteration Row Variable: The name of the variable that will hold the current item's data during each iteration (e.g., current_customer).

If While, Do While, or Until is selected: - Loop Condition: A logical expression that controls the loop (e.g., {var["retry_count"]} < 3).

Loop Flow (JSON)

The Loop Flow defines the sequence of actions executed in every iteration. It follows the standard PinionAI flow format.

{
    "0": {"api": "get_item_details"},
    "1": {"parser": "item_parser"},
    "2": {"script": "update_summary"}
}

Managing Existing Loops

Existing loops are listed in expanders. - Edit (:material/edit:): Modify the configuration. - Duplicate (:material/content_copy:): Create a copy of the loop to use as a template. - Delete (:material/delete:): Permanently remove the loop.

Configuration Examples

Example 1: Process a List of Orders (For Each)

Iterates through a list of orders and runs a parser on each.

• Loop Type: For Each
• Datasource Type: list
• Datasource Variable: order_queue
• Iteration Row Variable: current_order
• Loop Flow:

  {
      "0": {"parser": "order_data_extractor"},
      "1": {"api": "update_internal_inventory"}
  }
  

Example 2: Retry an API Call (While)

Retries a specific action until a success flag is set or max retries are reached.

• Loop Type: While
• Max Iterations: 3
• Loop Condition: {var["is_success"]} == false
• Loop Flow:

  {
      "0": {"api": "external_service_call"},
      "1": {"rule": "check_success_status"}
  }
  

Example 3: Accumulate Data (For)

Runs exactly 5 times to collect multiple pieces of information.

• Loop Type: For
• Max Iterations: 5
• Iteration Row Variable: step_index
• Loop Flow:

  {
      "0": {"input": "get_next_item_input"},
      "1": {"merger": "append_to_collection"}
  }