Loop

The loop primitive has two modes: foreach for deterministic batch processing and react for AI agent reasoning. Both share the same type: "loop". The mode property determines behavior.

Foreach Mode

Process an array of items with configurable concurrency and failure handling. Foreach is designed for bounded inline work. Use it with custom-table steps or registered HTTP actions that you explicitly mark as inline.

json

{
  "type": "loop",
  "properties": {
    "mode": "foreach",
    "items_path": "@input.orders",
    "item_variable_name": "order",
    "actions_to_execute": [
      {
        "type": "custom-table",
        "properties": {
          "table": "order_work_queue",
          "operation": "upsert",
          "key_fields": ["order_id"],
          "keys": ["order_id", "customer_id", "amount", "status"],
          "values": ["@order.id", "@order.customer_id", "@order.total", "ready"]
        }
      }
    ],
    "max_concurrency": 10,
    "failure_strategy": "continue_on_error",
    "collect_results": true,
    "result_key": "queuedOrders"
  }
}

Foreach Properties

Property	Type	Required	Description
`mode`	`"foreach"`	Yes	Selects foreach mode
`items_path`	@path / doc:	Yes	Array of items to iterate over. Accepts `@path` references or `doc:` uploaded documents (CSV/JSON resolve to arrays)
`item_variable_name`	string	Yes	Variable name for the current item (accessible as `@{name}`)
`actions_to_execute`	array	Yes	Inline-safe steps to run for each item, such as custom-table operations and HTTP actions explicitly marked `inline: true`
`max_concurrency`	number	No	Maximum parallel executions (default: 5, max: 50)
`failure_strategy`	string	No	`"continue_on_error"` (default) or `"fail_fast"`
`collect_results`	boolean	No	Whether to gather results from all iterations (default: true)
`result_key`	string	No	Context key for collected results

Item Access

Inside actions_to_execute, reference the current item using the variable name:

json

{
  "item_variable_name": "order",
  "actions_to_execute": [
    {
      "type": "custom-table",
      "properties": {
        "table": "order_work_queue",
        "operation": "write",
        "keys": ["order_id", "amount", "currency"],
        "values": ["@order.id", "@order.total", "@order.currency"]
      }
    }
  ]
}

Failure Strategies

continue_on_error (default): Failed items are recorded but processing continues. Use when one rejected row should not stop the rest of the batch.

fail_fast: If any item fails, the loop stops and the run fails. Use when all items must succeed.

React Mode

Run an AI agent that reasons step-by-step toward an objective. See Agents for full details.

json

{
  "type": "loop",
  "properties": {
    "mode": "react",
    "objective": "Investigate this expense report. Check policy compliance, verify receipts, recommend approval or rejection.",
    "tools": [
      { "type": "action", "name": "lookup_employee" },
      { "type": "action", "name": "check_expense_policy" },
      { "type": "action", "name": "verify_receipt" }
    ],
    "model": "gpt-4",
    "max_iterations": 15,
    "timeout_ms": 300000,
    "temperature": 0.7,
    "on_stuck": {
      "action": "escalate",
      "iterations": 3
    },
    "include_reasoning_trace": true,
    "result_key": "expenseDecision"
  }
}

React Properties

Property	Type	Required	Description
`mode`	`"react"`	Yes	Selects react mode
`objective`	string	Yes	What the agent should accomplish. Supply the required facts directly, through a `doc:` reference, or through a declared tool
`tools`	array	Yes	Available tools as typed declarations or action-name strings. See Tool Declarations
`model`	string	No	LLM model to use (default: configured in environment)
`max_iterations`	number	No	Maximum think-act-observe cycles (default: 10)
`timeout_ms`	number	No	Maximum execution time in milliseconds (default: 300000)
`temperature`	number	No	LLM temperature from 0 to 2 (default: 0.7)
`on_stuck`	object	No	Recovery when agent loops without progress
`on_stuck.iterations`	number	No	Repeated iterations before triggering (default: 3)
`on_stuck.action`	string	No	`"fail"`, `"escalate"`, or `"retry_with_hint"`
`on_stuck.hint`	string	No	Guidance text for `retry_with_hint`
`include_reasoning_trace`	boolean	No	Include the reasoning trace in the loop result (default: true)
`result_key`	string	No	Context key for the agent's final answer

When to Use Which Mode

Use Foreach When	Use React When
You know exactly what to do with each item	The task requires judgment or reasoning
Processing is deterministic	The approach depends on intermediate results
Items are independent of each other	The agent needs to decide what to do next
You need parallel processing	You need natural language understanding

Composing batch work and agent review

actions_to_execute cannot contain another loop. For a governed batch investigation, persist the candidate rows with foreach, then let one top-level ReAct step read them through a fixed custom-table action. If every item needs a separate agent run, start one bounded agent execution per item from your application and put that item's facts or document reference in its objective.

→ Next: Approval