What makes a Koog agent hit its maxIterations limit mid-run?

## What the cap is `AIAgent` takes a `maxIterations` parameter that bounds how many iterations the agent performs before Koog gives up and fails the run. It is deliberately blunt: when it trips you get an error, not a truncated answer, because a half-finished agent run silently presented as a result is worse than a visible failure. Be precise about what it is *not*. It is not a token budget and not a spend cap — a run can burn a lot of money in few iterations, or many cheap iterations. It is not a timeout either. It is a liveness guard: proof that the graph is making progress toward `nodeFinish`, and a hard stop when it is not. ## Cause one: the graph cannot terminate Koog type-checks that every edge is a legal hop. It does not and cannot prove that a path to `nodeFinish` exists for every value a node can emit. So the classic failure is structural: - `nodeLLMSendToolResult` has an `onToolCall` edge back to `nodeExecuteTool` but no `onAssistantMessage` edge to `nodeFinish`. The agent handles tool-free questions correctly and hangs on every question that touches a tool. - A broad or unconditional edge is declared above the narrow one that leads out, so the exit is shadowed — edges are taken in declaration order, first match wins, and the shadowed edge is legal, compiling dead code. - A custom node routes back into an earlier node on a condition that the graph never clears. The signature of this class of bug is determinism. The same input fails the same way every time, at roughly the same iteration count, regardless of model or temperature. That makes it cheap to reproduce: a strategy is an ordinary Kotlin object, so you can drive it in a unit test with a stubbed executor and assert the run reaches `nodeFinish`. ## Cause two: the model will not stop The second family is behavioural. The graph is wired correctly and does have an exit, but the model never emits the plain assistant message that takes it. Typical triggers: - A tool returns an error string every time — bad credentials, a 404, an empty result set — and the model keeps retrying it, sometimes with slightly different arguments, sometimes identically. - Two tools contradict each other, and the model oscillates between them looking for agreement. - The system prompt insists the model must verify before answering, and verification never succeeds, so the model obediently never answers. This one is intermittent. It correlates with a downstream dependency being unhealthy, with a specific class of input, or with a model version change. It does not reproduce on your laptop. ## Telling them apart Instrument the run so each iteration records which node executed and, for tool nodes, which tool with which arguments. Then read the trace: - The same two nodes alternating with no new tool activity, ending exactly at the cap: wiring. Fix the graph. - The same tool called repeatedly, arguments drifting or identical, results all errors: model-side loop. Fix the tool or the prompt, not the graph. - A node reached once and never left: no outgoing edge matched. That is wiring again, of the stranded rather than the cycling kind. That classification is what an interviewer at senior level is listening for — the ability to separate "my graph is wrong" from "my dependency is down" from a symptom that looks identical from the outside. ## Choosing the number Set the cap from the graph's shape, not from superstition. Count the maximum sensible tool round-trips for the task and leave headroom — a research agent that legitimately makes a dozen searches needs more than a classifier that calls one tool. Setting it very high to "stop the errors" converts a fast, loud failure into a slow, expensive one; setting it below the honest worst case truncates legitimate long runs, and users experience that as random failure on the hardest queries. Also treat cap hits as a monitored signal rather than noise. A steady low rate is your graph's natural tail. A step change means something moved: a tool started failing, a model version shipped, a prompt edit removed an early exit. Because the cause is nearly always one of those three, the alert is unusually actionable. ## What to do when it trips in production Fail the request cleanly and say so — do not present whatever text happened to be lying around as an answer. Log the node trace with the failure so the classification above can be done after the fact rather than by reproducing it. And if the run did real, non-idempotent work through tools before aborting, know what state it left behind; the cap stops iteration, it does not undo side effects the tools already performed.