Loops Examples

Two runnable examples demonstrate the Loop workflow construct using deterministic handler tasks (no LLM required, completely offline). The same patterns work with AI-backed tasks — replace the handlers with descriptions and provide a chatLanguageModel(...) on the ensemble.

Reflection loop (writer + critic)

A writer drafts content; a critic reviews; the loop repeats until the critic approves or hits the iteration cap. Default config: LAST_ITERATION output, ACCUMULATE memory, RETURN_LAST on max iterations.

./gradlew :agentensemble-examples:runLoopReflection

Source: LoopReflectionExample.java.

What it shows:

• Multi-task loop body that repeats until a predicate fires.
• Reading the per-iteration history from EnsembleOutput.getLoopHistory(...).
• LoopOutputMode.LAST_ITERATION (default) projecting only the final iteration’s outputs to the rest of the ensemble.
• MaxIterationsAction.RETURN_LAST returning the last attempt as the final output if the loop never converges.

Sample output (truncated):

Loop 'reflection' stopped by predicate after iteration 3/5
Loop ran 3 iteration(s)
Termination reason: predicate
Final draft: Draft attempt #3 on edge AI inference.
Final verdict: APPROVED

Retry-until-valid (generator + validator)

A generator produces output; a validator decides if it’s acceptable; the loop repeats until valid or aborts. Two scenarios:

• Convergence: the validator passes on iteration 3; the loop terminates via the predicate.
• Non-convergence: the validator never passes; MaxLoopIterationsExceededException is thrown because onMaxIterations(THROW) is configured.

./gradlew :agentensemble-examples:runLoopRetryUntilValid

Source: LoopRetryUntilValidExample.java.

What it shows:

• MaxIterationsAction.THROW for “non-convergence is a hard error” semantics.
• The contrast with the reflection example: when never-converged means broken output rather than degraded output.
• Body tasks declaring intra-body context() deps so the validator sees the generator’s output.

See also

• Loops guide — full reference for stop conditions, output modes, memory modes, and validation rules.
• Phase Review examples — bounded one-step retry within a phase, contrasted with the multi-iteration loop pattern.