> 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/parallel.md).

# parallel

The Parallel block is a container block in Agent Forge that allows you to execute multiple instances of blocks concurrently.

{% hint style="info" %}
Parallel blocks are container nodes that execute their contents multiple times simultaneously, unlike loops which execute sequentially.
{% endhint %}

## Overview

The Parallel block enables you to:

1. **Distribute work**: Process multiple items concurrently
2. **Speed up execution**: Run independent operations simultaneously
3. **Handle bulk operations**: Process large datasets efficiently
4. **Aggregate results**: Collect outputs from all parallel executions

## Configuration Options

### Parallel Type

Choose between two types of parallel execution:

{% tabs %}
{% tab title="Count-based" %}
Execute a fixed number of parallel instances. Use this when you need to run the same operation multiple times concurrently.

```
Example: Run 5 parallel instances
- Instance 1 ┐
- Instance 2 ├─ All execute simultaneously
- Instance 3 │
- Instance 4 │
- Instance 5 ┘
```

{% endtab %}

{% tab title="Collection-based" %}
Distribute a collection across parallel instances. Each instance processes one item from the collection simultaneously.

```
Example: Process ["task1", "task2", "task3"] in parallel
- Instance 1: Process "task1" ┐
- Instance 2: Process "task2" ├─ All execute simultaneously
- Instance 3: Process "task3" ┘
```

{% endtab %}
{% endtabs %}

## How to Use Parallel Blocks

### Creating a Parallel Block

1. Drag a Parallel block from the toolbar onto your canvas
2. Configure the parallel type and parameters
3. Drag a single block inside the parallel container
4. Connect the block as needed

### Accessing Results

After a parallel block completes, you can access aggregated results:

* **`<parallel.results>`**: Array of results from all parallel instances

## Example Use Cases

### Batch API Processing

Scenario: Process multiple API calls simultaneously

1. Parallel block with collection of API endpoints
2. Inside parallel: API block calls each endpoint
3. After parallel: Process all responses together

### Multi-Model AI Processing

Scenario: Get responses from multiple AI models

1. Count-based parallel set to 3 instances
2. Inside parallel: Agent configured with different model per instance
3. After parallel: Compare and select best response

## Advanced Features

### Result Aggregation

Results from all parallel instances are automatically collected:

```javascript
// In a Function block after the parallel
const allResults = input.parallel.results;
// Returns: [result1, result2, result3, ...]
```

### Instance Isolation

Each parallel instance runs independently:

* Separate variable scopes
* No shared state between instances
* Failures in one instance don't affect others

### Limitations

{% hint style="warning" %}
Container blocks (Loops and Parallels) cannot be nested inside each other. This means:

* You cannot place a Loop block inside a Parallel block
* You cannot place another Parallel block inside a Parallel block
* You cannot place any container block inside another container block
  {% endhint %}

{% hint style="warning" %}
Parallel blocks can only contain a single block. You cannot have multiple blocks connected to each other inside a parallel - only the first block would execute in that case.
{% endhint %}

{% hint style="info" %}
While parallel execution is faster, be mindful of:

* API rate limits when making concurrent requests
* Memory usage with large datasets
* Maximum of 20 concurrent instances to prevent resource exhaustion
  {% endhint %}

## Parallel vs Loop

Understanding when to use each:

| Feature        | Parallel                          | Loop                 |
| -------------- | --------------------------------- | -------------------- |
| Execution      | Concurrent                        | Sequential           |
| Speed          | Faster for independent operations | Slower but ordered   |
| Order          | No guaranteed order               | Maintains order      |
| Use case       | Independent operations            | Dependent operations |
| Resource usage | Higher                            | Lower                |

## Inputs and Outputs

{% tabs %}
{% tab title="Configuration" %}

* **Parallel Type**: Choose between 'count' or 'collection'
* **Count**: Number of instances to run (count-based)
* **Collection**: Array or object to distribute (collection-based)
  {% endtab %}

{% tab title="Variables" %}

* **parallel.currentItem**: Item for this instance
* **parallel.index**: Instance number (0-based)
* **parallel.items**: Full collection (collection-based)
  {% endtab %}

{% tab title="Results" %}

* **parallel.results**: Array of all instance results
* **Access**: Available in blocks after the parallel
  {% endtab %}
  {% endtabs %}

## Best Practices

* **Independent operations only**: Ensure operations don't depend on each other
* **Handle rate limits**: Add delays or throttling for API-heavy workflows
* **Error handling**: Each instance should handle its own errors gracefully