Agents and workflows

01Workflow or Agent

An agent is software you hand a whole job to. Not one instruction — the job. You give it a goal and a set of tools (search, email, your files, whatever the task needs), and it works in a loop: look at where things stand, decide the next move, make it, look again. It stops when the job is done.

So the first question of any agent build isn’t how. It’s whether. Does this job actually need an agent?

Agents are the expensive option: more moving parts to coordinate, higher running costs, more ways to fail. Sometimes that price is worth paying — for open-ended work where nobody can write the steps down in advance. Most of the time, a simpler fixed setup does the job for a fraction of the cost. Making that call deliberately, before building anything, is the real first design decision.

Here is how to make it. Five tells, each with a workflow answer and an agent answer:

• —The plan. If you can enumerate the exact steps in code, choose a workflow — the code is the plan. If you can give the goal and the tools but not the path, that is agent territory. Discovering the path is what you are paying the model for.
• —The blast radius. When errors are expensive and every step needs its own guardrail, a workflow wins. You wrote the steps, so a gate can sit exactly where the risk is. With an agent the risk moves — the model picks the order — so the safety net has to be the toolset itself. Non-determinism is acceptable when the registered tools bound everything the agent can do.
• —The paper trail. A workflow is easy to watch: every step is a call you can log, trace and alert on with the tooling you already run. An agent needs more than that — what it saw, what it did, why — before you can trust it in production.
• —The inputs. Known, well-constrained inputs — a fixed form, a known format — point to a workflow. Inputs that vary unpredictably in content and structure need something that can absorb the surprise and still act.
• —The rhythm. Same sequence, every run? Workflow. The job demanding creative sequencing, the order of the tools invented as the work unfolds? That is the agent’s home turf.

One ladder sits under all five tells: start with a single call. Add a workflow when the job has steps you can write down. Reach for the agent only when the variability is more than those steps can absorb.

02The five workflow patterns

Anthropic’s engineering writing names five recurring shapes. All of them sit on the same primitive: the augmented LLM. That is a model with retrieval, tools and memory, writing its own search queries, choosing its own tools, deciding which information to keep. The patterns differ in one thing only — how much steering they hand the model. The exam regularly hands you a scenario and asks which shape fits:

• —Prompt chaining — fixed subtasks in sequence. Each call handles the previous output. Programmatic gates check intermediate results between the links. You pay latency for accuracy on decomposable tasks (draft, check, revise).
• —Routing — classify the input first, then hand it to a specialist prompt or model. The exam’s favourite example: easy questions to a small fast model, hard ones to a frontier model, so most tokens bill at the cheaper rate. Precondition: the inputs really do fall into distinct categories, and a classifier can sort them accurately.
• —Parallelization — run several calls at once. Two flavours. Sectioning: independent subtasks run separately and merge in code — answer the customer, then screen the answer for policy. Voting: the same task runs multiple times, for confidence. Splitting concerns across calls improves quality, not just speed.
• —Orchestrator-workers — a central model decomposes the task, delegates pieces to workers it defines itself, then stitches the results together. Use it when you cannot enumerate the subtasks in advance — a refactor that might touch an unknown number of files.
• —Evaluator-optimizer — a generator and a critic loop against each other. It fits when two things hold: answers visibly improve with feedback, and a model can supply that feedback itself.

The sharpest distinguishing question in this cluster: could you write the subtasks down before any input arrives? If yes, parallelization. If the model must invent them per request, orchestrator-workers. The two look identical on a diagram — the exam knows that.

One more layer. Because the orchestrator decides the delegation at runtime, this pattern is already model-driven control — it is where workflows start turning into agents. Managed Agents says as much: when its coordinator delegates, it spawns the worker sessions at runtime, each one context-isolated.

03The agent loop, and four places to run it

Strip the marketing away and an agent is a loop. The model looks at the current state and either asks for a tool or answers. Your harness executes what it asked. The result goes back in. Repeat. One full cycle is a turn. The loop ends only when the model produces a reply with no tool call in it. That — not a message that sounds finished — is the exit condition.

Strip it further and the loop is the pattern. The pattern never changes. Who runs it is an implementation choice, not a design one. Four surfaces, in increasing order of hand-off:

• —The Client SDKs — the raw Messages API. You write the loop yourself. Right when you need exact control over every request.
• —The Claude Agent SDK — a library that runs the Claude Code engine inside your process. It brings built-in file, shell and web tools, permissions, sessions, subagents, hooks and MCP connections. Right when you want the harness but must self-host — say, on your own Kubernetes cluster.
• —Managed Agents — Anthropic hosts the harness and the sandbox both. You define the agent once — model, system prompt, tools, MCP servers — then refer to it by ID, send events in, and stream results back. Right for long-running, asynchronous sessions when you do not want to own sandboxing or session storage.
• —The Claude Code CLI — the same engine, driven by a human in a terminal.

The docs attach a warning to all frameworks, and the exam echoes it. An abstraction that hides prompts and responses invites wrong assumptions about what it does under the hood. If you use a harness, know what code it actually runs.

Managed Agents carries one constraint that decides the question before convenience gets a say. Its sessions are stateful and stored on Anthropic’s side. And the feature is not currently eligible for Zero Data Retention or a HIPAA BAA — current as of September 2026.

Workloads with those requirements stay on the Agent SDK or a raw loop, however well the managed path fits otherwise.

Whichever surface you pick, four jobs are on the list:

• —Register the tools — each with its schema, so the model knows what exists and how to call it.
• —Scope the system prompt — broad prompts make tool routing wander; a prompt that names the one task and its tools makes routing consistent.
• —Execute every tool call — the model issues the request; something you wrote runs it and returns the result.
• —Define the exit — before the loop runs, not during.

That last job earns its own paragraph. The loop ends when the model replies with no tool call — mechanically true, but "the model stopped" is not an exit condition. With no finish line you set, the model can keep calling tools past the point of usefulness. Decide what done means before you run, and make the loop enforce it.

Last wiring question: where does a human check fit? Ask what the worst outcome is if this step runs unchecked. Three insertion points cover most of it:

• —Before a destructive call — a write, a delete, a send. A wrong move here cannot be undone.
• —After the plan, before execution. A wrong plan carried out perfectly is still wrong.
• —On unexpected output — an error flag, an empty result, a value out of bounds. These are the failures a retry cannot fix.

04Reading the stream

The Agent SDK’s query interface yields a stream of typed messages. Five kinds matter:

• —SystemMessage — lifecycle metadata. An "init" message at start, a "compact_boundary" message after the conversation has been compacted.
• —AssistantMessage — the model’s output. One message per content block (text blocks, tool-use blocks); blocks from the same response share a message ID.
• —UserMessage — tool results flowing back to the model, plus any human input injected mid-loop.
• —StreamEvent — the incremental deltas, if you asked for partial message streaming.
• —ResultMessage — the end of the loop: final text, token usage, cost, session ID. Check its subtype — "success" is not the only value.

Two implementation details that become exam questions. First: the result message is not guaranteed to be the last item in the stream. Trailing system events can follow, so iterate to completion rather than breaking early.

Second: in the TypeScript SDK the content blocks sit one level deeper than in Python — message.message.content, not message.content. The hook events on offer differ between the two SDK languages too; not every event exists in both (current as of September 2026).

05How tool use actually executes

The contract the exam wants you to internalise: Claude never executes anything. It emits a structured request — a tool name plus arguments. Something else runs it. That "something else" comes in exactly three flavours:

• —User-defined tools — you write the schema, your code executes the call, your code returns the tool_result. Claude sees only the schema and the result, never the implementation.
• —Anthropic-schemas tools — bash, text_editor, memory and kin. Anthropic publishes the schema. The models are trained on those exact signatures, which makes the calls more reliable — but your application still executes them. This is the row people get wrong.
• —Server tools — web_search, web_fetch, code_execution, tool_search. A roster that grows: current as of September 2026. Defined by Anthropic, executed on Anthropic’s infrastructure. You never build a tool_result for these; the response already contains the result.

With client-side tools, your code keys on the response’s stop_reason. When it reads "tool_use", execute the requested tools. Append the results as tool_result blocks in a new user message. Send the conversation back. Keep looping while stop_reason says "tool_use". The other stop reasons are "end_turn", "max_tokens", "stop_sequence" and "refusal".

The subtle one is "pause_turn". Server tools run in a loop of their own inside Anthropic’s infrastructure, and that loop has an iteration limit. Hit the limit mid-work and you get pause_turn — the work is not finished. Resend the conversation as-is, paused response included, and the model continues.

One related rule. If the model requests a server tool and one of your client tools in the same parallel group, the server tool only runs after you have returned your tool’s results.

06Subagents

A subagent is a Claude instance with its own conversation, its own prompt and optionally a restricted toolset, spawned by a parent. In the Agent SDK you define them three ways: in code, as markdown files in .claude/agents/, or by using the built-in general-purpose subagent. Defining one in code means three fields. A description, telling the model when to reach for it. A prompt, acting as its system prompt. Optional tool and model overrides. Four reasons to reach for one:

• —Context isolation — the subagent’s reads and reasoning happen in its own window. Only its final message returns to the parent. That’s a context-management move as much as a specialisation one.
• —Parallelism — independent subagents (a style checker, a security scan, a coverage check) run concurrently.
• —Specialised instructions — a system prompt tuned to one job.
• —Tool restriction — a documentation reviewer limited to read-only tools physically cannot edit files, whatever the task tempts it to do.

07One page to revise from

Six sections of prose sit above this line. Here is the same domain as three tables — the distinction every scenario question turns on, the five patterns the exam names, and the four surfaces it asks you to choose between. If you reread one thing the night before, reread this.

One line to draw through all of it: the ideas are stable, the product details are not. Who decides the next step, the five patterns, the loop, the model-requests-and-harness-executes split — those will outlive any product change. The dated facts — the Managed Agents compliance list, the server-tool roster, which hook events exist in which SDK language — were checked against the official documentation in September 2026, and they are the kind of detail that can change between exam editions. Anything on this page stamped "current as of" falls in that second group; re-check those against the live docs the week you sit the exam.

08The traps in this domain

• —"An agent is an upgrade over a workflow" — no. The simplest working solution wins; agents pay for flexibility with latency and cost.
• —"Orchestrator-workers is parallelization with a new name" — no. Parallelization’s subtasks are fixed in advance; an orchestrator invents them per input.
• —"Claude runs the tools" — never. It requests; your code or Anthropic’s servers execute.
• —"Any stop_reason other than tool_use means done" — pause_turn means unfinished server-tool work; resend and continue.
• —"The result message is the last stream item" — iterate the stream to completion and check the subtype.
• —"The model will stop when it’s done" — no. With no exit condition you defined, it can keep calling tools past the point of usefulness. Define done, in code.

09Check yourself

Three questions, in roughly the exam’s register. Each one expands to show the answer and — more usefully — why the wrong options are wrong.