Parallel Execution

Run multiple agents simultaneously for faster results.

Difficulty: Intermediate Time: 15 minutes

What You'll Build

A flow that:

• Splits into multiple parallel branches
• Runs agents simultaneously
• Merges results from all branches

TBD: Replace with screenshot of parallel flow

Prerequisites

• Completed Simple Sequential Flow
• Understanding of flow basics

Why Parallel Execution?

Sequential (slow):

A → B → C → D
Time: 4 units

Parallel (fast):

    ┌─ B ─┐
A ──┼─ C ─┼── D
    └─ D ─┘
Time: 2 units

When tasks are independent, run them simultaneously.

How It Works

Parallel execution uses two node types:

• Parallel Node — Splits execution into concurrent branches (branches: string[] — list of node IDs to start)
• Merge Node — Joins branches back together with a mergeStrategy

Step 1: Identify Independent Tasks

Tasks can run in parallel if they:

• Don't depend on each other's output
• Can execute simultaneously
• Don't have shared state conflicts

Good for parallel:

• Multiple code reviews (security, style, performance)
• Searching multiple sources
• Generating multiple variations

Not good for parallel:

• Sequential transformations
• Tasks that need previous output
• Order-dependent operations

Step 2: Create a Parallel Flow

Example: Multi-Aspect Code Review

1. Go to Flows → + New Flow
2. Name it "Comprehensive Code Review"

Flow Structure

              ┌── Security Review ──┐
              │                     │
Trigger ── Parallel ── Performance ─┼── Merge ── Summary ── End
              │                     │
              └── Style Review ─────┘

Agent Definitions

Security Reviewer:

name: Security Reviewer
model: claude-sonnet-5-0
thinkingLevel: think
systemPrompt: |
  Focus exclusively on security issues:
  - Injection vulnerabilities
  - Authentication flaws
  - Data exposure risks
  - Insecure dependencies

Performance Reviewer:

name: Performance Reviewer
model: claude-sonnet-5-0
thinkingLevel: think
systemPrompt: |
  Focus exclusively on performance:
  - Algorithm efficiency
  - Memory usage
  - Database queries
  - Caching opportunities

Style Reviewer:

name: Style Reviewer
model: claude-haiku-4-5-20251001
systemPrompt: |
  Focus exclusively on code style:
  - Naming conventions
  - Code organization
  - Documentation
  - Best practices

Step 3: Configure the Flow

Trigger Node

triggerType: manual
triggerConfig:
  inputSchema:
    type: object
    properties:
      code:
        type: string
        description: Code to review
      context:
        type: string
        description: Additional context

Parallel Node

The Parallel node lists which nodes to execute concurrently:

branches:
  - "securityReview"
  - "performanceReview"
  - "styleReview"

Agent Nodes

Each agent receives the same input from the trigger:

# securityReview node
agentId: security-reviewer
inputMapping:
  code: "trigger.input.code"
  context: "trigger.input.context"
outputMapping: {}

# performanceReview node
agentId: performance-reviewer
inputMapping:
  code: "trigger.input.code"
  context: "trigger.input.context"
outputMapping: {}

# styleReview node
agentId: style-reviewer
inputMapping:
  code: "trigger.input.code"
  context: "trigger.input.context"
outputMapping: {}

Merge Node

The Merge node waits for branches to complete:

mergeStrategy: "all"
sourceNodes:
  - "securityReview"
  - "performanceReview"
  - "styleReview"

Summary Agent

After the merge, a final agent compiles results:

# summary node
agentId: review-summarizer
inputMapping:
  securityReview: "nodes.securityReview.output"
  performanceReview: "nodes.performanceReview.output"
  styleReview: "nodes.styleReview.output"
outputMapping: {}

Merge Strategies

Strategy	Behavior
all	Wait for ALL branches to complete before continuing
any	Continue when ANY branch completes (first to finish)
first	Continue with the first branch result only

Wait for All

mergeStrategy: "all"
sourceNodes: ["branchA", "branchB", "branchC"]

Best for: Aggregating results from independent analyses.

Wait for Any

mergeStrategy: "any"
sourceNodes: ["branchA", "branchB"]

Best for: Redundant checks where any positive result is sufficient.

First Only

mergeStrategy: "first"
sourceNodes: ["branchA", "branchB"]

Best for: Racing multiple approaches and using the fastest result.

Accessing Parallel Results

After the merge, access each branch's output through the flow context:

# In the summary agent's inputMapping
inputMapping:
  security: "nodes.securityReview.output"
  performance: "nodes.performanceReview.output"
  style: "nodes.styleReview.output"

Example: Research from Multiple Sources

                ┌── Academic Search ──┐
                │                     │
Query ── Parallel ── News Search ─────┼── Merge ── Synthesize ── End
                │                     │
                └── Technical Blogs ──┘

Academic Search Agent:

name: Academic Searcher
allowedTools:
  - tool: WebSearch
    allowed: true
mcpServers:
  - sciorex-research
systemPrompt: |
  Search for academic papers and research.
  Focus on peer-reviewed sources.
  Use sciorex_search_papers when available.

News Search Agent:

name: News Searcher
allowedTools:
  - tool: WebSearch
    allowed: true
systemPrompt: |
  Search for recent news articles.
  Focus on reputable publications.

Blog Search Agent:

name: Blog Searcher
allowedTools:
  - tool: WebSearch
    allowed: true
systemPrompt: |
  Search technical blogs and forums.
  Focus on practical experiences.

Error Handling in Parallel

Check Individual Branch Results

Use condition nodes after the merge to check for failures:

# Condition node after merge
conditions:
  - path: "nodes.securityReview.output"
    operator: "eq"
    value: null
targetNodeId: "handle-security-failure"
defaultTargetNodeId: "continue-normally"

Error Recovery

When a branch fails, the flow pauses at that node. Recovery options:

• Retry — Re-execute the failed branch
• Skip — Provide mock output and continue
• Stop — Halt the entire flow

Performance Tips

Right-Size Models

Use appropriate models per task:

Task Complexity	Model
Simple classification	Haiku
Standard analysis	Sonnet
Complex reasoning	Opus

Worktree Isolation

For branches that modify code, use worktree mode to isolate changes:

# Agent node with worktree
agentId: security-fixer
worktreeMode: "new"
worktreeConfig:
  label: "security-fixes"
  baseBranch: "main"
  autoMergeOnSuccess: true
  cleanupOnComplete: true

Each branch gets its own git worktree, preventing conflicts between parallel code modifications.

Complex Parallel Patterns

Fan-Out / Fan-In

         ┌── Process 1 ──┐
         │               │
Parallel ┼── Process 2 ──┼── Merge
         │               │
         └── Process 3 ──┘

Parallel with Post-Conditions

Parallel → Merge → Condition → [all passed] → End (success)
                           └──→ [failures] → End (failure)

Nested Parallel

         ┌── Branch A ── Parallel A ── Merge A ──┐
         │                                        │
Parallel ┤                                        ├── Final Merge
         │                                        │
         └── Branch B ── Parallel B ── Merge B ──┘

Tips

• Identify independence: Only parallelize truly independent tasks
• Balance load: Don't create too many parallel branches
• Handle failures: Use error recovery or post-merge conditions
• Monitor timing: Track which branches are slow via debug mode
• Test thoroughly: Parallel flows can have subtle timing issues

Related

• Simple Sequential Flow
• Conditional Branching
• Chaining Multiple Agents
• Flows Overview