Claude Architect · Lesson

Loop & Orchestration Anti-Patterns

Text-parsing termination, arbitrary caps, over-narrow decomposition.

Why Loops Go Wrong

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.

The Loop Contract

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.

import anthropic

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Audit the repo and summarize risks."}]

while True:
    resp = client.messages.create(
        model="claude-opus-4-1",
        max_tokens=2048,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        break
    # ... handle tool_use, append results, loop ...

All lessons in this course

← Back to Claude Architect