- In short
- Agentic loop anti-patterns are three flawed ways to control when a Claude agent stops looping: parsing natural language for completion, using arbitrary iteration caps as the primary stopping mechanism, and checking for assistant text as a completion signal. Each fails because it ignores the authoritative stop_reason field.
Why agentic loop control anti-patterns matter
Sound agentic loop control is deceptively easy to get almost right. A loop that works in a demo can fail in production because the developer chose the wrong signal to decide when to stop. The Claude Certified Architect exam tests this knowledge point at the evaluate level, which means you will be shown several reasonable-looking loop designs and asked to judge which is sound. Recognising the three agentic loop control anti-patterns on sight is the skill being assessed.
Each anti-pattern shares one root flaw: it substitutes a heuristic for the structured stop_reason field. Loop control should hinge on that one authoritative value; the moment a design routes the stopping decision through prose, a counter, or a content type, it has stepped onto unreliable ground. Once you see that common thread, the three specific mistakes are easy to name and easy to reject.
The role of stop_reason in loop control
Before naming the anti-patterns, it helps to restate what good agentic loop control looks like. Every Messages API response carries a stop_reason, and for an agent it answers the only question that matters between turns: do I run another cycle, or am I finished? A value of tool_use means the model has requested a tool and expects to continue; end_turn means it has produced its final answer. The loop is therefore a while driven by that field, with each iteration appending tool results and resending the history.
The handling-stop-reasons documentation treats this field as the backbone of robust applications, and lists the full set of values, end_turn, tool_use, max_tokens, stop_sequence, pause_turn, and refusal, each of which is a distinct instruction. An anti-pattern is, precisely, any control scheme that ignores this field in favour of a proxy. Keep that definition in mind and the three classic mistakes practically announce themselves.
- Agentic loop anti-pattern
- A flawed loop-control strategy that decides when an agent is done by some means other than the model's stop_reason, leading to premature stops, infinite loops, or truncated output.
Anti-pattern one: parsing natural language for completion
The first temptation is to read Claude's words. "If the reply says 'I'm all done', stop the loop." It feels intuitive and it even works in early testing. It is also the most brittle choice you can make.
Natural language is ambiguous. The model might narrate its reasoning, "let me check that for you", without actually emitting a tool call, or it might call a tool with no narration at all. Phrasing also drifts across prompts and model versions, so a string match that works today silently breaks tomorrow. The structured contract, by contrast, does not drift: a turn that wants a tool returns stop_reason: tool_use, full stop. Re-deriving that fact from prose throws away a guarantee and replaces it with a guess.
Anti-pattern two: iteration caps as the primary stopping mechanism
The second anti-pattern is subtler because part of it is good practice. Capping the number of loop iterations is a legitimate safety guard. It stops a misbehaving agent from running forever and burning budget. The anti-pattern is using that cap as the primary way to decide that the work is done.
If your loop's real stopping logic is "run exactly five iterations and then return whatever you have," you will cut off useful work when the task needed six turns, and waste turns when it finished in two. The cap is blind to whether the model is actually finished. The correct design branches on stop_reason to decide completion, and keeps a generous iteration cap only as a backstop against runaways. Caps guard; they do not decide.
Anti-pattern three: checking for assistant text as a completion signal
The third anti-pattern inspects the response content: "if the assistant returned a text block, it must be finished." This breaks because, as the tool-use documentation shows, the model frequently emits a text block alongside a tool_use block, narrating what it is about to do while also requesting the tool. Seeing text present, your loop concludes the agent is done, returns the half-formed narration, and never runs the tool.
This is closely related to the bug at the heart of debugging premature loop termination, where checking response.content[0].type == "text" ends the loop early. The lesson is the same: the presence of text tells you nothing definitive about completion. Only stop_reason does.
The correct pattern, stated plainly
The sound loop is a while driven by stop_reason: continue while it is tool_use, stop on end_turn, and explicitly handle the other outcomes such as max_tokens. You can layer a safety cap on top to prevent runaways, but the cap is a guardrail, never the primary logic. This is the design Anthropic's effective-agents guidance points toward, give the model structured control of the loop, then add deterministic guards around it where the stakes demand.
Holding this clear distinction, guard versus decision, structured field versus prose, is what lets you evaluate a loop design at a glance. When the exam shows you four loops, the right one branches on stop_reason and treats caps as backstops; the three wrong ones each lean on an anti-pattern.
Why all three anti-patterns share one fix
It is tempting to treat the three mistakes as separate problems with separate remedies, but they are really three faces of a single error: trusting a proxy instead of the source of truth. Natural-language parsing trusts wording; iteration caps trust a counter; content-type checks trust block shape. None of those proxies is the model's actual statement of intent, and so all three can disagree with what the model meant. The unifying fix is therefore also single: read stop_reason and branch on it.
This is why an architect who internalises the principle outperforms one who merely memorises the list. New variations of the mistake appear constantly, "stop when the response is shorter than 50 tokens," "stop after the model uses a particular tool", and they all fail the same way. If you can ask, "is this decision being made by stop_reason or by a proxy for it?" you can classify any candidate loop on sight, including ones the exam invents that are not literally on the canonical list of three.
Worked example
A research assistant agent is shipped with a loop that stops after three iterations regardless of stop_reason. Reviewers notice some reports are incomplete.
The agent is asked to compile findings across several sources, each requiring a tool call. On a broad query it needs five tool-using turns, but the loop halts at three because the iteration cap is doing the deciding. The model was mid-investigation, returned stop_reason: tool_use, and yet the loop exited and surfaced a partial report.
A reviewer first blames the model's reasoning. But the model behaved correctly. It kept asking for tools because it was not finished. The defect is architectural: the cap was promoted from guard to primary stop. The fix is to loop while stop_reason is tool_use and let the cap sit at, say, fifteen iterations purely as a runaway backstop. Now the agent finishes when the model signals end_turn, and the cap only ever fires on genuine misbehaviour.
Two traps stated as misconceptions
Misconception
Iteration caps are an anti-pattern, so a well-designed agent loop should never use them.
What's actually true
Misconception
If Claude's text output says it has finished, the loop can safely stop.
What's actually true
What a robust loop adds on top of stop_reason
Branching on stop_reason is necessary but not the whole story of production-grade loop control. A robust loop also handles the values beyond tool_use and end_turn deliberately. max_tokens means the turn was truncated, so you continue or raise the limit rather than ship a half-answer. pause_turn, returned when a server-side tool loop hits its iteration limit, means you send the response back to let the model finish. refusal means the model declined, which your application should surface rather than retry blindly. Each value is its own branch, and an exhaustive switch is sturdier than an if tool_use / else binary.
This is where the anti-patterns reveal their second cost: by short-circuiting on a proxy, they not only make the wrong stop-or-continue decision, they also skip past these other outcomes entirely. A loop that stops the moment it sees a text block never gets the chance to notice a max_tokens truncation or a pause_turn. So choosing the right signal is not just about avoiding premature stops and infinite loops; it is about being positioned to handle the full range of things a turn can mean. Layering a generous iteration cap on top of that exhaustive handling gives you safety without surrendering correctness.
Bringing it to the exam
Expect scenario questions that describe an agent looping forever, stopping too soon, or returning truncated work, then offer four candidate explanations or fixes. The distractors are deliberately reasonable, "add a clearer instruction," "raise the iteration cap," "check the text for a completion phrase." The correct answer rejects the proxy signals and points back to stop_reason. Because this knowledge point is evaluative, the exam is testing whether you can tell a structurally sound loop from a plausible-but-flawed one, which is exactly the judgment a Claude architect needs in production.
One more framing helps under exam pressure: read every candidate answer and ask whether it makes the loop's decision more dependent on stop_reason or less. Answers that add prose parsing, lean harder on a counter, or inspect content shape all move away from the authoritative signal and are wrong by construction. The single answer that moves toward branching on stop_reason, even if it is phrased plainly, is the one to choose. That lens collapses a four-option question into a one-question test, and it is the same lens you should apply when reviewing real agent code.
An agent occasionally returns an empty or half-written answer. Its loop ends as soon as the assistant response includes any text content block. What is the best fix?
People also ask
What are common mistakes in agent loops?
Are iteration caps a bad way to stop an agent?
Why not parse Claude's text to decide when to stop?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Implementing multiple turns
Why watch: Building the loop correctly highlights the three anti-patterns to avoid: NL termination, iteration caps, and text-type checks.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.