The 5 concepts behind the build

Tap any concept to jump to its 5-card cluster. The actual lab steps live on desktop.

• 1What You'll BuildThe coordinator + subagents pattern, end to end
• 2Architecture OverviewTool boundaries and explicit context passing
• 3The Subagent PatternFocused specialists with isolated context windows
• 4The Coordinator PatternRouting, handoffs, and result synthesis
• 5Going FurtherStreaming, parallelism, evals, and SDK migration

One mind cannot juggle every job.

The desktop lab assembles a complete UCC filing research system: a coordinator agent at the top, two specialist subagents below it (research and risk analysis), and three tools split between them. The user asks one question; the coordinator decides who handles what, hands them a task, collects results, and writes a single answer.

This is the smallest pattern that earns the name "agent system." It is bigger than a single ReAct loop and smaller than a fleet of agents on a queue. Once you have built it once, every more complex architecture is the same pattern repeated — more spokes, more layers, same hub.

You learn it because production agents almost never live in a single loop. The moment you cross 4–5 tools, accuracy collapses and you reach for this pattern.

The law-firm partner

BEFORE: Imagine a solo lawyer doing every part of a case — intake interviews, discovery, motion drafting, witness prep, courtroom argument. One brain, one calendar, one mouth.

PAIN: Above a certain caseload, quality drops. The lawyer forgets which client said what, mixes up filing deadlines across jurisdictions, and pastes boilerplate from the wrong matter. Every additional skill steals attention from the others.

MAPPING: A real firm has a lead partner who interviews the client, then delegates: "Associate, run discovery on this entity. Paralegal, pull all liens in Texas. Bring the results back to me, I'll synthesize the strategy memo." That partner is the coordinator. Each specialist runs their job in isolation and returns a clean deliverable. The partner stitches it into one answer for the client.

Five moving parts

1. Coordinator agentOwns the user-facing conversation. Decides which subagent to call. Synthesizes their structured outputs into one coherent reply.
2. Research subagentSpecialist for finding UCC filings. Has only two tools: search_filings, get_filing_details. Returns structured JSON.
3. Analysis subagentSpecialist for risk scoring. Has one tool: check_risk_score. Receives explicit context from the coordinator (debtor IDs, filing summaries).
4. Mock data layerRealistic sample filings — just enough variety to exercise every branch. Replaces a real DB so you can build without infra.
5. Test harnessHappy path, edge cases, error scenarios. Proves each part works in isolation before you wire them together.

Pseudocode

The whole system in one shape — coordinator routes, subagents specialize:

# THE WHOLE SYSTEM IN ~12 LINES

FUNCTION ucc_research_system(user_question):
  # 1. Coordinator decides what to do
  plan = coordinator.understand(user_question)

  # 2. Coordinator delegates to specialists, in order
  research = run_subagent("research",
                         task=plan.research_brief)

  risk     = run_subagent("analysis",
                         task=plan.risk_brief
                              + research.summary)  # explicit handoff

  # 3. Coordinator stitches a single answer
  RETURN coordinator.synthesize(research, risk)

The lab spends most of its time on three things: what each subagent receives, what each returns, and how the coordinator threads results together. Get those right and the rest is plumbing.

Misconceptions

Tool boundaries shape the agents.

Architecture in this system means one decision repeated three times: which tool belongs to which agent. The coordinator gets delegation tools (call research, call analysis). The research subagent gets search tools. The analysis subagent gets scoring tools. Nothing overlaps.

The other half of architecture is the context pipe. Each subagent starts with a blank context window. The only thing it knows about the world is whatever the coordinator types into the task prompt. So the architecture isn't just "who has which tools" — it's also "who explicitly hands what to whom."

Get tool boundaries right and the agents stay focused. Get the context pipe right and they actually cooperate.

The IVR-routed call centre

BEFORE: Pre-IVR call centres had one operator handling every call — billing, tech support, returns, scheduling. That operator had to know everything and toggle between five different systems while you waited on hold.

PAIN: Slow and error-prone. Add a sixth product line and the wheels come off — wrong manual, mixed-up customers, forgotten context. Same failure mode as a single agent with too many tools.

MAPPING: Modern call centres route you to a specialist: "Press 1 for billing, press 2 for tech support." The IVR is the coordinator. Each specialist sees only their script and tools (their tool boundary) and gets a clean transfer summary from the previous agent (the context pipe). Your agent system has the same shape: routing at the front, specialists in the middle, explicit context handoffs along the way.

The three design decisions

1. Why split when 3 tools fit on one agent?Because the pattern matters more than the count. Tool selection accuracy degrades above 4–5 tools per agent. Establishing the split now means the system holds up at 10, 20, 50 tools without a rewrite.
2. Why pass context explicitly?Subagents start with a blank context window. They never see the coordinator's chat history. If the user said "their TX filings" and the coordinator forwards that raw, the subagent has no clue who "their" is. The coordinator must resolve every reference and pack it into the task string.
3. Why structured results, not prose?So the coordinator can pull values reliably. research.debtor_id is a field lookup. Trying to regex "Acme's debtor ID is ACME-001" out of a paragraph breaks the moment Claude rephrases. JSON in, JSON out.

Three decisions. Every other architectural question in the lab is a corollary of one of them.

When to split into subagents

# Should this be one agent or many?

IF tool_count <= 3 AND tools share one domain:
  USE single agent           # cheaper, faster, simpler

ELIF tool_count IN 4..5 AND domains overlap:
  USE single agent
  PLAN the split for v2     # write subagent boundaries now

ELIF tool_count >= 5 OR domains diverge:
  USE coordinator + subagents # this lab
  # 1 spec per subagent, 1-3 tools each

ELIF subagent_count > 5:
  GO hierarchical          # sub-coordinators per group
  # avoids the same selection problem at the next level

Heuristic: if a teammate could explain the agent's job in one sentence, it's well-scoped. If you need three sentences and a "but," split it.

Misconceptions

A subagent is a fresh, focused agent.

A subagent is not a sub-prompt or a function call — it's a complete agent invocation with its own system prompt, its own small tool set, and a brand-new context window. It runs its own ReAct-style loop until it has an answer, then returns that answer to whoever called it.

The key word is focused. The research subagent's system prompt says "you find UCC filings" and lists two tools. It does not know about risk scoring; the tool isn't even in its schema. That tight scope means better tool selection, cleaner context, and no domain bleed. Each subagent is a one-job specialist by construction.

The contractor with a sealed envelope

BEFORE: Imagine a contractor who shows up at a job site, opens whatever's already there, fixes whatever they want, and signs it off. They've seen everything you've ever done; they assume context that may not be relevant.

PAIN: Inconsistent work. The contractor "helps" by touching things outside the brief. They overhear a conversation about a different job and apply that decision to this one. You can't audit what they did because it leaks across boundaries.

MAPPING: A subagent is the opposite contractor — they arrive on site with a sealed envelope. The envelope contains the entire brief: what to do, what tools they're allowed to use, what known facts to assume. They never see anything outside that envelope. When they're done, they slide a signed report back. Auditable, repeatable, no bleed.

What runs inside a subagent

1. Receive taskThe coordinator passes one string: a fully self-contained brief. "Find all UCC filings for Acme Corporation in TX" — not "look up their TX filings."
2. Boot fresh contextBuild a brand-new message list: [{system: spec.role}, {user: task}]. Nothing else. No history, no shared state.
3. Run the inner ReAct loopCall Claude with the subagent's specialist system prompt and small tool set. If stop_reason is "tool_use", run the tool, append the result, repeat. If "end_turn", exit.
4. Parse and returnExtract the final text. Try JSON.parse; if it fails, wrap as {"summary": text}. Return the structured object back to the coordinator.
5. Cap with max_turnsA safety limit (e.g., 6 turns). If the subagent loops without finishing, return an error rather than burning your API quota.

Pseudocode

One generic run_subagent handles every specialist — it's the spec that varies, not the loop:

# Each subagent has a spec (declarative, in a file)
research_spec = {
  role:  "You find UCC filings. Return JSON.",
  tools: [search_filings, get_filing_details],
  max_turns: 6
}

FUNCTION run_subagent(spec, task_string):
  # Fresh, isolated context every call
  ctx = [system: spec.role, user: task_string]

  FOR turn IN 1..spec.max_turns:
    reply = CALL Claude(ctx, tools=spec.tools)

    IF reply.stop_reason == "tool_use":
      FOR call IN reply.tool_uses:
        result = run_tool(call.name, call.input)
        ctx.append(tool_result(call.id, result))
      CONTINUE

    IF reply.stop_reason == "end_turn":
      RETURN parse_json(reply.text)
                  or {summary: reply.text}

  RETURN {error: "max turns reached"}

Same shape as a single ReAct loop — just packaged so it can be called by another agent. In Claude Code style, the spec lives at .claude/agents/<name>.md: declarative, version-controlled, no glue code per subagent.

Misconceptions

The coordinator's tools are other agents.

The coordinator does not search filings. It does not score risk. It has zero domain tools. Its tools are delegation tools: research_filings(task) and analyze_risk(task). Each one launches a subagent and returns its structured result.

From Claude's perspective, calling a subagent looks identical to calling any other tool — same JSON Schema, same stop_reason == "tool_use" dance. The difference is what happens server-side: instead of querying a database, your code spins up a complete subagent invocation, runs its inner loop, and pipes the result back.

So the coordinator is doing four things in a loop: route, brief, collect, synthesize. That's the entire pattern.

The newsroom editor

BEFORE: A reporter who tries to do everything — investigate, photograph, fact-check, write headlines, lay out the page, copy-edit. The article ships, but it's mediocre on every axis.

PAIN: Time fragments across crafts. The reporter forgets the lead while picking a font. Quality suffers in proportion to the number of hats.

MAPPING: An editor doesn't write or take photos — they assign. "Reporter, get the quotes by 4pm. Photographer, headshot of the source. Fact-checker, verify the timeline. Bring it back to me, I'll wire it together for the front page." That's the coordinator: a router, briefer, collector, and synthesizer. Their value is judgment, not labour.

Route, brief, collect, synthesize

1. RouteRead the user's question and decide which subagent(s) to call and in what order. "Risk for Acme?" → research first, then analysis.
2. BriefBuild the task string for each subagent. Resolve pronouns ("their" → "Acme Corporation"). Pack in IDs, scope, and known facts. The subagent will see only what's in this string.
3. CollectReceive the structured result. Validate status == "success". Pull the fields you need (debtor_id, summary) for the next handoff. Handle errors gracefully — partial results beat no results.
4. SynthesizeCombine results into one user-facing answer. Cite specifics (filing numbers, dollar amounts, risk scores). Be explicit about anything that failed.

Multi-turn bonus: the coordinator also owns conversation history. Pronoun resolution lives at this layer, never inside the subagents.

Pseudocode

The coordinator's tools are the subagents:

# Coordinator tools = delegation calls, not DB queries
COORDINATOR_TOOLS = [
  {name: "research_filings", input: {task: string}},
  {name: "analyze_risk",    input: {task: string}}
]

FUNCTION dispatch(tool_name, tool_input):
  task = tool_input.task        # the brief
  IF tool_name == "research_filings":
    RETURN run_subagent(research_spec, task)
  IF tool_name == "analyze_risk":
    RETURN run_subagent(analysis_spec, task)

FUNCTION coordinator(user_msg, history):
  ctx = history + [user: user_msg]
  LOOP:
    reply = CALL Claude(ctx,
                  system=COORDINATOR_PROMPT,
                  tools=COORDINATOR_TOOLS)

    IF reply.stop_reason == "tool_use":
      FOR call IN reply.tool_uses:
        result = dispatch(call.name, call.input)
        ctx.append(tool_result(call.id, result))
      CONTINUE

    IF reply.stop_reason == "end_turn":
      RETURN reply.text, ctx

Notice: identical loop shape to a regular tool-using agent. Subagents are tools that happen to be smart.

Misconceptions

The lab system is the engine, not the car.

What you build in the lab works on your laptop. It can answer real-ish questions about real-ish data with real Claude calls. But it's missing every layer that makes an agent safe, observable, and shippable: input validation, output guardrails, tracing, rate limits, persistence, deployment, evals.

"Going Further" is the bridge from "works in dev" to "runs in production." Some of it lives in later modules (M16 input guardrails, M19 tracing, M21 deployment). Some are stretch goals you can layer on top of the lab today — parallel subagents, an entity-resolution specialist, a caching layer, an interactive CLI.

The most important "going further" is the architectural one: rebuild this same agent in M26 using the Agent SDK. About 50 lines instead of 250. Same output, one fifth the code, all the abstractions you just wrote by hand.

The car you built in your driveway

BEFORE: You spent the weekend assembling a working engine in your garage. It turns over. The pistons fire in the right order. You put it on a wooden dolly and pushed it up the driveway under its own power. Real progress.

PAIN: But it's not a car. There are no seatbelts, no brakes, no dashboard, no headlights, no chassis, no road. Drive it as-is and the first bump kills you.

MAPPING: The lab system is the engine. M16/M17 add seatbelts (guardrails). M19/M20 add the dashboard (tracing and monitoring). M21/M22 add chassis and road (deployment). The capstone bolts them together. Don't skip the engine — but don't try to drive it home either.

Five practical extensions

1. Add an entity-resolution subagentNormalize "Acme Corp", "ACME CORPORATION", "Acme Inc" to one canonical entity. Wire it in before research, so downstream subagents always work with a clean ID.
2. Run subagents in parallelWhen research and analysis are independent (different entities, different jurisdictions), fan out with asyncio.gather / Promise.all. Latency drops with no logic change.
3. Cache subagent resultsRepeated queries for the same debtor shouldn't hit the API twice. A simple dict/Map keyed on (subagent, task_hash) saves money and time.
4. Stream tokens as they arriveWrap each Claude call with stream=True. The user sees text appear in real time instead of waiting 60 seconds for a synthesized blob.
5. Build an eval suiteCodify your test cases as graded scenarios. "For 'risk on Acme', expect HIGH and at least 2 cited filings." Run on every code change to catch regressions.

Each extension preserves the hub-and-spoke shape — you're adding capabilities, not changing the architecture.

What to add, when

# From lab system to production agent

IF users are anyone other than you:
  ADD input guardrails (M16)
  # prompt injection, scope checks, PII

IF outputs go to a UI or downstream system:
  ADD output guardrails (M17)
  # schema validation, hallucination checks

IF bugs need to be diagnosed without re-running:
  ADD tracing & logs (M19, M20)
  # every coordinator decision, every subagent call

IF users are not on your laptop:
  ADD an HTTP API (M21) AND deploy (M22)

IF the code is >200 lines of agent loop:
  CONSIDER Agent SDK (M26)
  # same agent, ~50 lines, hooks & sessions built in

IF you ship to prod and need to refactor confidently:
  ADD evals (M18)
  # otherwise every change is a coin flip

Add layers in the order failures hurt you. Most teams hit guardrails first, observability second, deployment third.

Misconceptions

One question per concept

Tap a card to reveal the answer.