Loop Agents

Loop agents repeatedly execute sub‑agents until a stopping condition is met, enabling iterative improvement and progressive refinement workflows.

The LoopAgent

The LoopAgent executes its subAgents in a loop. It repeatedly runs a sequence of agents for a specified number of iterations or until a termination condition is met.

Use the LoopAgent when your workflow involves repetition or iterative refinement (for example, revising drafts or retrying approaches).

As with other workflow agents, the LoopAgent is not powered by an LLM and is deterministic in how it orchestrates. Sub‑agents can be any type, including LlmAgent.

Visual

Quick Example

Here's how to create a problem‑solving loop that tries different approaches until finding a working solution:

import { LlmAgent, LoopAgent, Event, EventActions } from "@iqai/adk";

// Problem-solving agent (pseudo tools omitted here)
const solverAgent = new LlmAgent({
  name: "code_problem_solver",
  description: "Attempts solutions iteratively",
  model: "gemini-2.5-flash",
  instruction: `Try an approach; if tests pass, state 'PASS'. Otherwise, adapt and try again.`,
  outputKey: "solver_status",
});

// Checker agent to stop the loop when PASS
class StopOnPass extends LlmAgent {}
const stopChecker = new (class extends LlmAgent {
  constructor() { super({ name: "stop_checker", description: "Stops on PASS" }); }
  // Delegate to Event emission: if status is PASS, escalate
  protected async *runAsyncImpl(ctx: any) {
    const status = String(ctx.session.state.get("solver_status", "")).toUpperCase();
    const done = status.includes("PASS");
    yield new Event({ author: this.name, actions: new EventActions({ escalate: done }) });
  }
})();

// Loop up to 8 attempts
const persistentSolver = new LoopAgent({
  name: "persistent_solver",
  description: "Keeps trying until success or limit",
  subAgents: [solverAgent, stopChecker],
  maxIterations: 8,
});

How it Works

When the LoopAgent runs, it performs the following actions:

1. Sub‑Agent Execution: Iterates through subAgents in order; each sub‑agent’s run method is called per iteration.
2. Termination Check: The loop itself does not inherently decide when to stop. You must implement a termination mechanism to prevent infinite loops. Common strategies:
   • Max Iterations: Set maxIterations on the LoopAgent. The loop terminates after that many iterations.
   • Escalation from sub‑agent: Design one or more sub‑agents to evaluate a condition (e.g., “Is the quality good enough?”). If the condition is met, the sub‑agent signals termination by yielding an Event with EventActions({ escalate: true }).

Key Benefits

• Iterative Improvement: Each cycle builds on previous results for progressive refinement
• Automatic Retry: Keep trying until success or limits are reached
• Quality Convergence: Gradually approach desired quality standards
• Flexible Stopping: Multiple ways to determine when to stop

When to Use

Ideal for:

• Content refinement (improve writing until quality standards are met)
• Problem solving (try different approaches until solution found)
• Research deepening (iterate to build comprehensive understanding)
• Code optimization (refine until performance goals achieved)

Avoid when:

• Single execution is sufficient
• No clear improvement path exists
• Infinite loops are possible without proper stopping conditions

Related Topics