Loop Agent

Purpose

Within the broader scope of Agent Workflow Management, the Loop Agent addresses the need to repeatedly execute a set of sub-agents either for a fixed number of iterations or until a specified termination condition is met. This subtopic enables workflows that require iterative refinement, continuous monitoring, or repeated attempts to achieve a goal—scenarios where running sub-agents just once (as with the Sequential Agent) or concurrently (as with the Parallel Agent) is insufficient.

Typical use cases include iterative problem solving, progressive refinement of an output (such as code revision or multi-step reasoning), or polling-like behaviors where the loop continues until an escalation or stop signal occurs.

Functionality

The Loop Agent extends the base agent behavior by orchestrating its sub-agents in a repeating cycle. Key aspects of its functionality include:

• Iteration Control: It accepts a configuration parameter MaxIterations. If set to zero, the agent loops indefinitely until a termination condition occurs; otherwise, it runs for the specified number of iterations.

• Sub-agent Execution Sequence: In each iteration, all contained sub-agents are executed sequentially. The Loop Agent yields events generated by each sub-agent back to the caller as they occur.

• Termination Conditions:

  • The loop exits early if any sub-agent emits an event with the Escalate action flag set. This typically indicates a sub-agent has requested higher-level intervention or that a stopping condition has been met.

  • When the maximum number of iterations is reached (if set), the loop terminates naturally.

• Event Streaming: The agent uses an iterator-style pattern to yield session.Event objects asynchronously to the caller, allowing real-time processing or streaming of sub-agent outputs.

• No Custom Run Implementation Allowed: The Loop Agent enforces that the Run method cannot be overridden in the configuration, ensuring that the looping behavior remains consistent and managed internally.

Core Looping Logic Example

func (a *loopAgent) Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] {
    count := a.maxIterations

    return func(yield func(*session.Event, error) bool) {
        for {
            shouldExit := false
            for _, subAgent := range ctx.Agent().SubAgents() {
                for event, err := range subAgent.Run(ctx) {
                    if !yield(event, err) {
                        return
                    }
                    if event.Actions.Escalate {
                        shouldExit = true
                    }
                }
                if shouldExit {
                    return
                }
            }

            if count > 0 {
                count--
                if count == 0 {
                    return
                }
            }
        }
    }
}

This snippet demonstrates the continuous execution of sub-agents, yielding their events, and checking for termination conditions.

Integration

The Loop Agent is a specialized implementation within the Agent Workflow Management topic, complementing the Sequential Agent and Parallel Agent by providing iterative execution semantics.

• With Sub-agents: The Loop Agent operates by managing sub-agents configured under it. These sub-agents can themselves be various types of agents (e.g., LLM agents, tool agents, or other workflow agents), allowing complex nested workflows.

• Within Sessions: It integrates seamlessly with the session management system to append events generated during each iteration, preserving state and event history as part of the overall user-agent interaction.

• With Runner: The Loop Agent is typically executed via the Agent Execution Runner, which manages invocation context, session updates, and event streaming.

• Escalation Propagation: The agent respects escalation signals from sub-agents, which may be triggered by function calls or internal logic, allowing higher-level agents or orchestrators to interrupt looping workflows when necessary.

• Testing and Customization: Unit tests demonstrate usage scenarios, including infinite loops, capped iteration loops, and escalation-triggered exits, showcasing flexibility and robustness.

Relationship with Other Workflow Agents

flowchart TD
LoopAgent[Loop Agent]
SequentialAgent[Sequential Agent]
ParallelAgent[Parallel Agent]
SubAgent1[Sub-Agent 1]
SubAgent2[Sub-Agent 2]
SubAgent3[Sub-Agent 3]
LoopAgent --> SubAgent1
LoopAgent --> SubAgent2
SequentialAgent --> SubAgent1
SequentialAgent --> SubAgent2
ParallelAgent --> SubAgent2
ParallelAgent --> SubAgent3

The diagram illustrates how the Loop Agent manages its own sub-agents similarly to other workflow agents but with repetition semantics.

Diagram of Loop Agent Execution Flow

flowchart TD
Start[Start Loop]
IterationCheck{MaxIterations reached?}
RunSubAgents[Run Sub-Agents Sequentially]
YieldEvents[Yield Events to Caller]
EscalateCheck{Escalate Flag?}
Terminate[Terminate Loop]
NextIteration[Next Iteration]
Start --> IterationCheck
IterationCheck -- No --> RunSubAgents
RunSubAgents --> YieldEvents
YieldEvents --> EscalateCheck
EscalateCheck -- Yes --> Terminate
EscalateCheck -- No --> NextIteration
NextIteration --> IterationCheck
IterationCheck -- Yes --> Terminate

This flowchart visualizes the Loop Agent's core iterative process, showing how it runs sub-agents repeatedly, yields events, checks for escalation, and respects maximum iteration limits.

The Loop Agent’s design enables developers to build iterative AI workflows that require repeated processing steps, refinement cycles, or monitoring loops, integrating tightly with the broader agent orchestration capabilities described in Agent Workflow Management.