loop

Create iterative workflows with loops that execute blocks repeatedly.

The Loop block is a container block in Agent Forge that allows you to execute a group of blocks repeatedly. Loops enable iterative processing in your workflows.

Loop blocks are container nodes that can hold other blocks inside them. The blocks inside a loop will execute multiple times based on your configuration.

Overview

The Loop block enables you to:

• Iterate over collections: Process arrays or objects one item at a time

• Repeat operations: Execute blocks a fixed number of times

Configuration Options

Loop Type

Choose between two types of loops:

For Loop

A numeric loop that executes a fixed number of times. Use this when you need to repeat an operation a specific number of times.

Example: Run 5 times
- Iteration 1
- Iteration 2
- Iteration 3
- Iteration 4
- Iteration 5

ForEach Loop

A collection-based loop that iterates over each item in an array or object. Use this when you need to process a collection of items.

Example: Process ["apple", "banana", "orange"]
- Iteration 1: Process "apple"
- Iteration 2: Process "banana"
- Iteration 3: Process "orange"

How to Use Loops

Creating a Loop

1. Drag a Loop block from the toolbar onto your canvas

2. Configure the loop type and parameters

3. Drag other blocks inside the loop container

4. Connect the blocks as needed

Accessing Results

After a loop completes, you can access aggregated results:

• <loop.results>: Array of results from all loop iterations

Example Use Cases

Processing API Results

Scenario: Process multiple customer records

1. API block fetches customer list

2. ForEach loop iterates over each customer

3. Inside loop: Agent analyzes customer data

4. Inside loop: Function stores analysis results

Iterative Content Generation

Scenario: Generate multiple variations

1. Set For loop to 5 iterations

2. Inside loop: Agent generates content variation

3. Inside loop: Evaluator scores the content

4. After loop: Function selects best variation

Advanced Features

Limitations

Container blocks (Loops and Parallels) cannot be nested inside each other. This means:

• You cannot place a Loop block inside another Loop block

• You cannot place a Parallel block inside a Loop block

• You cannot place any container block inside another container block

If you need multi-dimensional iteration, consider restructuring your workflow to use sequential loops or process data in stages.

Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead.

Inputs and Outputs

Configuration

• Loop Type: Choose between 'for' or 'forEach'

• Iterations: Number of times to execute (for loops)

• Collection: Array or object to iterate over (forEach loops)

Variables

• loop.currentItem: Current item being processed

• loop.index: Current iteration number (0-based)

• loop.items: Full collection (forEach loops)

Results

• loop.results: Array of all iteration results

• Structure: Results maintain iteration order

• Access: Available in blocks after the loop

Best Practices

• Set reasonable limits: Keep iteration counts reasonable to avoid long execution times

• Use ForEach for collections: When processing arrays or objects, use ForEach instead of For loops

• Handle errors gracefully: Consider adding error handling inside loops for robust workflows