Loop

O bloco Loop é um contêiner que executa os blocks dentro dele repetidamente — sobre cada item de uma coleção, um número fixo de vezes ou enquanto uma condição for verdadeira. Solte blocks dentro dele e eles são executados uma vez por iteração. As iterações rodam uma após a outra; para trabalho concorrente, use um block Parallel.

Tipos de Loop

Um loop For é executado um número fixo de vezes. Defina a contagem de iterações.

Um loop ForEach é executado uma vez por item de um array ou objeto, expondo o item atual como <loop.currentItem>.

Um loop While é executado enquanto uma condição for verdadeira. A condição é verificada antes de cada iteração, então o corpo pode rodar zero vezes.

Um loop Do-While executa o corpo uma vez e depois repete enquanto uma condição for verdadeira. A condição é verificada depois de cada iteração, então o corpo sempre roda pelo menos uma vez.

Configuração

Defina o tipo de loop e depois o valor de que ele precisa:

  • Iterations — quantas vezes executar (loops For)
  • Collection — o array ou objeto a iterar (loops ForEach)
  • Condition — a expressão booleana a verificar (loops While e Do-While)

Referenciar dados do loop

As referências mudam dentro do loop e depois dele.

Dentro do loop, leia a iteração atual com <loop.*>:

  • <loop.index> — o número da iteração, começando em 0
  • <loop.currentItem> — o item atual (somente ForEach)
  • <loop.items> — a coleção completa (somente ForEach)
const idx = <loop.index>;        // 0, 1, 2, ...
const item = <loop.currentItem>; // the current item

Essas referências só estão disponíveis para os blocks dentro do contêiner do loop.

Depois do loop, leia os resultados coletados pelo nome do block de loop — não por <loop.*>:

// a loop named "Process Items"
const all = <processitems.results>; // [result1, result2, ...]

O nome é normalizado — minúsculas, sem espaços. <loop.*> só funciona dentro do loop.

Exemplos

Um loop ForEach pontua cada avaliação e coleta os resultados; quando o loop termina, um Agent resume <loop.results>. O mesmo contêiner abriga os blocks de qualquer tipo de loop:

  • Processar resultados de API — API (Fetch) → Loop (ForEach) → Agent (Analyze) → Function (Store)
  • Gerar variações — Loop (5×) → Agent (Generate) → Evaluator (Score) → Function (Select best)
  • Contador com While — Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)

Aninhamento e limites

Contêineres podem ser aninhados. Você pode colocar loops dentro de loops, parallels dentro de loops e qualquer combinação, para montar workflows multidimensionais.

Loops For e ForEach são limitados a 1.000 iterações. Loops While e Do-While rodam até a condição ser falsa, sem limite fixo — garanta que a condição eventualmente se torne falsa para o loop terminar.

Boas práticas

  • Use ForEach para coleções. Quando você tem um array ou objeto, o ForEach é mais claro que um loop For com indexação manual.
  • Mantenha as contagens de iteração razoáveis. Cada iteração soma ao tempo total da execução, já que o loop roda sequencialmente.
  • Recorra ao Parallel quando a ordem não importa. Trabalho independente sobre uma coleção roda mais rápido em um block Parallel.
  • Garanta uma saída. Em loops While e Do-While, certifique-se de que a condição vai se tornar falsa.

Common Questions

Loops For e ForEach são limitados a 1.000 iterações. Loops While e Do-While com uma condição não têm limite fixo — eles rodam até a condição ser falsa. Um Do-While sem condição recorre a uma contagem fixa, também limitada a 1.000. Garanta sempre que as condições de While/Do-While eventualmente se tornem falsas para evitar loops infinitos.
Sequencialmente, uma após a outra. Para concorrência entre itens, use o block Parallel, ou aninhe um Parallel dentro de um Loop se você precisa dos dois padrões.
Use <loop.currentItem> para o item atual e <loop.index> para o número da iteração, que começa em zero. Essas referências só estão disponíveis para os blocks dentro do contêiner do loop.
Referencie o block de loop pelo seu nome normalizado (minúsculas, sem espaços) com <blockname.results>, que retorna um array com todos os resultados das iterações em ordem. Não use <loop.*> fora do loop — isso só funciona dentro dele.
Sim. Loops e Parallels suportam aninhamento em qualquer combinação, e cada contêiner aninhado mantém seu próprio escopo e contexto de iteração.
Um loop While verifica a condição antes de cada iteração, então pode rodar zero vezes. Um loop Do-While executa o corpo uma vez e depois verifica a condição, então sempre roda pelo menos uma vez.
O corpo é ignorado e o loop retorna um array de resultados vazio. O workflow continua para o que estiver conectado depois do loop.
RouterParallel