Lesson 1: When One Loop Isn't Enough

Learning goals:

• Use a real task that breaks single-loop agents to show why "get a bigger window" doesn't solve the shape problem
• State the architectural distinction between workflows and agents, and use "who holds the plan" to place any system on that axis
• List the triggers for moving up and the conditions for staying put, with latency and token costs on the table first

Prerequisites: Completed the first 11 courses in this series, can hand-write a harness loop driven by stop_reason (course 7, "Agent Harness Fundamentals: Loops and Control") | Next: Lesson 2 >>

By module 30, something's wrong

You need to migrate a backend repo from internal RPC framework v1 to v2. Before starting, you need an inventory: the repo has 40 modules, and each module needs a migration assessment—list the risk points, estimate the scope of changes, attach a dependency manifest. The work isn't hard, it's just numerous. You have that harness from course 7 in this series:

(A harness is the host code wrapping model calls: send the request, execute the tools the model wants to use, push results back, decide whether to continue.)

You hand it the list of 40 modules all at once, write "assess each one, one report per module," then go make coffee.

The first 5 modules look great: it greps out call sites, reads config, checks test files, and the reports are more detailed than you expected.

At module 15, you come back and check the logs. The messages array is already impressive: grep output from the first 14 modules, whole chunks of config files read in, success receipts from file writes, traces of paths taken then abandoned—all still sitting on that timeline. None of this content was wrong—each was necessary at the time. But their current function has been reduced to one thing: taking up space.

By module 30, quality collapses. It copies the conclusion from module 27 onto module 30 because the names are similar; it quietly skips the "check for custom interceptors" step it did every time before; by module 34, even the output format starts drifting.

Your first reaction is probably: switch to a model with a bigger context window.

That reaction only gets you halfway. Double the window and the collapse point probably moves from module 30 to module 55. Your next repo has 120 modules. You haven't solved the problem, you've bought a stay of execution.

What's actually exhausted isn't the window, it's the shape of "one loop": 40 independent items forced to share one timeline, one attention budget. The quality of the assessment for module 30 depends on how much residue the first 29 modules left behind—and these two things have nothing to do with each other.

What this course does is swap out that shape.

Get the official vocabulary straight first

Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop¹. That while you wrote in course 7 of this series is exactly that, not one line different. So position yourself: you've already built an agent, this course isn't starting from zero.

One layer up. Anthropic categorizes all these variations as agentic systems (plain talk: systems assembled from models, tools, and some form of control flow that can walk through multiple steps on their own), but within this broad category they draw an important architectural distinction¹:

• Workflows are systems where LLMs and tools are orchestrated through predefined code paths¹. "Predefined code paths" is the key phrase—what happens next is written into the code.
• Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks¹. What happens next, the model decides on the spot.

One more foundational term you'll use repeatedly in the next few lessons. In computing, deterministic systems produce the same output every time given identical inputs, while non-deterministic systems—like agents—can generate varied responses even with the same starting conditions².

Apply that definition to your while and you'll see it's two things stitched together: how to send the request, how to execute tool calls, when to stop—those are deterministic, written by you in code; while "what to grep next, whether this report is finished"—those are non-deterministic, decided by the model on the spot. The surgery you're about to perform is moving decision-making power between these two halves.

The axis of "who holds the plan"

Claude Code's documentation asks this more directly: Subagents, skills, agent teams, and workflows can all run a multi-step task. The difference is who holds the plan³.

("Subagent" = an assistant that works independently in its own context window and returns only a summary; "fan out" = dispatch multiple subagents to work simultaneously. Course 6 in this series covered both terms.)

That sentence cuts through a bunch of approaches that look similar. Take "run assessments for 40 modules":

• You let the model proceed through all 40 in one conversation—the plan is in the model's hands, and it's implicit, hidden in the conversation history. You'd have to dig through logs to guess its intended path.
• You make the model an orchestrator, and it decides each turn which subagent to dispatch for which module—the plan is still in the model's hands, just a bit more explicit.
• You write a script, and the script for-loops through those 40 modules itself—the plan is in code. You can open the file and read it through, and run it again tomorrow unchanged.

The third approach has a precise description: A workflow moves the plan into code. The workflow script holds the loop, the branching, and the intermediate results itself, so Claude's context holds only the final answer³. And intermediate results stay in script variables instead of landing in Claude's context³. The grep output from module 27 stays in a JavaScript array, so the assessment for module 30 naturally can't see it—not because the model learned to ignore it, but because it never had the chance to see it at all.

For the two ends of this axis, the official guidance each gets one sentence on fit: When more complexity is warranted, workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale¹.

One thing to clarify: this course calls this axis the "determinism spectrum" and calls the composition patterns in lesson 5 "graphs," "nodes," "edges." These labels are this course's own engineering metaphors and never appear in the primary sources—the primary materials only provide definitions of the two endpoints (predefined code paths vs. model-driven decisions)¹ and the framing of "who holds the plan"³. We borrow the spectrum and graph metaphors because they're convenient for arranging patterns that really exist; you won't read these terms in any official docs, so don't present them as official concepts.

When to move up

"One loop isn't enough" sounds like intuition, but there are articulable triggers.

Trigger one: the task needs more agents than one conversation can coordinate, or you want the orchestration codified as a script you can read and rerun³. The first half is a capability issue, the second half is an engineering issue—even if one conversation can barely coordinate it, "can we run this exactly the same way tomorrow" qualifies as a reason on its own.

Trigger two: when the task is larger than one agent can hold in context, or when the same step needs to run across many items³. These two sentences together describe exactly the 40-module scenario at the start. Note the second sentence: the number of items itself is a reason, regardless of whether each item is difficult.

Trigger three: when a side task would flood your main conversation. The subagent documentation's scenario description: when a side task would flood your main conversation with search results, logs, or file contents you won't reference again, dispatch a subagent—it does that work in its own context and returns only the summary⁴, preserving context by keeping exploration and implementation out of your main conversation⁴. Notice this trigger prescribes "dispatch a subagent"—the plan still stays in the model's hands; that and "move the plan into code" are two different things. The Level 2 exercise's columns B and C will lay out this distinction.

Look at this code to get a feel for what the shape looks like after it's swapped:

The loop is still that loop—inside runHarnessLoop is the while you wrote in course 7 of this series. Only one thing changed: who counts to 40. Before, the model was counting. Now, the for is counting.

When to stay put

Behind the trigger signals is an equally long checklist of the opposite, and this one is easier to skip.

Find the simplest solution possible, and only increase complexity when needed. This might mean not building agentic systems at all¹. For many applications, however, optimizing single LLM calls with retrieval and in-context examples is usually enough¹. That job of renaming a function in 12 places doesn't need a harness, doesn't need orchestration—one call plus one grep and it's done.

Some domains today are not a good fit for multi-agent systems: those requiring all agents to share the same context, or where there are many dependencies between agents. The text names one example—most coding tasks involve fewer truly parallelizable tasks than research, and LLM agents are not yet great at coordinating and delegating to other agents in real time⁵. You're refactoring a tightly coupled order module, and changes ripple through a chain of callers—fanning this out to five subagents only makes it slower and messier, because they all need to look at the same thing, and whoever moves first invalidates everyone else's information.

Conversely, the positive fit conditions are stated just as plainly: they found that multi-agent systems excel at tasks that involve heavy parallelization, information that exceeds single context windows, and interfacing with numerous complex tools⁵, and tasks where the value of the task is high enough to pay for the increased performance⁵. The more of these three conditions you hit, the more worthwhile it is to move up.

There's also a category of tasks that should stay with autonomous loops, not forced into orchestration: open-ended problems where it's difficult or impossible to predict the required number of steps, and where you can't hardcode a fixed path—these can be given to agents, they'll potentially operate for many turns, and you must have some level of trust in their decision-making¹. Anthropic's own research system is this type: research work involves open-ended problems where it's very difficult to predict the required steps in advance. You can't hardcode a fixed path for exploring complex topics, as the process is inherently dynamic and path-dependent⁵.

So "should I move to orchestration" isn't a one-directional progress bar. The 40-module assessment should move toward orchestration because the steps are fixed, just numerous; "should we swap message queue from A to B" shouldn't move toward orchestration because you don't even know how many articles you'll need to read.

Put costs on the table first

Before you start learning the five patterns, open the ledger.

Agentic systems often trade latency and cost for better task performance, and you should consider when this tradeoff makes sense¹. Not one word here is rhetoric: it's describing an exchange.

How expensive? Anthropic provides a set of observations from their own data: agents typically use about 4× more tokens than chat interactions, and multi-agent systems use about 15× more tokens than chats⁵. So their conclusion is—for economic viability, multi-agent systems require tasks where the value of the task is high enough to pay for the increased performance⁵.

Notice the context of this number: it comes from their own data, not a universal benchmark, and not "all orchestration approaches cost 15× more." But the direction is clear: every step you take toward "more agents, more parallelism," the bill jumps up a tier. Quick boundary: this multiplier measures multi-agent systems relative to chat, not the price tag of "moving the plan into code" itself—primary materials never gave a standalone cost figure for orchestration scripts. This is also why those 40 modules are worth moving up while 12 renamings aren't—not because one is "complex" and one is "simple," but because a migration assessment that saves two weeks of rework can afford this cost.

The next five lessons

The rest of this course starts with the lightest shape and builds toward composition:

• Lesson 2: Chaining and Routing: Break a task into fixed steps with programmatic gates between each; classify then dispatch to specialized prompts. The lightest form of "plan in code."
• Lesson 3: Parallelization: Sectioning (split into independent subtasks run in parallel) and voting (run the same task multiple times for diverse outputs), plus how to aggregate results in code.
• Lesson 4: Orchestrator-Workers: A central LLM dynamically breaks down tasks, delegates to worker LLMs, and synthesizes their results. The key difference: subtasks aren't predefined.
• Lesson 5: Evaluation loops, and composing patterns into graphs: Check-fix-recheck until it passes or stops making progress, then stitch the earlier patterns together. That lesson will state it again: "graph" is this course's own visualization.
• Lesson 6: Hands-on: Upgrade that single-loop harness from course 7 in this series into a deterministic orchestration script.

This pattern taxonomy isn't a 2024 relic: the current Claude platform's multi-agent orchestration docs still independently name Parallelization (fan out independent subtasks simultaneously, coordinator synthesizes results), Specialization (route to agents with domain-focused system prompts and tools), Escalation (consult a more capable agent or model for a subset of complex subtasks)⁶. The skin changed, the skeleton is the same.

One more thing about how this course divides from the previous two: course 2 in this series taught the concept of workflows—steps, state, branching, diagram-level understanding; course 6 in this series taught multi-agent collaboration division of labor and communication—fan out, delegation prompts being self-contained, producer-reviewer. This course doesn't reteach either. What it covers is the control flow itself: who counts, who branches, where intermediate results go, what happens when it crashes. Quick vocabulary bridge: what course 6 in this series called "producer-reviewer," primary materials call evaluator-optimizer¹, and Claude Code's workflow docs call having independent agents adversarially review each other's findings³.

Proportionality: everything must pass "measurable improvement"

This course will teach you five patterns and a bunch of composition methods. They all share one admission line, and the original text is unambiguous: These building blocks aren't prescriptive. They're common patterns that developers can shape and combine to fit different use cases. The key to success, as with any LLM features, is measuring performance and iterating on implementations. To repeat: you should consider adding complexity only when it demonstrably improves outcomes¹.

"Demonstrably improves outcomes" requires concrete support, which comes from the evaluations of course 10 and the observability of course 11 in this series: without an eval set, you can't say clearly "did adding routing actually make things better." The ending of the canonical text follows this order: start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short¹.

So after learning each pattern, ask yourself: Can I produce a number showing results got better after adding it? If you can't, don't add it yet.

💻 Exercises

Recap

• That while you wrote in course 7 of this series is an agent—agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop¹.
• These variations are collectively called agentic systems, within which an architectural distinction is drawn: workflows are systems where LLMs and tools are orchestrated through predefined code paths, agents are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks¹.
• The axis that distinguishes them is "who holds the plan": a workflow moves the plan into code, the script itself holds the loop, the branching, and the intermediate results, so Claude's context holds only the final answer³. This course calls this axis the "determinism spectrum" and calls lesson 5's composition visualization "graphs"—both terms are this course's own metaphors and don't appear in primary materials.
• Triggers for moving up: the task needs more agents than one conversation can coordinate, or you want the orchestration codified as a script you can read and rerun³; when the task is larger than one agent can hold in context, or when the same step needs to run across many items³; when a side task would flood your main conversation with content you won't reference again⁴.
• Conditions for staying put: find the simplest solution possible, add complexity only when needed, which might mean not building agentic systems at all¹; for many applications, optimizing single LLM calls with retrieval and in-context examples is usually enough¹; domains requiring shared context or many inter-agent dependencies today are not a good fit for multi-agent, most coding tasks involve fewer truly parallelizable tasks than research⁵.
• Keep with autonomous loops: open-ended problems, difficult to predict step count, can't hardcode a fixed path¹—research-type work is typical, the process is inherently dynamic and path-dependent⁵.
• Get the bill first: agentic systems often trade latency and cost for better task performance¹; in their own data, agents use about 4× more tokens than chat, multi-agent about 15×, economic viability requires the task value to support that improvement⁵.
• Everything this course teaches must pass the same gate: add complexity only when it demonstrably improves outcomes¹; start with simple prompts, optimize them with comprehensive evaluation, add multi-step agentic systems only when simpler solutions fall short¹.

>> Lesson 2: Chain It, Route It: Chaining and Routing