Anti-pattern di cicli e orchestrazione

The agentic loop is deceptively simple: send a request, inspect the stop_reason, run any tools, append results to history, repeat until end_turn. Yet this is exactly where production agents fail most often.

This lesson dissects three orchestration anti-patterns that recur across the Claude Certified Architect exam:

• Text-parsing termination — stopping when the reply contains a word like "done".
• Arbitrary iteration caps used as the primary stop mechanism.
• Over-narrow decomposition — slicing work so finely that quality and coordination collapse.

Each looks reasonable in a demo and breaks under real traffic. Let's make the correct patterns reflexive.

Claude keeps no server-side state. Every turn you resend the full messages history. The model signals control flow through stop_reason, not through prose.

The four stop reasons you orchestrate against:

• end_turn — the task is complete; exit the loop.
• tool_use — run the requested tools, append results, continue.
• max_tokens — output was truncated.
• stop_sequence — a configured sequence was emitted.

The contract is structural. Branch on the field the API guarantees, never on the text the model happens to produce.

The most common termination bug: scanning the assistant's text for a completion signal.

This fails in ways that are hard to debug:

• The model writes "I'm not done yet" — your substring match on "done" fires anyway and exits early.
• The model finishes but phrases it as "that completes the analysis" — your check never matches and the loop spins.
• A tool result quotes the word "finished" — false termination.

Natural language is probabilistic; control flow must be deterministic. The stop_reason field exists precisely so you never have to guess from prose.

Terminate on stop_reason == "end_turn". When it is tool_use, execute every requested tool, append the results as a tool_result message, and continue. The model decides when it is finished by emitting end_turn — you simply honor that signal.

This keeps the decision model-driven where it belongs. The model has the full context to judge completion; your harness only routes the structured signal.

The next trap is treating an iteration cap as the way you stop. You write for _ in range(5) and call it orchestration.

The problem is intent. A cap that is your primary stop means:

• Tasks that legitimately need 7 tool calls are silently truncated mid-investigation.
• Tasks that finish in 2 calls still appear "capped" in your telemetry, hiding real behavior.
• You have no signal distinguishing completed from ran out of budget.

The model's end_turn must remain the decision point. The cap is something else entirely.

Iteration caps are valid — but only as a safety net against runaway loops, never as the primary termination logic. The reflex from the fact sheet: decisions are model-driven; reserve hard code for guarantees.

So the cap sits around the model-driven loop. end_turn is how you normally exit. The cap only fires in the pathological case, and when it does you treat that as an error condition worth logging and escalating — not a normal exit.

"Model-driven" does not mean "never use hard code." Reserve deterministic code for genuine guarantees — places where a probabilistic decision is unacceptable.

Examples from the exam's anti-pattern catalog:

• A hook blocking a refund over $500 — deterministic enforcement, ~100% reliable, versus a prompt at ~90%.
• A programmatic precondition: block process_refund until get_customer has returned a verified ID.

The line is clear: route open-ended decisions to the model; encode policy and safety in code. Caps belong to the latter only as a backstop.

Multi-agent systems use a hub-and-spoke shape: a coordinator decomposes, delegates, aggregates, routes, and handles errors. The orchestration failure here is slicing the work too finely.

Over-narrow decomposition spawns a subagent per trivial step. The costs compound:

• Coordination overhead dwarfs the actual work.
• Each subagent loses context — subagents do not inherit the coordinator's conversation history.
• Cross-cutting judgment that needs a whole-picture view gets fragmented across isolated agents.

Decompose by meaningful unit of work, not by individual operation.

Because subagents start with a blank history, the coordinator must pass all needed context explicitly in each subagent prompt. Over-narrow decomposition makes this worse: more agents means more boundaries where context is dropped and more prompts to keep in sync.

Note also that multiple Task calls in a single response run in parallel, and the coordinator's allowedTools must include "Task". Parallelism is a reason to decompose at the right granularity — independent, self-contained units — not to shatter one coherent task into fragments that each need the same shared context re-injected.

Code review is the canonical example of correct decomposition — and it shows the difference from over-narrow slicing.

The right structure is a per-file local pass followed by a separate cross-file integration pass. A single-pass multi-file review dilutes attention; one agent juggling everything misses both local bugs and integration issues.

The wrong over-narrow extreme is the opposite error: a subagent per function or per line, none of which can see enough to judge correctness. Decompose into passes that each have a coherent scope — file-level, then integration-level — not into fragments below the level at which judgment is possible.

One more lever prevents both over- and under-decomposition: match the strategy to the problem shape.

• Fixed pipelines / prompt chaining for known, sequential steps — extract, then validate, then format.
• Adaptive decomposition for open-ended investigations where the next step depends on what was just found.

Forcing a fixed pipeline onto an open-ended research task pushes you toward brittle over-narrow stages; using adaptive decomposition for a deterministic three-step transform adds needless coordination. Choose deliberately, and let the model drive the steps it should own while code owns the steps that must be guaranteed.

An architect's agent loop calls tools across several turns. Pick the orchestration that matches the certification's reliability guidance.

Three reflexes to carry into the exam and into production:

• Terminate on stop_reason. Exit on end_turn; never parse text for "done". The model owns the completion decision; you route its structured signal.
• Caps are a safety net, not a plan. Keep a generous cap to catch runaways, treat hitting it as an anomaly, and reserve hard code for real guarantees (hooks, preconditions).
• Decompose at the right grain. Hub-and-spoke with coherent units — per-file then cross-file passes, not a subagent per line. Pass all context explicitly, and match fixed vs adaptive strategy to the problem.

Get these three right and most loop-and-orchestration distractors on the exam fall away.