> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-loops.md).

# Agentic Workflow Loops

The Loop step repeats a sequence of steps for every item in an array of Records, strings, or UUIDs, with nesting limits, Exit Loop, and Debug behavior.

{% hint style="success" %}
Agentic Workflow builders use a Loop step to repeat a sequence of steps across every item in an array, including nested loops and the restrictions that apply while a loop is running.
{% endhint %}

## Overview

A Loop step repeats a sequence of steps once for every item in an array variable, instead of requiring a separate branch or workflow for each <code class="expression">space.vars.entity</code>. Use a Loop step when an <code class="expression">space.vars.automation</code> needs to inspect, evaluate, or act on every <code class="expression">space.vars.entity</code> in a set, for example, checking a set of active contracts for inconsistent data such as a termination date on a contract that's still marked active, or iterating through active policies to build a second array of <code class="expression">space.vars.entities</code> to calculate commission values.

Loops build on [Agentic Workflow variables](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-variables.md) and on the way parallel paths inside a loop converge before continuing. Loops reuse the same branch-merging mechanism introduced for [Agentic Workflow conditions](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-conditions.md).

## Terminology

* **Array**: The collection of values a Loop step iterates over. The values can be <code class="expression">space.vars.entities</code>, strings, or UUIDs. An array can be empty, but never null.
* **Item**: An entry within an array. An item can be an <code class="expression">space.vars.object</code> <code class="expression">space.vars.entity</code>, a string, or a UUID.
* **Add Items to Array**: The action of adding entries to an array variable.

## Adding a Loop Step

Select **Loop** from the step-type selector, either the top selector on the canvas or the "+" dropdown between steps, where it's listed after <code class="expression">space.vars.condition\_step</code>.&#x20;

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FxFmq4502HhUZPqeFUZHU%2Fkizen-step-type-selector.png?alt=media&amp;token=38313070-498d-4f3a-9498-ad4cd200874d" alt="Step-type selector with buttons for Action, AI Agent, Condition, Loop, Delay, and Goal."><figcaption></figcaption></figure></div>

Adding a Loop step opens the Add Loop modal, with three sections:

1. **Loop Type**: The only option at the moment is For Each Item, which is pre-selected.
2. **Description**: The same optional description field every step type has.
3. **Loop Settings**: Where you choose the Array Variable and see the auto-generated Item Reference Variable.

If the workflow has no array variables yet, the Array Variable field shows “No options” and an **Add Variable** choice. Choose **Add Variable** to create one without leaving the modal. The new variable then appears in the field.

The Array Variable list only includes variables whose Cardinality is set to Array of Values, whether their type is Object Record, String, or UUID. For a nested loop, the array variable already used by the outer loop is excluded from that list for the inner loop, since reusing it could corrupt the iteration state of the outer loop. If it's selected, saving the step fails.

Once you choose an array variable, Kizen auto-generates the Item Reference Variable using the pattern `<array variable name>_item` (for example, `_contact_list_item`). If that name is already taken, an incrementing suffix is appended, for example `_contact_list_item_1`.

If you later change the Array Variable, what happens to the Item Reference Variable depends on the target: Selecting a variable of the same kind leaves it unchanged, so steps inside the loop that already reference it continue to work. The same kind means a <code class="expression">space.vars.entity</code> array that points to the same <code class="expression">space.vars.object</code>, or a string array swapped for a UUID array (or the reverse). Selecting any other variable replaces it with a newly generated one and deletes the old one. That covers a Record array that points to a different <code class="expression">space.vars.object</code>, and any switch between a <code class="expression">space.vars.entity</code> array and a string or UUID array. Any step inside the loop still referencing the deleted variable will generate an error when you try to save it.

## Loop Anatomy

Adding a Loop step places two cards on the canvas. The Loop card is labeled Loop, with a summary that reads "For each item in `<array variable name>`," for example, "For each item in `pets_array`." Like other step cards, its description is truncated to two lines, with the full text available in a tooltip on hover.

A card labeled Next/Finish marks the end of the loop, with a summary that reads "Next item or finish loop and continue". It shares the Loop card's color, and unlike other step cards, it has no drag handle and no three-dot menu. Instead, every action on the loop lives on the Loop card.

A dotted line connects the Next/Finish card back up to the Loop card to show which steps belong to the loop. Steps placed after the Next/Finish card connect normally to whatever comes next in the <code class="expression">space.vars.automation</code>.

## Managing Loops

Hover over the Loop card to reveal a move handle you can drag to relocate the entire loop. While you're dragging it, every card inside the loop, including Next/Finish, switches to a placeholder style, and you can drop it anywhere but inside itself or into a loop that’s already at the maximum nested depth of three. Once you drop it in its new spot, downstream steps reconnect to the Next/Finish card the same way they would for any other step move.

Copying a loop and pasting it copies only the Loop and Next/Finish cards. None of the steps inside the loop come with it, the same way copying a <code class="expression">space.vars.condition\_step</code> step copies the <code class="expression">space.vars.condition\_step</code> but not the steps on its paths. The pasted loop gets its own Item Reference Variable, renamed with an incrementing suffix if the default name is already taken.

Deleting a loop is only possible from the Loop card. The Next/Finish card can't trigger it. Because deleting the Loop card removes every step inside the loop, Kizen asks you to confirm first: "All steps within this loop will be deleted as well." Steps that came after the loop are reconnected to wherever the loop used to start.

## Exiting a Loop Early

An Exit Loop step stops a loop before it reaches every item, for example, when a loop searching a set of <code class="expression">space.vars.entities</code> finds the one it needs. When it runs, Exit Loop skips the remaining iterations and the <code class="expression">space.vars.automation</code> continues with the first step after the loop's Next/Finish card.

**Exit Loop** is listed under **Agentic Workflows** in the **Add Action** modal, and it appears only when you add a step inside a loop. Choosing it takes you to two more sections lower in the same modal:

1. **Description**: The same optional description field available with every step.
2. **Action Settings**: A **Loop to Exit** dropdown that lists every loop containing the step. Options read `<array variable name> Loop`, for example, `pets_array Loop`. It defaults to the innermost loop.

The card is labeled **Exit Loop**, with a summary that reads "Exit \<array variable name> Loop", for example, "Exit pets\_array Loop."

Steps you place between an Exit Loop step and the **Next/Finish** card on the same path are marked **Unreachable**, since the loop never gets that far. If the Exit Loop step is on one path of a <code class="expression">space.vars.condition\_step</code> or Goal step, only the steps on that path before the paths merge are marked **Unreachable**. If every path has an Exit Loop step, every step after them is marked **Unreachable**.

Exit Loop has a few placement rules:

* You can't drag it outside the loop it exits, although you can move it into or out of an inner loop.
* You can copy it and paste it where you choose, but only inside the loop.
* You can't duplicate it. Duplicating it adds an instant copy beside the original as a new branch, and loops don't allow branches.
* Deleting a loop deletes its Exit Loop steps too, and an Exit Loop step can't be saved if the loop it points to no longer exists.

## Behavioral Caveats and Limitations

### Nesting Depth

Loops can be nested up to three levels deep: an outer loop containing an inner loop, which can contain one more inner loop. Once you're at that depth, Kizen removes Add Loop from the "+" menu and blocks pasting a copied loop inside it. Dragging a Loop step, or an existing loop, into a spot that would exceed the limit tags every step inside the loop with the restriction message: \
"<code class="expression">space.vars.automations</code> only support a loop depth of 3."

### No Branching

You can't create a branch inside a loop, and so the Create New Branch action is removed from the "+" menu while you're inside one. For the same reason, steps inside a loop have no **Duplicate** option in their three-dot menu, since duplicating a step creates a branch. This doesn't affect <code class="expression">space.vars.condition\_step</code> or Goal steps, which produce paths rather than branches and remain usable inside a loop. Dragging in a set of steps that contains a branch (for example, a <code class="expression">space.vars.condition\_step</code> step with branches downstream) marks every step inside the loop with the restriction message: "You cannot add branches to a loop".

### No 'Go To' Agentic Workflow Step

You can't add a Go To <code class="expression">space.vars.automation</code> Step inside a loop. It's removed from the list of available actions while you're dragging into one. Dragging in a Go To step, or a set of steps that contains one, tags every step inside the loop with the restriction message: "You cannot add Go To Steps to a loop". If the steps you're dragging in include a <code class="expression">space.vars.condition\_step</code> step that has both a branch and a Go To step, either restriction message might appear. A Go To Agentic Workflow Step outside a loop also can't target a step inside one.

### Modifying the Array Mid-Loop

While a loop is running, no other step is allowed to update the array variable it's iterating over. Attempting to do so pauses the updating step on failure with the error: "Array variable `<variable name>` cannot be updated while looping over its items." Update Variable and Search <code class="expression">space.vars.entities</code> steps follow their normal step error handling when this happens. Code and LLM steps also follow their normal error handling but don't retry.

### Archived Records

If a <code class="expression">space.vars.entity</code> in the array is already archived before the loop reaches it, that item is skipped and the Next/Finish step's history is marked failed for that item. If a <code class="expression">space.vars.entity</code> becomes archived while it's actively being processed inside the loop, handling depends on the step involved, for example, a step that tries to update a field on the now-archived <code class="expression">space.vars.entity</code> fails at the point it attempts that interaction and pauses, following that step's normal error handling. If a <code class="expression">space.vars.entity</code> driving an outer loop is archived while an inner loop is running on it, the inner loop finishes early.

## Debug and Execution Behavior

Each Item Reference Variable is initialized alongside an <code class="expression">space.vars.automation</code>'s other variables, but that initialization step isn't shown on the standard canvas. It becomes visible in the Execution View and Debug View canvases, alongside the <code class="expression">space.vars.automation</code>'s other variables, with the card label Variable - Item Reference. In Debug view, it's iterated through the same way as other variable steps, initializing to blank.

Skipping the Loop card in Debug mode skips the entire loop: Every step inside becomes unreachable, and the first step after the Next/Finish card becomes the next pending step. For general Debug mode behavior, see [Agentic Workflow Status & Lifecycle](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-status-and-lifecycle.md).

***

## What's Next

Now that you know how to build and manage a Loop step, learn how the variables it depends on work, and see how it fits into a running <code class="expression">space.vars.automation</code>.

<details>

<summary>Related Topics</summary>

* [Agentic Workflow Variables](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-variables.md)
* [Agentic Workflow Conditions](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-conditions.md)
* [Agentic Workflow Status & Lifecycle](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-status-and-lifecycle.md)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-loops.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
