FastGPTFastGPT

Loop

FastGPT Loop node overview and usage (applicable to version 4.15.0 and above)

Node Overview

The Loop Node allows you to repeatedly execute a sub-workflow. Whether you want to process a batch of data item by item (Array Loop), or iteratively optimize a task until it meets a specific standard (Conditional Loop), the Loop Node makes it easy.

Loop Node

Ideal for scenarios such as:

  • Summarizing paragraph chunks of a long article one by one (Array Loop)
  • Refining an AI draft and repeatedly revising it if the score is below 80, until it passes (Conditional Loop)
  • Calling external APIs sequentially in batches

Core Features & Loop Modes

The Loop Node provides two running modes.

1. Array Loop

  • How it works: Iterates through a provided array (e.g., article paragraphs), processing one element per iteration.
  • Data Injection: During each iteration, the Loop Start node automatically outputs Current Item and Current Index (0-based).

2. Conditional Loop

  • How it works: Runs repeatedly based on conditions instead of an array, until a Loop Break node is executed.
  • Requirement: Must contain at least one Loop Break node inside the loop container, otherwise saving or running the workflow will result in an error.
  • Data Injection: During each iteration, the Loop Start node automatically outputs Current Loop Count (1-based).

3. Error Handling & User Interaction

  • Preserving Prior Run Logs: If a loop fails at some point, the logs and results from previous successful iterations are kept. You can inspect the step-by-step trace in "Run Details" to easily spot what went wrong.
  • User Interaction Support: Supports nodes that require user input (like Form input) inside the loop. The loop will temporarily pause when reaching these nodes and automatically resume running from where it paused once the user completes the input.

Parameter Descriptions

Inputs

ParameterRequiredDefaultDescription
Loop TypeYesArray LoopChoose between Array Loop (array) or Conditional Loop (conditional).
ArrayYes-(Visible only in Array Loop mode) The list of data to process. Typically referenced from a preceding node's array output.
Loop BodyYes-The sub-workflow to execute inside the container, starting from the Loop Start node (can be exited via the Loop Break node).

Outputs

ParameterTypeDescription
Error TextstringThe error message if the loop terminates abnormally due to an error.
Custom OutputsAnyUsers can add custom outputs by typing a variable name in the node's Output area and binding it to an internal node's variable reference. When the node finishes running, it outputs the values from the final iteration (or upon termination).

Important Caveats & Best Practices

  1. No Nesting
    • You cannot place another Loop Node or Parallel Run node inside a Loop Node.
  2. Returns the Final Iteration Only
    • The custom outputs on the Loop Node only hold the values from the last iteration when the loop exits (it no longer aggregates all outputs into a single array).
    • How to aggregate results from all iterations?
      To collect data from every iteration into a list, declare an array global variable outside the Loop Node and update it inside the loop body based on the element type:
      1. String array: In the Variable Update node inside the loop body, select the array global variable, switch the value mode to Manual Input, choose Append, and type / in the input box to insert the current iteration's result (Variable Citation mode replaces the entire array with the referenced array).
      2. Object array: The append box for an object array accepts JSON text. To append a dynamic object output by an upstream node, add a Code Run node inside the loop body that combines the existing global array and the current object into a new array, then update the global array variable in the Variable Update node using Variable Citation.
  3. Variable and External Output Writeback
    • After each successful iteration, global variable changes made inside the loop body are written back to the main flow. If a Variable Update node changes an output on a node outside the loop container, that output is also written back after that iteration succeeds.
    • Failed iterations do not commit variable or external output changes from that iteration. When an interactive node pauses execution, the completed changes before the pause are kept as a resumable checkpoint so the loop can continue after the user submits input.
  4. Prevent Infinite Loops
    • For Conditional Loops, ensure that a Loop Break node is reachable under certain conditions.
    • The system enforces a maximum iteration limit (default 100). The loop will automatically terminate and throw an error if this limit is reached.

Deployment Settings

For self-hosted developers or operators, you can adjust the execution limits of the Loop Node via the following environment variable:

Environment VariableDefaultDescription
WORKFLOW_MAX_LOOP_TIMES100The maximum length of input arrays and the maximum iteration limit for Conditional Loops (shared by Loop Node, Parallel Run, and the deprecated Batch Run).

Example Scenario: Array Loop Validation and Conditional Loop Extension

Validate the data flow with an array loop before extending it to AI rewriting. The verified configuration below uses a global array captureItems = ["alpha", "beta"], replies with each item, and records the final item.

Array loop replying to each item and returning lastItem

Implementation Steps

  1. Add an array variable captureItems in system configuration and enter ["alpha", "beta"].
  2. Select Array Loop and reference captureItems as the input array.
  3. Connect Loop Start to Assigned Reply inside the loop. Reference the current item as the reply content.
  4. Add a custom output lastItem and reference the current item from Loop Start. Its final value is beta.
  5. To extend this to AI rewriting, select Conditional Loop and connect rewriting, scoring, and condition nodes inside the body. The passing branch outputs the text and reaches Loop Break; the other branch continues the next iteration. Store text and scores needed across iterations in variables.

Execution Flow & Details

This screenshot records two successful iterations of the array validation example. Expand the loop in Complete Response to inspect the iteration count, history, and per-iteration custom outputs:

Two array-loop iterations and the final output

  1. The first current item is alpha; Assigned Reply outputs alpha.
  2. The second current item is beta; Assigned Reply outputs beta.
  3. The loop finishes with lastItem = "beta". AI scoring in a conditional loop depends on the model and prompt; test its passing and termination paths separately.
Edit on GitHub

Last updated