> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/blocks/loop.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.