Task statement 1.1 · Agents and workflows

1.1 · Agent Architecture

In Shelfwise, the course example, one agent answers each stock question. It runs on the Agent SDK and reaches the feed through one MCP server. Architecture decides who chooses the next step, and Shelfwise keeps that choice inside one agent.

watch the video

Part 1 of 3 · Workflow, one agent or subagents? How to pick · 3:50

Agent architecture: 3 parts · 14 min, with chapters

Why it's tested

The tempting design copies an org chart, with a coordinator agent and a specialist helper agent for each kind of work. It fails on cost and debugging, because every helper starts fresh and makes its own requests, so in Anthropic's research system a multi-agent run used about 15 times the tokens of a chat. When the steps share context, splitting them only adds handoffs where facts get lost.

Start hereThree terms this section adds

workflow
LLM calls and tools run along code paths you wrote in advance, so each route is fixed in code before it runs.
agent
Claude directs its own process, choosing each tool call from the last result until it judges the task done.
subagent
An agent another agent starts for one subtask. It works in its own context window and returns only its final message.

KnowledgeWorkflow versus agent: the decision criteria

Anthropic's "Building effective agents" draws the line by who controls the path. In a workflow, LLM calls and tools follow predefined code paths, so you can read, test and price each route in advance. In an agent, Claude calls a tool, reads the result and picks the next step until it is done, so the route and the number of requests change with each input. That flexibility costs latency and money, and an early mistake can compound through later steps. Choosing between them therefore weighs predictability against flexibility: a workflow gives consistent results on a well-defined task, and an agent fits when the steps depend on results not yet seen.

The guidance also says to start with the simplest solution and add complexity only for a measured gain, which is often one Claude call with retrieval and good examples. Between that call and an agent sit the workflow patterns (prompt chaining, routing, parallelisation, orchestrator-workers and evaluator-optimiser), which 1.3, Agent Patterns and Frameworks, teaches. Orchestrator-workers matters here, because an LLM splits the task into workers' parts at run time, which is where hierarchies begin.

Interactive · who decides the next step in each architecture

Three architectures side by side, each read from top to bottom. Workflow: your code runs an LLM call, a tool and a second LLM call in a fixed order. One agent: inside one context window, Claude chooses a tool, reads its result and loops until it ends the turn. Coordinator and subagents: the coordinator, in its own context window, sends a prompt string to each of two subagents outside it, each in its own context window, and each returns only its final message for the coordinator to combine. Workflow your code: step list fixed order step 1: LLM call step 2: tool, called by code step 3: LLM call path fixed in code ROUTE SET BEFORE IT RUNS One agent request ONE CONTEXT WINDOW Claude next step? tool result → loop ends the turn answer Claude picks each step REQUESTS VARY PER INPUT Coordinator and subagents coordinator splits task combine check gaps subagent A subagent B prompt string final message COORDINATOR'S WINDOW subagents run at once EACH IN ITS OWN CONTEXT WINDOW

Choose an architecture to see who decides each step and what it costs.

Workflow: your code fixes the steps and their order, so each route is fixed in code before it runs, at a cost you can predict, but it cannot add a step the input turns out to need.

One agent: Claude chooses each tool call from what the last result showed, looping in one context window until it ends the turn, so the route and the number of requests vary with the input.

Coordinator and subagents: the coordinator splits the task and passes each subagent only a prompt string; each works in its own context window, at the same time as the others, and returns only its final message.

Each column reads downward. Blue is input or your code, amber is a Claude call, green is a tool or a subagent's work, and a dashed ember border is a context window.

KnowledgeManager/supervisor hierarchies

A manager/supervisor hierarchy puts one coordinating agent above the agents that do the work. Anthropic's research system calls it the lead agent, which analyses the request, plans an approach and spawns subagents to explore parts of it at once. The structure is a split of ownership: the coordinator owns the whole task and the final answer, while each subagent owns one bounded piece and reports back only its result. A handoff runs in four steps:

  1. The coordinator sizes the request: in Anthropic's system a simple fact takes one agent, a comparison 2–4 subagents, and only broad research more than ten.
  2. It writes one brief per subagent: an objective, an output format, the tools and sources to use, and the subtask's boundaries.
  3. It sends the brief through the Agent SDK's Agent tool. Unless the subagent is a fork (a copy of the coordinator's conversation), the brief is all it receives.
  4. Each subagent returns a condensed final message, and the coordinator combines the results, checks for gaps, and delegates again or answers.

Each step has a failure mode. The brief "research the semiconductor shortage" led Anthropic's subagents to cover the same ground twice, because no subagent sees another's assignment. A fact left out of the brief never reaches a non-fork subagent, which answers without it and raises no error. The lead agent also waits for each group of subagents, so the slowest one sets the latency.

More precise than the guide. The docs do not say "manager/supervisor hierarchy" (as of 2026-10-04): Anthropic's engineering posts say lead agent or orchestrator, and the Agent SDK docs say main agent and subagent. A subagent can spawn its own, up to three layers deep by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Exam answer: a manager or supervisor is the coordinating agent above its subagents, and the hierarchy can have more than one level.

KnowledgeThe role of subagents in improving task execution

The Agent SDK docs list four ways a subagent improves task execution. Its own context window keeps intermediate tool calls and results out of the parent, so it can read dozens of files and hand back a summary. Several can run at once, so independent subtasks finish in the time of the slowest. Each can carry a specialised system prompt, the instructions sent ahead of the conversation, plus a restricted tool list and its own model. The price, except for a fork, is a fresh start, so the docs advise keeping work in the main conversation when phases share context or latency matters. In Anthropic's research system, subagents beat a single agent by 90.2% on an internal evaluation, using about 15 times a chat's tokens, and the post calls most coding tasks a poor fit. 6.1 covers context isolation, 2.5 why a growing history costs more each turn, and 2.4 the Plan subagent.

SkillWorked example: why Shelfwise stays one agent

Shelfwise's path is short but not fixed. Claude decides which product name in a free-text question to look up, and may look again, in about three requests, which is why the team runs one agent rather than a fixed workflow. A proposal to add a coordinator that hands loosely typed branch names to a subagent shows what a hierarchy would cost. It is hypothetical and was never built:

# proposal (hypothetical, not built): coordinator + branch-name subagent
question: "any 4 mm drill bits at the leeds shop?"
coordinator → Agent("branch-resolver", prompt: "Which branch is 'the leeds shop'?")
  subagent: own system prompt, so it cannot read the agent's cached ≈6,000-token prefix
  returns "Leeds", one word; answer requests ≈3 → 5 or more
# decision: one agent, which reads "the leeds shop" as Leeds inside its own loop

The subagent's result is one word, so its own context window has nothing to keep out of the main one, while its extra requests miss the agent's cache, cost against the $0.01 ceiling and add latency against the 8 s target. Subagents would earn a place only for work that reads far more than it returns, such as a hypothetical weekly review of slow-moving stock across every branch, with each branch's records kept in a subagent's own context window.

Before choosing an architecture, ask: who has to decide the next step? Code can, since every step is known in advance → a workflow, or one call if that is enough. Claude must, since each step depends on the last result → one agent. Claude must, and the work splits into independent parts that read far more than they return → a coordinator with subagents.
Takeaway
  • An agent buys flexibility with latency, cost and the risk of compounding errors.
  • Unless it is a fork, a subagent knows only its brief: objective, output format, sources and boundaries.
  • Subagents can nest three layers deep by default, and a multi-agent run can cost about 15 times a chat's tokens.

check yourself

0 / 3 answered

A city council's planning office wants Claude to answer residents' questions about its 40-page planning guidance, which fits easily in one request, quoting the paragraph each answer relies on. A developer proposes a coordinator agent with zoning, heritage and fees subagents. No design has been tried yet.Which design is the most proportionate place to start?

Select one.

A due-diligence tool's lead agent spawns four subagents, each prompted "Review the target's contracts for legal risk." Three of the final messages analyse the same office lease, and none mentions the 14 employment contracts. When one subagent is prompted to review only the employment contracts, it analyses all 14 without error.What is the most likely root cause?

Select one.

A finance team's agent writes a monthly variance report on five regional ledgers. It analyses the regions one after another, so a run takes about 40 minutes, although no region's analysis uses another's. Last month, while only reading a ledger, it also posted a correcting journal entry with a tool it holds for month-end close.Which TWO uses of subagents best cut the run time and stop a reading task from posting entries?

Select two.

sources

  1. Anthropic Engineering, "Building effective agents": workflows orchestrate LLMs and tools "through predefined code paths", agents "dynamically direct their own processes and tool usage"; find the simplest solution and add complexity only when needed; the latency and cost tradeoff; predictability and consistency against flexibility; higher costs and compounding errors; the five workflow patterns. Checked 2026-10-04.
  2. Anthropic Engineering, "How we built our multi-agent research system": the lead agent analyses the query, develops a strategy and spawns subagents that work in parallel in their own context windows and condense their findings; the 90.2% result; about 4 times (agents) and 15 times (multi-agent) the tokens of a chat; shared context, many dependencies and most coding tasks as a poor fit; the semiconductor-shortage duplication and the four-part brief; effort-scaling rules; the lead agent waiting on each group of subagents. Checked 2026-10-04.
  3. Claude Code Docs, "Subagents in the SDK": context isolation, parallelisation, specialised instructions and tool restrictions; the Agent tool; the prompt string as the only content passed from the parent; only the final message returns; the model field; nested subagents and the depth, concurrency and spend caps. Checked 2026-10-04.
  4. Claude Code Docs, "Create custom subagents": each subagent runs in its own context window; nesting up to three layers below the main conversation, set by CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; when to use the main conversation instead, including shared context and latency; a non-fork subagent starts fresh. Checked 2026-10-04.
  5. The branch-name subagent proposal and the weekly stock review are this course's hypothetical extensions of Shelfwise; neither is built.