How does a Google ADK LoopAgent decide to stop iterating?

## What the loop actually does `LoopAgent(name=..., sub_agents=[...], max_iterations=N)` is a workflow agent, so like `SequentialAgent` and `ParallelAgent` it invokes no model of its own. Its behaviour is: run sub-agent 1, then 2, then 3; that is one iteration; go back to sub-agent 1; repeat. It carries the same invocation context and the same session state across every iteration, which is what makes progress possible — each pass reads what the previous pass left in state and improves on it. ## Termination condition one: max_iterations The simplest bound. `max_iterations=5` means at most five passes over the sub-agent list, after which the loop finishes regardless of whether anything was achieved. If you leave it unset, nothing in the framework will stop the loop for you. `max_iterations` is not primarily a quality mechanism; it is a **cost and liveness** mechanism. Iterative agent loops fail in a characteristic way — the refiner and the critic settle into a stable disagreement, each pass producing an almost identical draft and an almost identical critique — and without a bound that failure is an unbounded spend that ends when someone notices the bill or the request times out. Set it on every loop, including ones you are confident will escalate. ## Termination condition two: escalation The interesting exit is semantic: stop because the work is *done*. ADK expresses this as escalation. A tool running inside a sub-agent sets `escalate` to true on its tool context's actions, and the loop treats that as a signal to end after the current step. A custom agent built on the base agent class can emit an event whose actions carry escalate for the same effect. The key structural point is that the loop delegates the exit judgment to its sub-agents. There is no `condition=` parameter on `LoopAgent` and no LLM inside it asking "are we done?". That produces the standard two-member loop: 1. a **worker** agent that improves the artifact in state (`output_key="draft"`), 2. a **checker** agent whose only job is to evaluate the draft and, when it passes, call a tool that escalates. The checker is where the exit criterion is written, in that agent's instruction, in natural language you can iterate on independently of the worker. ## The failure modes **No exit at all.** The most common bug is a checker whose instruction says "decide whether the draft is good enough" without ever telling it to *call the escalation tool*, or a checker with no such tool registered. The model dutifully replies "yes, this is good enough" as text — text which the loop does not read, because the loop reads actions, not prose. The loop then runs to `max_iterations` every single time. Symptom: every run costs exactly the maximum. If you see uniform maximum iteration counts in your traces, look here first. **Escalating on the first pass.** A checker with a lenient instruction escalates immediately, and the loop degenerates into a single pass — an expensive way to write a `SequentialAgent`. Uniform iteration counts of one are the mirror-image symptom. **No progress carried between passes.** Because iterations share state, the worker must actually overwrite the artifact key each pass. If the worker's `output_key` differs from the key the checker reads, or the worker regenerates from the original input each time without seeing the critique, the loop spins producing new drafts that are not better drafts. Wire the critique into the worker's instruction so pass N+1 sees pass N's feedback. **Oscillation.** Two passes alternating between two acceptable-but-different drafts consume the full budget without converging. Bounding iterations covers the cost; converging usually means making the checker's criterion concrete and checkable rather than aesthetic. ## Operating a loop in production Instrument the iteration count and treat its distribution as a health metric. A healthy refinement loop shows a spread — mostly two or three passes, occasionally the maximum. A distribution pinned at either end means the escalation path is broken in one of the two directions above, and it will not surface as an error because both outcomes are, to the framework, a successful run. Also budget the loop as a whole rather than per agent. A three-member loop with `max_iterations=5` is up to fifteen model calls with a context that grows as state accumulates, so worst-case cost and worst-case latency are both multiplied by the bound. Choose `max_iterations` from what you are willing to spend and wait for on the worst request, not from what feels generous. ## The summary "Iterations run out, or a sub-agent escalates." The senior half of the answer is the follow-on: the loop has no opinion about doneness, so somebody inside it must actively signal it, and `max_iterations` exists to bound what happens when nobody does.