Skip to main content
A Loop Node runs a section of your flow once per element in an array, or a fixed number of times. It is the right primitive when a single task carries multiple items that each need the same processing, for example a batch of documents, a list of order line items, or a set of records returned by an upstream API call.

​
When to Use a Loop Node

Per-Item Processing

Run the same set of steps against each element of an array produced by an earlier node

Fixed-Count Passes

Repeat a section of the flow a known number of times, for example for retry passes

Fan-Out to Other Agents

Spawn one child task per item against another agent for parallel-style orchestration

Aggregating Results

Collect per-iteration outputs into a single array for a downstream node to summarise

​
Loop Modes

A Loop Node operates in one of two modes, either (fixed) Iteration count or Linked. Count Mode (fixed iterations):
  • The loop runs its body a fixed number of times, set as a static value.
  • No per-iteration data is passed to the body automatically.
  • Best for retry loops or any flow where the body does not depend on per-iteration data.
Linked Mode (array-driven):
  • The loop reads an array variable from an upstream node and runs its body once per element.
  • Iteration count is derived from the array length at runtime.
  • Each iteration exposes a single element of the array to the body via Linked variable fill.
  • Best for “do the same thing to every item” workflows.

​
Building a Loop

1

Add a Loop Node

Insert a Loop Node at the point in the flow where iteration should begin. The body nodes you add afterwards will run inside the loop.
2

Choose the Mode

Pick Count for fixed-iteration mode, or Items to loop through for Linked mode.For Count mode, enter the number of iterations as a static value.For Linked mode, use the picker to select an array variable emitted by an earlier node. The loop will iterate once per element in that array.
3

Build the Loop Body

Add the nodes that should run on each iteration directly inside the loop container. The body can be a single node or a chain of nodes.When the body has more than one node, wire them together with edges in the canvas the same way you would outside a loop. Studio adds the required edges automatically when you connect nodes via the UI.
4

Wire Per-Iteration Inputs (Linked Mode)

Inside the loop body, configure the first node’s input to use Linked fill against the loop’s array source. At runtime Beam injects one element per iteration into that input.The body sees one element at a time, not the full array. The shape of the element matches whatever shape the upstream node produced for each entry in the array.
5

Connect Downstream Nodes

After the loop, add the nodes that should consume the loop’s collected output. Downstream nodes link to the loop node itself, not to any single body node.

​
How the Loop Body Reads Data

In Linked mode, the body sees one element of the source array per iteration via the Linked variable it was configured with. That element is the only per-iteration value injected automatically. The iteration index is not exposed to the body as a directly readable variable. If your body logic needs to know which item it is processing, include that information inside each element of the source array (for example a position field) rather than expecting a free iteration-counter variable. The iteration index does appear in runtime telemetry on each body-node execution record as loopingNodeIterationCount, useful for inspecting individual iterations in task views, but it is not a value your body code can read at runtime.

​
Loop Output Shape

After the loop completes, post-loop nodes can read the loop’s collected output as an array. Each entry in the array represents one iteration and contains the output of the body’s inner nodes for that iteration. When the body has a single inner node, each entry contains that node’s output. When the body has multiple inner nodes, each entry contains the outputs of all body nodes for that iteration, keyed by their position in the body. Downstream nodes typically pass the loop output to a summariser node or write each entry to an external system in a follow-on step.

​
Troubleshooting

Cause: The Linked source is not actually wired, or the array variable id has not been saved on the loop node.Things to check:
  • The loop node’s Linked picker shows the source variable, not an empty field.
  • The upstream node that produces the array is published and emitting that variable in recent task runs.
  • The variable id stored on the loop matches a real output id on the source node.
When Linked mode is configured but the array source is missing, the loop falls back to a single-iteration pass and the body receives the source as-is (often as the whole array rather than one element).
Cause: The inner nodes are not edged together. Studio’s canvas enforces edges between sibling body nodes when you wire them via the UI, but body nodes added through other paths can end up unconnected.Things to check:
  • In the canvas, confirm there is an explicit edge from body node 1 to body node 2 (and so on).
  • The first body node has an edge from the loop, the last body node has an edge to the loop’s exit.
Without sibling edges, only the first body node runs each iteration and subsequent body nodes are silently skipped.
Cause: When a parent flow passes a structured object as the query field of a Create Agent Task request, the child task’s task_query.query arrives JSON-stringified.Solution: In the child agent’s first node, JSON.parse(input.task_query) (or the equivalent in your tool’s prompt) before reading nested fields. This is a normal artefact of the request body schema, not a Loop Node behaviour, but it shows up frequently in loop-driven fan-out and is worth knowing.
Cause: Studio’s link picker on a body-node input filters by static type compatibility. When the body input is typed object and the loop’s source is typed object[], the picker may not surface the array as a selectable source, even though Beam auto-unwraps one element per iteration at runtime.Things to check:
  • The body input’s declared type matches the per-element shape of the source array, not the array shape itself.
  • If the picker still does not show the source, configure the Linked variable via the Agent Graph API by setting fillType: linked and linkParamOutputId to the source array’s output id. Beam injects one element per iteration regardless of how the link was configured.

​
Next Steps

Custom Integrations

Build the Custom Integration used in the fan-out pattern

Multi-Agent Collaboration

Understand single-task agent-to-agent triggering

Variables & State

Configure Linked variable fill for per-iteration inputs

Create Agent Task API

Reference for the endpoint called by the fan-out integration