From fc7f56e21badddfddd6c6cf235af172ba8863d1c Mon Sep 17 00:00:00 2001 From: Vikhyath Mondreti Date: Sat, 24 Jan 2026 11:36:47 -0800 Subject: [PATCH] improvement(docs): loop and parallel var reference syntax (#2975) --- apps/docs/content/docs/en/blocks/loop.mdx | 50 ++++++++++++++--- apps/docs/content/docs/en/blocks/parallel.mdx | 56 +++++++++++++++---- 2 files changed, 87 insertions(+), 19 deletions(-) diff --git a/apps/docs/content/docs/en/blocks/loop.mdx b/apps/docs/content/docs/en/blocks/loop.mdx index ecb1623f4..cbc88d808 100644 --- a/apps/docs/content/docs/en/blocks/loop.mdx +++ b/apps/docs/content/docs/en/blocks/loop.mdx @@ -124,11 +124,44 @@ Choose between four types of loops: 3. Drag other blocks inside the loop container 4. Connect the blocks as needed -### Accessing Results +### Referencing Loop Data -After a loop completes, you can access aggregated results: +There's an important distinction between referencing loop data from **inside** vs **outside** the loop: -- **``**: Array of results from all loop iterations + + + **Inside the loop**, use `` references to access the current iteration context: + + - **``**: Current iteration number (0-based) + - **``**: Current item being processed (forEach only) + - **``**: Full collection being iterated (forEach only) + + ``` + // Inside a Function block within the loop + const idx = ; // 0, 1, 2, ... + const item = ; // Current item + ``` + + + These references are only available for blocks **inside** the loop container. They give you access to the current iteration's context. + + + + **Outside the loop** (after it completes), reference the loop block by its name to access aggregated results: + + - **``**: Array of results from all iterations + + ``` + // If your loop block is named "Process Items" + const allResults = ; + // Returns: [result1, result2, result3, ...] + ``` + + + After the loop completes, use the loop's block name (not `loop.`) to access the collected results. The block name is normalized (lowercase, no spaces). + + + ## Example Use Cases @@ -184,28 +217,29 @@ Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++) + Available **inside** the loop only:
  • - loop.currentItem: Current item being processed + {""}: Current iteration number (0-based)
  • - loop.index: Current iteration number (0-based) + {""}: Current item being processed (forEach only)
  • - loop.items: Full collection (forEach loops) + {""}: Full collection (forEach only)
  • - loop.results: Array of all iteration results + {""}: Array of all iteration results (accessed via block name)
  • Structure: Results maintain iteration order
  • - Access: Available in blocks after the loop + Access: Available in blocks after the loop completes
diff --git a/apps/docs/content/docs/en/blocks/parallel.mdx b/apps/docs/content/docs/en/blocks/parallel.mdx index 8753fdfcd..be0c1e104 100644 --- a/apps/docs/content/docs/en/blocks/parallel.mdx +++ b/apps/docs/content/docs/en/blocks/parallel.mdx @@ -76,11 +76,44 @@ Choose between two types of parallel execution: 3. Drag a single block inside the parallel container 4. Connect the block as needed -### Accessing Results +### Referencing Parallel Data -After a parallel block completes, you can access aggregated results: +There's an important distinction between referencing parallel data from **inside** vs **outside** the parallel block: -- **``**: Array of results from all parallel instances + + + **Inside the parallel**, use `` references to access the current instance context: + + - **``**: Current instance number (0-based) + - **``**: Item for this instance (collection-based only) + - **``**: Full collection being distributed (collection-based only) + + ``` + // Inside a Function block within the parallel + const idx = ; // 0, 1, 2, ... + const item = ; // This instance's item + ``` + + + These references are only available for blocks **inside** the parallel container. They give you access to the current instance's context. + + + + **Outside the parallel** (after it completes), reference the parallel block by its name to access aggregated results: + + - **``**: Array of results from all instances + + ``` + // If your parallel block is named "Process Tasks" + const allResults = ; + // Returns: [result1, result2, result3, ...] + ``` + + + After the parallel completes, use the parallel's block name (not `parallel.`) to access the collected results. The block name is normalized (lowercase, no spaces). + + + ## Example Use Cases @@ -98,11 +131,11 @@ Parallel (["gpt-4o", "claude-3.7-sonnet", "gemini-2.5-pro"]) → Agent → Evalu ### Result Aggregation -Results from all parallel instances are automatically collected: +Results from all parallel instances are automatically collected and accessible via the block name: ```javascript -// In a Function block after the parallel -const allResults = input.parallel.results; +// In a Function block after a parallel named "Process Tasks" +const allResults = ; // Returns: [result1, result2, result3, ...] ``` @@ -158,25 +191,26 @@ Understanding when to use each: + Available **inside** the parallel only:
  • - parallel.currentItem: Item for this instance + {""}: Instance number (0-based)
  • - parallel.index: Instance number (0-based) + {""}: Item for this instance (collection-based only)
  • - parallel.items: Full collection (collection-based) + {""}: Full collection (collection-based only)
  • - parallel.results: Array of all instance results + {""}: Array of all instance results (accessed via block name)
  • - Access: Available in blocks after the parallel + Access: Available in blocks after the parallel completes