For Each

The For Each block executes a single block sequence several times.

Each iteration of the sub-sequence gets its own independent scratchpad.

The sub-sequence can be made of several blocks. The same block transition logic occurs within the sub-sequence as within the “main” sequence. The sub-sequence can even be nested.

The For Each block takes a CEL expression as input, that must resolve to either a list or a dictionary.

  • List: Each value in the list is copied into a new CEL variable, which can be accessed by the sub-sequence blocks.

  • Dictionary: Each key/value pair is copied into a new CEL variable, which can be accessed by the sub-sequence blocks. This variable is itself a dictionary, with the following format: {"key": input_dict_key, "value": input_dict_value}.

Example use case

Imagine an agent that needs to fetch news articles and summarize them. You want the summary to run for each article.

A first block in the Agent flow will fetch the news articles, and store in the state a list of the URLs. So for example you will have, in the state, the variable urls, containing ["url1", "url2", "url3"]

You then use a for-each block, with expression state.urls, and with target block a Core Loop with a web scraping tool.

The expression resolves to a list of three items, so the Core Loop block will be called three times.

You configure the For Each block with the_url as the “Input variable name”. This means that for each iteration, there will be a variable the_url available for CEL templating, containing the URL for this particular iteration.

You can then, for example, in the Core Loop block, use the following settings:

  • Pass History: no

  • Tool: the web scraping tool

  • Instructions: Fetch and summarize the article at {{the_url}}

Output

Once a For Each block completes, the text output of each iteration is written to a key in the state or scratchpad, that will contain the outputs of all the individual iterations. This output will be either a list or a dictionary, matching the type of the input.

  • List: Each value in the output list is the text result of the sub-sequence applied to the corresponding value from the input list.

  • Dictionary: The output dictionary contains the same keys as the input dictionary. Each value in the output dictionary is the text result of the sub-sequence applied to the corresponding key/value pair from the input dictionary.

Cautions

Inherently, the For Each block is not interactive. If you are using a Core Loop block within a For Each block, it will not be possible to resume from it. When the Core Loop block within the For Each block terminates, control will move to the block after For Each.

Be very careful about writing to the state from a For Each block iteration, as several iterations may run in parallel. You should usually only write to the Scratchpad (there is one separate scratchpad per iteration)