> 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


---

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