> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/blocks/loop.md).

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

{% hint style="info" %}
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.
{% endhint %}

## 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:

{% tabs %}
{% tab title="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
```

{% endtab %}

{% tab title="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"
```

{% endtab %}
{% endtabs %}

## 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

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead.
{% endhint %}

## Inputs and Outputs

{% tabs %}
{% tab title="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)
  {% endtab %}

{% tab title="Variables" %}

* **`loop.currentItem`**: Current item being processed
* **`loop.index`**: Current iteration number (0-based)
* **`loop.items`**: Full collection (forEach loops)
  {% endtab %}

{% tab title="Results" %}

* **`loop.results`**: Array of all iteration results
* **Structure**: Results maintain iteration order
* **Access**: Available in blocks after the loop
  {% endtab %}
  {% endtabs %}

## 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