Skip to main content

Loop Agent

A composite agent that runs sub-agents in a loop until a maximum number of iterations is reached or a stopping condition is met.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs​

  • Session ID (optional) - (string) A unique identifier for this specific conversation thread.
  • Name - (string) Name of the loop agent.
  • Description - (string) Description of the loop agent's purpose.
  • Query - (string) User query that initiates the loop execution.

Options​

  • Max Iterations - (number) Maximum number of times the loop should run. Default: 5.
  • Custom Sub-Agents Order - (array) Defines the execution order of sub-agents within each loop iteration. Each entry specifies a Sub-Agent Name.
  • Timeout (seconds) - (number) Maximum wait time in seconds for all loop iterations to finish. Default: 300.

Outputs​

  • Response - (string) Final response after the loop finishes or times out.

Ports​

  • sub-agents - (output) Connect to agents (LLM Agent, Sequential Agent, Parallel Agent, Loop Agent) that will execute in each loop iteration.
  • callbacks - (output) Connect to Callback In nodes to monitor loop execution.

How It Works​

The Loop Agent node creates an iterative agent workflow:

  1. Initialization - Creates a loop agent with the specified name, description, and max iterations
  2. Sub-Agent Connection - Connects to all agents on the sub-agents port
  3. Ordering - Orders the sub-agents according to the Custom Sub-Agents Order configuration
  4. Loop Execution - Executes the sub-agent sequence repeatedly:
    • Each iteration runs all sub-agents in order
    • Sub-agents can access and modify session state
    • The loop continues until max iterations or a stop condition
    • Session state accumulates across iterations
  5. Termination - Stops when max iterations is reached, timeout occurs, or agents signal completion
  6. Response - Returns the final result from the last iteration

Common Use Cases​

  • Iterative Refinement - Progressively improve results over multiple passes
  • Retry Logic - Attempt operations with retry mechanisms
  • Polling Workflows - Check status repeatedly until a condition is met
  • Multi-Round Conversations - Handle back-and-forth dialogues with multiple turns
  • Progressive Problem Solving - Break down problems into iterative steps
  • Data Processing Loops - Process items from a list or queue iteratively

Error Handling​

The node will return errors in the following cases:

  • Initialization timeout (30 seconds) - "Agent initialization timed out, cannot process message"
  • Invalid sub-agent order - "Order name not found in agent names"
  • Sub-agent execution failure - Error from the failing agent is propagated
  • Timeout during execution - Loop terminates after the specified timeout
  • Max iterations exceeded - Loop stops and returns the last available result

When Continue On Error is enabled, the workflow will continue even if an iteration fails.

Usage Notes​

  • Ordering is Required - All connected sub-agents must be specified in the Custom Sub-Agents Order configuration
  • State Accumulation - Session state persists across loop iterations, allowing agents to build upon previous results
  • Early Termination - Agents can signal loop completion before max iterations by setting appropriate state values
  • Callbacks - Before and after callbacks can be connected to monitor each loop iteration
  • Nested Loops - Loop agents can contain other loop, sequential, or parallel agents for complex workflows
  • Session Management - Provide a Session ID to maintain context across the entire loop
  • Performance - Total execution time = iterations × (time per iteration)
  • Iteration Tracking - Loop iteration count and state is maintained in the session

Performance Considerations​

  • Max Iterations - Set this value carefully to avoid excessive execution time
  • Timeout - Should account for max iterations × expected iteration time
  • State Size - Session state grows with each iteration; monitor memory usage for long loops
  • API Costs - Each iteration consumes API credits; consider cost implications

Example Workflow​

A typical loop agent workflow might look like:

  1. Data Extractor Agent - Extracts data from a source
  2. Validator Agent - Checks if extraction is complete
  3. Processor Agent - Processes the extracted data

The loop continues until all data is extracted or max iterations is reached, with each iteration processing the next batch of data.

Stopping Conditions​

The loop can terminate through:

  • Max Iterations - Configured maximum is reached
  • Timeout - Total execution time exceeds the timeout value
  • Agent Signal - Sub-agents can indicate completion via state updates
  • Error - An unhandled error occurs (unless Continue On Error is enabled)