> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gaife.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loop Task

> This page gives you an overview of the Loop Task in Agent Builder

## Overview

The Loop node allows you to repeat a sequence of tasks multiple times in your workflow. You can loop either a fixed
number of times or iterate through a list of items. This is perfect for processing multiple files, handling user data in
batches, or any repetitive operations.

## When to Use Loop Nodes

* Process multiple files or documents
* Handle lists of users, orders, or records
* Retry operations multiple times
* Generate multiple variations of content
* Batch process large datasets

## Adding a Loop Node

1. Drag the Loop node from the node palette onto your workflow canvas
2. Connect it to your previous task
3. Configure the loop settings in the properties panel

## Required Configuration

### Basic Settings

#### Node Name

* **Field**: Node Name
* **Required**: Yes
* **Description**: Give your loop a descriptive name like "Process User Records" or "Retry API Calls"

#### Iteration Type

* **Field**: Iteration Type
* **Required**: Yes
* **Options**:
  * **Count**: Loop a specific number of times
  * **List**: Loop through each item in an array

#### Iteration Parameter

* **Field**: Iteration Parameter
* **Required**: Yes
* **Description**: This controls how many times the loop runs or what list to iterate through

## Setting Up Iteration Parameters

### For Count Loops

When using **Count** iteration type, the parameter must be a **number**:

#### Manual Entry

```
5
```

#### Reference from Previous Task

```
setup_task.output.batch_count
get_config.input.retry_attempts
```

### For List Loops

When using **List** iteration type, the parameter must be an **array**:

#### Basic Array Reference

```
data_fetch.output.users
file_processor.output.documents
api_call.input.items_to_process
```

#### Object with Array Property

```
database_query.output.results.records
api_response.output.data.customers
user_data.input.profile.addresses
```

#### Nested Object Properties

```
complex_data.output.response.users.active_users
report_data.output.analytics.metrics.daily_stats
```

### Using the Parameter Picker

Instead of typing manually, you can use the parameter picker:

1. Click the **"Select Parameter"** button
2. Choose the source task from the dropdown
3. Select whether you want an **input** or **output** parameter
4. Pick the specific field name
5. For objects, drill down to the array property you need

<Warning>
  The selected parameter must result in either a **number** (for count loops) or
  an **array** (for list loops). If the parameter type doesn't match, the loop
  won't work correctly.
</Warning>

## Loop Flow Configuration

### Loop Start Block

* **Field**: Loop Start Block
* **Required**: Yes
* **Description**: The first task that runs inside each loop iteration
* **UI**: Dropdown showing available tasks in your workflow

### Loop End Block(s)

* **Field**: Loop End Blocks
* **Required**: Yes
* **Description**: The task(s) that can end each loop iteration
* **UI**: Multi-select dropdown for multiple possible end points

### Exit Block

* **Field**: Exit Block
* **Required**: Yes
* **Description**: The task that runs after all loop iterations complete
* **UI**: Dropdown showing available tasks

## Loop Structure Visual

```mermaid theme={null}
graph TD
    A[Previous Task] --> B[Loop Node]
    B --> C[Loop Start Block]
    C --> D[Task 1]
    D --> E[Task 2]
    E --> F[Loop End Block]
    F --> G{More Items?}
    G -->|Yes| C
    G -->|No| H[Exit Block]
    H --> I[Next Task]
```

## Practical Examples

### Example 1: Processing User List

**Scenario**: You have a list of users and want to send each one a personalized email.

**Configuration**:

* **Iteration Type**: List
* **Iteration Parameter**: `user_fetch.output.users`
* **Loop Start Block**: `generate_email`
* **Loop End Block**: `send_email`
* **Exit Block**: `send_summary_report`

### Example 2: Retry Mechanism

**Scenario**: Try an API call up to 3 times if it fails.

**Configuration**:

* **Iteration Type**: Count
* **Iteration Parameter**: `3`
* **Loop Start Block**: `make_api_call`
* **Loop End Block**: `check_api_success`
* **Exit Block**: `handle_final_result`

### Example 3: Batch File Processing

**Scenario**: Process files in batches based on system capacity.

**Configuration**:

* **Iteration Type**: Count
* **Iteration Parameter**: `config.output.number_of_batches`
* **Loop Start Block**: `fetch_file_batch`
* **Loop End Block**: `process_batch`
* **Exit Block**: `consolidate_results`

## Advanced Parameter Examples

### Simple Array from API Response

```
api_call.output.data
```

### Nested Array in Complex Object

```
database_query.output.results.users.active_list
```

### Configuration-Based Count

```
system_config.input.processing_parameters.batch_size
```

### Calculated Count from Previous Task

```
data_analyzer.output.metrics.recommended_iterations
```

## Common Validation Errors

### "Parameter must be an array"

* **Problem**: You selected List iteration but the parameter is not an array
* **Solution**: Choose a parameter that contains a list of items, or switch to Count iteration

### "Parameter must be a number"

* **Problem**: You selected Count iteration but the parameter is not a number
* **Solution**: Choose a numeric parameter, or switch to List iteration

### "Loop start block not found"

* **Problem**: The selected start block doesn't exist in your workflow
* **Solution**: Create the task first, then select it as the start block

### "Circular dependency detected"

* **Problem**: Your loop configuration creates a circular reference
* **Solution**: Ensure the loop exit block connects to a task outside the loop

## Loop Variable Access

During each iteration, your tasks can access loop information through the special `__loop__` variable:

**Available Properties**:

* `__loop__.current_iteration` - Current iteration number (starts at 0)
* `__loop__.total_iterations` - Total number of iterations
* `__loop__.current_item` - Current item being processed (List loops only)
* `__loop__.is_first` - True if this is the first iteration
* `__loop__.is_last` - True if this is the last iteration

## Best Practices

### ✅ Do's

* **Use descriptive names** for your loop nodes
* **Test with small datasets** before processing large lists
* **Set reasonable limits** for count-based loops
* **Handle empty arrays** gracefully in your workflow
* **Use the parameter picker** instead of typing parameter paths manually

### ❌ Don'ts

* **Don't create infinite loops** - always ensure your count is reasonable
* **Don't forget error handling** - plan for what happens if an iteration fails
* **Don't use loops for single items** - use conditional logic instead
* **Don't nest loops too deeply** - consider breaking complex logic into separate workflows

## Troubleshooting

### Loop Doesn't Start

1. Check that your iteration parameter actually contains data
2. Verify the parameter path is correct using the parameter picker
3. Ensure the previous task completed successfully

### Loop Runs Forever

1. Verify you're using Count iteration with a specific number
2. Check that List iteration has a finite array
3. Ensure loop end blocks are properly connected

### Tasks Not Found

1. Make sure all referenced tasks exist in your workflow
2. Use the dropdowns instead of typing task names manually
3. Check that task names haven't changed after configuration

## Related Features

* **[Conditional Nodes](./conditional-nodes)** - Add logic to control loop behavior
* **[Variables](./variables)** - Store and reuse values across loop iterations
* **[Error Handling](./error-handling)** - Manage failures within loops
* **[Workflow Testing](./testing)** - Test your loops with sample data