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

# Parallel node

> Run multiple workflow branches simultaneously for maximum throughput and efficiency

## Purpose

The **Parallel node** executes multiple branches simultaneously. Each branch runs independently and in parallel, and the workflow continues only after all branches complete. Use Parallel nodes to maximize throughput when processing independent tasks.

Parallel execution is essential for AI workflows where multiple agents need to analyze the same input from different perspectives, or when you need to process multiple items simultaneously.

## How parallel execution works

When execution reaches a Parallel node:

<Steps>
  <Step title="Branch initialization">
    All branches within the Parallel node are initialized simultaneously. Each branch receives the same input data from the variable store.
  </Step>

  <Step title="Concurrent execution">
    Each branch executes its activities independently. Branches don't wait for each other — they run at the same time.
  </Step>

  <Step title="No cross-branch communication">
    Branches cannot communicate with each other during execution. Each branch operates on its own copy of the variable store.
  </Step>

  <Step title="Wait for completion">
    The workflow waits for ALL branches to complete before proceeding to the next node after the Parallel node.
  </Step>

  <Step title="Output collection">
    After all branches finish, their outputs are collected and merged into the variable store. Downstream nodes can access results from all branches.
  </Step>
</Steps>

<Info>
  Parallel nodes leverage Temporal's concurrent execution capabilities. Each branch runs as a separate activity, enabling true parallelism across multiple workers.
</Info>

## Configuration

Configure a Parallel node to define branches and how they execute.

### Add branches

Create two or more branches within the Parallel node. Each branch is a sequence of activities:

* **Branch 1:** Activity A → Activity B → Activity C
* **Branch 2:** Activity D → Activity E
* **Branch 3:** Activity F → Activity G → Activity H

Each branch can contain any combination of node types: Agent nodes, Tool nodes, Condition nodes, even nested Parallel nodes.

### Branch naming

Give each branch a descriptive name. Branch names become keys in the variable store for accessing outputs:

* `technical_evaluation` — Branch that evaluates technical requirements
* `vendor_assessment` — Branch that assesses vendor capabilities
* `financial_analysis` — Branch that analyzes financial terms

**Accessing branch outputs:**

```json theme={null}
{
  "technical_score": "{{technical_evaluation.agent.score}}",
  "vendor_score": "{{vendor_assessment.agent.score}}",
  "financial_score": "{{financial_analysis.agent.score}}"
}
```

### Input distribution

Configure how input data is distributed to branches:

* **Same input for all branches** — Each branch receives identical input (most common)
* **Branch-specific input** — Each branch receives different data

**Example: Same input distribution**

All branches receive the same document for analysis:

```json theme={null}
{
  "document": "{{input.document_url}}",
  "context": "{{input.context}}"
}
```

**Example: Branch-specific input**

Each branch receives a different document:

```json theme={null}
{
  "branch_1_input": {
    "document": "{{input.emirates_id_url}}"
  },
  "branch_2_input": {
    "document": "{{input.trade_license_url}}"
  },
  "branch_3_input": {
    "document": "{{input.passport_url}}"
  }
}
```

### Merge strategies

Configure how branch results are combined after completion:

| Strategy                        | Behavior                                                 |
| ------------------------------- | -------------------------------------------------------- |
| **`combine_results`** (default) | Collect all branch outputs into a combined result object |
| **`first_success`**             | Use the output from the first branch that succeeds       |
| **`all_required`**              | All branches must succeed; fail if any branch fails      |

### LLM-based output combining

For advanced use cases, configure an LLM `combine` step that synthesizes branch outputs into a unified result:

```json theme={null}
{
  "combine": {
    "input_fields": {
      "branch_outputs": {"source": "_branches"},
      "original_input": {"source": "input.document"}
    },
    "output_schema": {
      "summary": {"type": "string"},
      "overall_score": {"type": "number"}
    },
    "module_type": "chain_of_thought"
  }
}
```

The combine step receives all branch outputs and uses DSPy to produce a structured synthesis. This is useful when you need an LLM to reason across multiple branch results (e.g., synthesizing scores from multiple evaluators).

### Valid branch types

Each branch in a Parallel node must be one of these activity types:

* **Agent** — Execute an AI agent
* **Respond** — Generate a response from a template or schema
* **Router** — LLM-based routing decision
* **Tool** — Execute an MCP tool
* **Use Case** — Execute a child use case

### Execution settings

Configure how the Parallel node behaves:

* **Timeout** — Maximum wait time for all branches to complete
* **Template variable resolution** — Branch configs can use `{{input.*}}` and `{{variables.*}}` patterns that are resolved before execution

## Use cases

Parallel nodes enable powerful patterns for AI orchestration.

### Multi-perspective analysis

Analyze the same input from multiple perspectives simultaneously.

**Example: RFP (Request for Proposal) analysis**

<CardGroup cols={2}>
  <Card title="Technical evaluation" icon="code">
    **Branch 1**

    * Technical requirements agent
    * Evaluate solution architecture
    * Assess technical feasibility
    * Score: 0-100
  </Card>

  <Card title="Vendor assessment" icon="building">
    **Branch 2**

    * Vendor research agent
    * Check vendor reputation
    * Review past performance
    * Score: 0-100
  </Card>

  <Card title="Commercial analysis" icon="chart-line">
    **Branch 3**

    * Financial analysis agent
    * Evaluate pricing
    * Assess commercial terms
    * Score: 0-100
  </Card>

  <Card title="Compliance review" icon="shield-check">
    **Branch 4**

    * Compliance agent
    * Check regulatory requirements
    * Assess risks
    * Score: 0-100
  </Card>

  <Card title="Timeline analysis" icon="clock">
    **Branch 5**

    * Timeline assessment agent
    * Evaluate delivery schedule
    * Check resource availability
    * Score: 0-100
  </Card>
</CardGroup>

**After parallel completion:**

A synthesis agent combines all evaluations:

```json theme={null}
{
  "technical_score": 85,
  "vendor_score": 90,
  "commercial_score": 75,
  "compliance_score": 95,
  "timeline_score": 80,
  "overall_recommendation": "Proceed with vendor",
  "key_considerations": [...]
}
```

**Execution time comparison:**

* **Sequential:** \~5 minutes (5 agents × 1 minute each)
* **Parallel:** \~1 minute (all agents run simultaneously)

### Document verification (KYB/KYC)

Process multiple documents simultaneously for Know Your Business or Know Your Customer workflows.

**Example: Business verification**

<Steps>
  <Step title="Parallel document processing">
    Three branches process documents simultaneously:

    **Branch 1: Emirates ID verification**

    * Vision model agent extracts Emirates ID data
    * Validates document authenticity
    * Extracts: name, ID number, expiry date

    **Branch 2: Trade license verification**

    * Vision model agent extracts trade license data
    * Validates license status
    * Extracts: company name, license number, activities

    **Branch 3: Passport verification**

    * Vision model agent extracts passport data
    * Validates document authenticity
    * Extracts: name, passport number, nationality
  </Step>

  <Step title="Data cross-validation">
    After parallel completion, a validation agent checks consistency:

    * Do names match across documents?
    * Are all documents valid and not expired?
    * Does the trade license owner match the passport holder?
  </Step>

  <Step title="Decision">
    Based on validation results:

    * ✓ All valid and consistent → Auto-approve
    * ⚠ Minor discrepancies → Human review
    * ✗ Major issues → Auto-reject
  </Step>
</Steps>

**Execution time comparison:**

* **Sequential:** \~3 minutes (3 documents × 1 minute each)
* **Parallel:** \~1 minute (all documents processed simultaneously)

### Multi-language processing

Process the same content in multiple languages simultaneously.

**Example: Global announcement distribution**

<CardGroup cols={2}>
  <Card title="English version" icon="flag-usa">
    **Branch 1**

    * Translation agent (if needed)
    * Content formatting agent
    * Cultural adaptation agent
  </Card>

  <Card title="Arabic version" icon="flag">
    **Branch 2**

    * Translation agent
    * RTL formatting agent
    * Cultural adaptation agent
  </Card>

  <Card title="French version" icon="flag">
    **Branch 3**

    * Translation agent
    * Content formatting agent
    * Cultural adaptation agent
  </Card>

  <Card title="Spanish version" icon="flag">
    **Branch 4**

    * Translation agent
    * Content formatting agent
    * Cultural adaptation agent
  </Card>
</CardGroup>

After all branches complete, a final step distributes the localized content to the appropriate channels.

### Competitive intelligence gathering

Research multiple competitors simultaneously.

**Example: Market analysis**

Each branch researches one competitor:

* **Branch 1:** Competitor A analysis
* **Branch 2:** Competitor B analysis
* **Branch 3:** Competitor C analysis
* **Branch 4:** Competitor D analysis

Each branch:

1. Research agent gathers public information
2. Analysis agent evaluates strengths/weaknesses
3. Pricing agent extracts pricing information

After all complete, a synthesis agent creates a competitive landscape report.

## Output collection and merging

After all branches complete, their outputs are merged into the variable store. Understanding how to access this merged data is crucial.

### Branch output structure

Each branch's output is stored under its branch name:

```json theme={null}
{
  "parallel_node_name": {
    "branch_1_name": {
      "activity_1": { "output": {...} },
      "activity_2": { "output": {...} }
    },
    "branch_2_name": {
      "activity_1": { "output": {...} }
    },
    "branch_3_name": {
      "activity_1": { "output": {...} },
      "activity_2": { "output": {...} },
      "activity_3": { "output": {...} }
    }
  }
}
```

### Accessing parallel outputs

Reference branch outputs in downstream nodes:

**Specific branch output:**

```
{{parallel_node.technical_evaluation.agent.score}}
```

**Multiple branch outputs in an agent:**

```json theme={null}
{
  "analysis_context": {
    "technical_score": "{{parallel_node.technical_evaluation.agent.score}}",
    "vendor_score": "{{parallel_node.vendor_assessment.agent.score}}",
    "financial_score": "{{parallel_node.financial_analysis.agent.score}}"
  }
}
```

**All branch outputs for synthesis:**

Pass all branch results to a synthesis agent:

```json theme={null}
{
  "evaluations": "{{parallel_node}}"
}
```

The synthesis agent receives the complete parallel execution results and can combine them intelligently.

## Best practices

<AccordionGroup>
  <Accordion title="Use parallel for independent tasks">
    Only use Parallel nodes when branches are truly independent. If branch B needs results from branch A, don't run them in parallel — run them sequentially.
  </Accordion>

  <Accordion title="Balance branch complexity">
    Try to design branches with similar execution times. If one branch takes 10 seconds and another takes 5 minutes, the workflow waits for the slowest branch.
  </Accordion>

  <Accordion title="Name branches descriptively">
    Branch names appear in the variable store and in execution logs. Use clear names that indicate what each branch does.
  </Accordion>

  <Accordion title="Add synthesis step after parallel">
    After parallel execution, add a synthesis step that combines results. Don't try to merge results manually — let an agent do it intelligently.
  </Accordion>

  <Accordion title="Handle partial failures">
    Use Condition nodes after the Parallel node to check if all branches succeeded. Route to error handling if any branch failed.
  </Accordion>

  <Accordion title="Set appropriate timeouts">
    Set timeouts at the Parallel node level, not just individual activities. This prevents indefinite waits if a branch gets stuck.
  </Accordion>

  <Accordion title="Consider resource limits">
    Each branch consumes compute resources. Running 20 branches simultaneously may hit resource limits. Monitor and scale appropriately.
  </Accordion>
</AccordionGroup>

<Warning>
  Branches in a Parallel node cannot communicate with each other during execution. If you need inter-branch coordination, collect outputs after the Parallel node and process them in a subsequent step.
</Warning>

## Advanced patterns

### Nested parallel execution

You can nest Parallel nodes within branches for complex orchestration:

```
Parallel Node 1
├─ Branch A: Agent 1 → Agent 2
├─ Branch B:
│  └─ Parallel Node 2
│     ├─ Branch B1: Agent 3
│     ├─ Branch B2: Agent 4
│     └─ Branch B3: Agent 5
└─ Branch C: Agent 6
```

This enables hierarchical parallelism: multiple perspectives at the top level, with sub-perspectives within each.

### Dynamic branch creation

Use a ForEach node before a Parallel node to dynamically create parallel tasks based on input data:

```
ForEach (documents)
  → Create parallel branch for each document
  → Process all documents in parallel
```

This pattern is useful when you don't know how many items to process until runtime.

### Conditional parallel execution

Use Condition nodes within parallel branches to create adaptive workflows:

```
Parallel Node
├─ Branch A: Agent → Condition → [Path 1 or Path 2]
├─ Branch B: Agent → Condition → [Path 1 or Path 2]
└─ Branch C: Agent → Condition → [Path 1 or Path 2]
```

Each branch adapts independently based on its analysis results.

## Performance considerations

### Execution time

Parallel execution time = max(branch execution times) + overhead

**Example:**

* Branch A: 30 seconds
* Branch B: 90 seconds
* Branch C: 45 seconds
* **Total parallel time:** \~90 seconds (+ small overhead)

Compare to sequential execution:

* **Total sequential time:** 30 + 90 + 45 = 165 seconds

**Speedup:** 1.8x faster with parallel execution.

### Resource utilization

Each branch consumes resources:

* **Compute:** Each agent execution uses CPU/GPU
* **Memory:** Each branch maintains its own state
* **API costs:** Each LLM call incurs API costs

Monitor resource usage and scale your infrastructure appropriately.

<Tip>
  For maximum throughput with large-scale parallel execution, ensure your MagOneAI deployment has sufficient Temporal workers. Each worker can execute one activity at a time.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Agent node" icon="robot" href="/workflows/agent-node">
    Learn how to configure agents within parallel branches
  </Card>

  <Card title="Condition node" icon="code-branch" href="/workflows/condition-node">
    Route based on parallel execution results
  </Card>

  <Card title="ForEach node" icon="repeat" href="/workflows/foreach-node">
    Process collections before parallel execution
  </Card>

  <Card title="Memory system" icon="database" href="/workflows/memory">
    Understand how parallel outputs merge in the variable store
  </Card>
</CardGroup>