II · Planning & Control FlowMature★★

Iteration Node

also known as Map-Over-Collection Node, For-Each Sub-Workflow, Bounded Workflow Loop

Express map-over-collection inside a visual workflow as an explicit Iteration node that runs a subgraph once per element of an input array, with bounded, deterministic, observable execution.

This pattern helps complete certain larger patterns —

  • used-byVisual Workflow Graph★★— Express agentic logic as a visual graph of typed nodes connected on a canvas with Start and End nodes so non-coding stakeholders can read and edit the flow.

Context

A team builds workflows on a visual canvas — Dify, Coze, n8n, or a similar low-code platform — where some part of the work has to be applied to every element of a list: every retrieved chunk, every search result, every uploaded file, every row in a spreadsheet. The team wants the iteration itself to be visible on the canvas alongside the rest of the flow, so failures and timings can be inspected per element rather than hidden inside a black box.

Problem

A model-driven loop (where the language model decides when to stop iterating) is non-deterministic and hard to bound by the data length. Collapsing the whole list into one large model call hides per-element failures, so when one of fifty PDFs fails the workflow either retries the whole batch or silently drops the bad one. Pushing the loop out into a code node or an external script loses the visual debug surface that justified using the canvas in the first place. None of these options gives a structural, data-bounded, inspectable iteration.

Forces

  • Iteration must be deterministic and bounded by the array length, not by an LLM stopping condition.
  • Per-element results need to be inspectable to find the one element that failed.
  • Sequential vs parallel execution within the Iteration changes latency and rate-limit behaviour.
  • Sub-workflow state must not leak across iterations.
  • Iteration depth should be capped — nested Iteration nodes can blow up step counts.

Example

A document-processing workflow receives a list of uploaded PDFs. The team needs to extract metadata from each, run a quality check, and emit a per-document summary. They wrap the extract-check-summarise sequence in an Iteration node bound to the input list. The node runs per element with a concurrency cap of four; when one PDF errors out, the iteration logs the failed index and continues. The output array preserves order so the consumer can join back to the original list.

Diagram

Solution

Therefore:

Define an Iteration node with an input array, an inner subgraph that runs once per element with the element bound to a parameter, and an output array of per-element results. The runtime may execute elements sequentially or in parallel up to a configured concurrency. Each iteration is logged with its index; failures surface per-element rather than collapsing the whole node. Pair with map-reduce (the algorithmic shape it instantiates), visual-workflow-graph (the surrounding canvas), and parallelization (when concurrency matters).

What this pattern forbids. The inner subgraph must operate per element with element-scoped state; it is not allowed to mutate variables outside its scope, and the number of iterations is bounded by the input array length rather than by a model decision.

The smaller patterns that complete this one —

  • usesMapReduce for Agents★— Split an oversize task into independent chunks, process each in parallel, then aggregate.

And the patterns that stand alongside it, or against it —

  • complementsVisual Workflow Graph★★— Express agentic logic as a visual graph of typed nodes connected on a canvas with Start and End nodes so non-coding stakeholders can read and edit the flow.
  • complementsParallelization★★— Run independent LLM calls concurrently and combine results.
  • complementsStep Budget★★— Cap the number of tool calls or loop iterations the agent is allowed within a single request.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance