From e96358c10b49f55c1af728c0de9c0d3fee8557fc Mon Sep 17 00:00:00 2001
From: Stanislav Novosad <stas@skyvern.com>
Date: Fri, 30 Jan 2026 18:33:45 -0700
Subject: [PATCH] Workflow Copilot: clarify loop_over_parameter_key (#4592)

---
 .../skyvern/workflow_knowledge_base.txt       | 43 +++++++++++++++++--
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
index 4130a629..d104a3b4 100644
--- a/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
+++ b/skyvern/forge/prompts/skyvern/workflow_knowledge_base.txt
@@ -241,8 +241,8 @@ Structure:
 block_type: for_loop
 label: <unique_label>
 loop_blocks: []                          # Required: Blocks to run for each iteration
-loop_over_parameter_key: <param_key>     # Optional: Parameter key that resolves to a list
-loop_variable_reference: <jinja|path>    # Optional: Jinja2 or output path to resolve a list
+loop_over_parameter_key: <param_key>     # Optional: Use ONLY for workflow parameters defined in parameters section
+loop_variable_reference: <block_label>   # Optional: Use to reference output from a previous block
 complete_if_empty: false                 # Optional: Complete successfully when list is empty
 
 Important Notes:
@@ -250,7 +250,19 @@ Important Notes:
 - Loop blocks must use next_block_label to chain within the loop
 - Each iteration exposes {{ current_value }}, {{ current_item }}, and {{ current_index }}
 
-Example:
+CRITICAL DISTINCTION:
+* loop_over_parameter_key: ONLY for workflow parameters defined in the parameters section
+  - Use when looping over a static list or user-provided input
+  - Must reference a key from the workflow parameters list
+  - Example: loop_over_parameter_key: urls (where "urls" is in parameters)
+
+* loop_variable_reference: For referencing output from a PREVIOUS BLOCK
+  - Use when looping over data extracted or generated by a previous block
+  - Reference the block's label directly (e.g., "extract_rows")
+  - System automatically tries: block_label.extracted_information, block_label.results, etc.
+  - Example: loop_variable_reference: extract_rows (where "extract_rows" is a previous extraction block)
+
+Example 1 - Loop over workflow parameter:
 parameters:
   - parameter_type: workflow
     key: urls
@@ -262,13 +274,36 @@ blocks:
   - block_type: for_loop
     label: visit_urls
     next_block_label: null
-    loop_over_parameter_key: urls
+    loop_over_parameter_key: urls  # References the workflow parameter "urls"
     loop_blocks:
       - block_type: goto_url
         label: open_url
         next_block_label: null
         url: "{{ current_value }}"
 
+Example 2 - Loop over extraction block output:
+blocks:
+  - block_type: extraction
+    label: extract_products
+    next_block_label: process_each_product
+    data_extraction_goal: "Extract all products from the table"
+    data_schema:
+      type: array
+      items:
+        type: object
+        properties:
+          name: {type: string}
+          price: {type: number}
+  - block_type: for_loop
+    label: process_each_product
+    next_block_label: null
+    loop_variable_reference: extract_products  # References the extraction block's output
+    loop_blocks:
+      - block_type: navigation
+        label: add_to_cart
+        next_block_label: null
+        navigation_goal: "Add {{ current_value.name }} to cart"
+
 ** CONDITIONAL BLOCK (conditional) **
 
 Purpose: Branch to different blocks based on ordered conditions.