SyntaxPilot
Courses/AI: Zero to Agents/Lesson 33
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

AI: Zero to Agents · Lesson 33 of 40

Multi-agent systems

queued

These are the notes for AI episode 33. In episode 32 we built one complete agent. Some jobs are too big for one agent: its context fills up and the oldest facts fall out. Here you invent teams of agents: a lead (orchestrator) that splits the job, workers (subagents) with their own fresh context, clear task cards so they don't duplicate work, parallel workers, and handoffs guarded by a contract and a checker. Every Python example runs as-is in the SyntaxPilot compiler; outputs are real (Python 3.13). The agents are toys standing in for LLM calls.

Real-life example: a busy restaurant kitchen

In the kitchen In a multi-agent system
The head chef reads the order and splits it the lead agent (orchestrator)
Tandoor, curry and dessert cooks, each at a station worker agents (subagents), each with its own context
The order slip: dish, table, "no onion" a task card: objective, output, boundaries
The chef checks every plate at the pass a checker before anything goes out

Problem 1: one agent, one growing history

One agent plans Ravi's whole Goa trip, and every search result piles into one history. Our toy model can see only 60 words; real models see far more (episode 16: the context window), but real web pages are far longer too.

CONTEXT_LIMIT = 60                     # toy model: it can see only 60 words
def search(topic):                     # every search returns a long page
    return f"{topic}: " + "details " * 25

history = ["Plan Ravi's Goa trip: train, hotel, food"]
for topic in ["train 8 Nov", "hotel near Baga", "food near Baga"]:
    history.append(search(topic))      # ONE agent, ONE growing history

words = " ".join(history).split()
seen = " ".join(words[-CONTEXT_LIMIT:])   # the oldest words fall out
print("history:", len(words), "words. The model sees the last", CONTEXT_LIMIT)
for part in ["train", "hotel", "food"]:
    print(f"  {part:5} still in view? {part in seen}")

Output:

history: 91 words. The model sees the last 60
  train still in view? False
  hotel still in view? True
  food  still in view? True

The train fell out of view. The bigger the job, the more one agent forgets, or the more it pays to remember everything.

The fix: a lead and workers (orchestrator-worker)

The lead splits the job into tasks. Each worker starts with a fresh context (just its task and its own search) and sends back only a short summary.

def search(topic): return f"{topic}: " + "details " * 25

def worker(task):                      # a subagent with its OWN fresh context
    context = [task, search(task)]
    used = len(" ".join(context).split())
    summary = f"{task} -> best option picked"   # toy LLM: a short summary
    return summary, used

def lead(goal):                        # the orchestrator: split, send, combine
    tasks = ["train Mumbai to Goa 8 Nov", "hotel near Baga 2 nights",
             "food near Baga"]
    results = [worker(t) for t in tasks]
    for summary, used in results:
        print(f"worker saw {used:2} words | {summary}")
    total = sum(len(s.split()) for s, _ in results)
    print(f"lead reads only {total} words of summaries for: {goal}")

lead("Ravi's Goa trip")

Output:

worker saw 37 words | train Mumbai to Goa 8 Nov -> best option picked
worker saw 35 words | hotel near Baga 2 nights -> best option picked
worker saw 31 words | food near Baga -> best option picked
lead reads only 26 words of summaries for: Ravi's Goa trip
                 ┌──▶ worker: train  (own context) ──┐
goal ──▶ LEAD ───┼──▶ worker: hotel  (own context) ──┼──▶ LEAD combines summaries ──▶ answer
                 └──▶ worker: food   (own context) ──┘

In the real world

In June 2025 Anthropic described how they built Claude's Research feature: a lead agent plans, starts subagents that search in parallel, and combines their findings. They call it an orchestrator-worker pattern. With Claude Opus 4 as the lead and Claude Sonnet 4 subagents, the system outperformed a single Claude Opus 4 agent by 90.2% on their internal research evaluation.

Problem 2: vague instructions make workers duplicate work

The workers can't see each other or the lead's plan. Vague tasks get guessed.

def worker(task):                      # toy subagent: guesses when unclear
    for job in ["train", "hotel", "food"]:
        if job in task:
            return f"searched {job}s"
    return "searched hotels"           # vague task? it does the popular thing

tasks = ["research the Goa trip",      # the lead's lazy instructions
         "look into Goa options",
         "find hotels in Goa"]
done = [worker(t) for t in tasks]
for t, d in zip(tasks, done):
    print(f"{t:24} -> {d}")
for job in ["train", "hotel", "food"]:
    print(f"{job:5}: done {sum(job in d for d in done)} time(s)")

Output:

research the Goa trip    -> searched hotels
look into Goa options    -> searched hotels
find hotels in Goa       -> searched hotels
train: done 0 time(s)
hotel: done 3 time(s)
food : done 0 time(s)

Anthropic saw the same thing: with vague instructions, subagents misinterpreted the task, and in one example two subagents duplicated the same research "without an effective division of labor".

The fix: task cards

def worker(card):                      # same toy subagent
    return f"{card['job']:5} worker: {card['objective']} -> {card['output']}"

CARDS = [                              # a clear task card for each worker
  {"job": "train", "objective": "Mumbai to Goa on 8 Nov",
   "output": "train no, time, fare", "not": "hotels or food"},
  {"job": "hotel", "objective": "near Baga, 8-10 Nov, under Rs 3000",
   "output": "name, price, rating", "not": "trains or food"},
  {"job": "food",  "objective": "veg places near Baga",
   "output": "3 names with prices", "not": "hotels or trains"},
]
for card in CARDS:
    print(worker(card))

Output:

train worker: Mumbai to Goa on 8 Nov -> train no, time, fare
hotel worker: near Baga, 8-10 Nov, under Rs 3000 -> name, price, rating
food  worker: veg places near Baga -> 3 names with prices

Anthropic's rule: "Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries."

Task card field Example (hotel worker)
Objective near Baga, 8-10 Nov, under Rs 3000
Output format name, price, rating
Tools / sources hotel search tool, reviews
Boundaries not trains or food

Problem 3 and the fix: workers in parallel

Each worker mostly waits (on the web, on the model). Independent tasks can run at the same time; here ThreadPoolExecutor runs three workers together.

import time
from concurrent.futures import ThreadPoolExecutor

def worker(task):                      # each subagent waits ~1 s on the web
    time.sleep(1)
    return f"{task}: done"
tasks = ["train", "hotel", "food"]

start = time.time()
one_by_one = [worker(t) for t in tasks]
print(f"one by one : {time.time() - start:.1f} s")

start = time.time()
with ThreadPoolExecutor() as pool:     # all three at the same time
    together = list(pool.map(worker, tasks))
print(f"in parallel: {time.time() - start:.1f} s", together)

Output:

one by one : 3.0 s
in parallel: 1.0 s ['train: done', 'hotel: done', 'food: done']

Parallel only works when tasks are independent. If a task needs another's answer (book the hotel near the station the train arrives at), it must wait.

Problem 4: one failed worker sinks the team

With many workers, sooner or later one fails: a website times out, a tool errors. pool.map passes that error straight up, and every result is lost.

from concurrent.futures import ThreadPoolExecutor

def worker(task):                      # toy subagent
    if task == "hotel":
        raise TimeoutError("hotel site did not answer in 30 s")
    return f"{task}: done"

with ThreadPoolExecutor() as pool:
    results = list(pool.map(worker, ["train", "hotel", "food"]))
print(results)

Output:

Traceback (most recent call last):
  File "main.py", line 9, in <module>
    results = list(pool.map(worker, ["train", "hotel", "food"]))
  File "/usr/lib/python3.13/concurrent/futures/_base.py", line 625, in result_iterator
    yield _result_or_cancel(fs.pop())
          ~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/usr/lib/python3.13/concurrent/futures/_base.py", line 318, in _result_or_cancel
    return fut.result(timeout)
           ~~~~~~~~~~^^^^^^^^^
  File "/usr/lib/python3.13/concurrent/futures/_base.py", line 453, in result
    return self.__get_result()
           ~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3.13/concurrent/futures/_base.py", line 402, in __get_result
    raise self._exception
  File "/usr/lib/python3.13/concurrent/futures/thread.py", line 59, in run
    result = self.fn(*self.args, **self.kwargs)
  File "main.py", line 5, in worker
    raise TimeoutError("hotel site did not answer in 30 s")
TimeoutError: hotel site did not answer in 30 s

The fix: contain each failure, let the lead decide

Wrap each worker so a failure becomes a short report, just like the safe tool runner of episode 32. The lead then retries the failed part, or tells the user honestly that it's still pending.

from concurrent.futures import ThreadPoolExecutor

def worker(task):                      # same toy subagent
    if task == "hotel":
        raise TimeoutError("hotel site did not answer in 30 s")
    return f"{task}: done"

def safe_worker(task):                 # one failure must not sink the team
    try:
        return worker(task)
    except Exception as e:
        return f"{task}: FAILED ({type(e).__name__}: {e})"

with ThreadPoolExecutor() as pool:
    results = list(pool.map(safe_worker, ["train", "hotel", "food"]))
for r in results:
    print(r)
failed = [r.split(":")[0] for r in results if "FAILED" in r]
print("lead: retry", failed, "or tell Ravi the hotel is still pending")

Output:

train: done
hotel: FAILED (TimeoutError: hotel site did not answer in 30 s)
food: done
lead: retry ['hotel'] or tell Ravi the hotel is still pending

What a good lead agent does

  1. Plan: split the goal into independent tasks.
  2. Delegate: one clear task card per worker.
  3. Check: failures, gaps and duplicated work.
  4. Combine: one answer, and say what's missing.

Problem 5: facts get lost in a handoff

A pipeline is the other common shape: one agent finishes and hands off to the next, like a relay race.

def researcher():                      # agent 1: finds the facts
    return {"train": "train 20111", "date": "8 Nov", "hotel": "Baga Inn",
            "price": "Rs 2800/night"}

def writer(notes):                     # agent 2: writes the message
    return f"Ravi, take {notes['train']} and stay at {notes['hotel']}."

def send(text): print("sent to Ravi:", text)

notes = researcher()
message = writer(notes)                # hand off: agent 1 -> agent 2
send(message)
print("Ravi: which day?? and how much is the hotel?")

Output:

sent to Ravi: Ravi, take train 20111 and stay at Baga Inn.
Ravi: which day?? and how much is the hotel?

The researcher found four facts; the writer used two. Every handoff is a chance to lose information.

The fix: a handoff contract and a checker

A handoff contract lists what every handoff must carry. A checker agent compares the output with the contract and sends feedback (reflection, episode 31), with a retry limit.

REQUIRED = ["train", "date", "hotel", "price"]   # the handoff contract
def researcher():
    return {"train": "train 20111", "date": "8 Nov", "hotel": "Baga Inn",
            "price": "Rs 2800/night"}
def writer(notes, feedback=""):        # toy writer: fixes it when told
    if not feedback:
        return f"Ravi, take {notes['train']} and stay at {notes['hotel']}."
    return (f"Ravi, take {notes['train']} on {notes['date']} and stay at "
            f"{notes['hotel']} ({notes['price']}).")
def checker(text, notes):              # agent 3: checks the handoff
    return [k for k in REQUIRED if notes[k] not in text]
notes, feedback = researcher(), ""
for attempt in range(1, 4):
    message = writer(notes, feedback)
    missing = checker(message, notes)
    print(f"try {attempt}: missing {missing}")
    if not missing:
        print("sent to Ravi:", message); break
    feedback = f"add {missing}"

Output:

try 1: missing ['date', 'price']
try 2: missing []
sent to Ravi: Ravi, take train 20111 on 8 Nov and stay at Baga Inn (Rs 2800/night).

Two shapes of teams

Orchestrator-worker Pipeline (handoffs)
Shape lead + parallel workers agents in a line
Good for wide research, many independent parts step-by-step work (research → write → check)
Main risk vague tasks, duplicated work facts lost between steps
Guard task cards contract + checker

Real systems often mix both.

The cost, and when NOT to use a team

From the same Anthropic report:

Tokens compared with a normal chat
One agent about 4×
Multi-agent system about 15×
  • On the BrowseComp evaluation, token usage by itself explained 80% of the variance in performance: teams do better partly because they spend more tokens.
  • Early versions made mistakes like "spawning 50 subagents for simple queries".
  • Their rule of thumb: "Simple fact-finding requires just 1 agent with 3-10 tool calls"; direct comparisons might need 2-4 subagents; complex research might use more than 10.
  • Poor fit: jobs where all agents need the same shared context, and most coding tasks, which "involve fewer truly parallelizable tasks than research".
Use one agent Use a team
parts depend on each other many independent parts
most coding tasks wide research
small or quick jobs more information than one context can hold

Glossary

Term Meaning Example from this episode
Multi-agent system several agents working together on one job lead + 3 workers
Context window how much text a model can see at once (episode 16) our toy's 60 words
Orchestrator / lead agent the agent that splits the job and combines results lead()
Worker / subagent an agent given one part of the job worker(task)
Fresh context a worker starts with only its own task context = [task, search(task)]
Summary a short result a worker sends back "train ... -> best option picked"
Orchestrator-worker pattern a lead delegating to workers Anthropic's Research system
Delegation handing a task to another agent lead → worker
Task card objective, output format, tools, boundaries the hotel card
Parallel running at the same time 3.0 s → 1.0 s
ThreadPoolExecutor Python's pool for running functions in parallel threads pool.map(worker, tasks)
Independent task a task that doesn't need another task's result hotel vs food search
TimeoutError Python's error when something takes too long the hotel site
Pipeline agents in a line, each handing off to the next researcher → writer
Handoff passing work and facts from one agent to the next writer(notes)
Handoff contract the fields every handoff must carry REQUIRED
Checker an agent or code that checks output before it goes out checker()
Token cost what you pay for every token read and written about 15× a chat

Common mistakes

Mistake What you see Why Fix
One agent, one huge history train still in view? False the context window filled up split the job across workers
Vague tasks hotel: done 3 time(s), train: done 0 time(s) workers guess task cards with boundaries
Parallel workers that depend on each other wrong or missing results a task needed another's answer run dependent steps in order
One worker's error not caught TimeoutError: hotel site did not answer in 30 s, all results lost pool.map re-raises the error catch per worker, report, retry
Unchecked handoff Ravi: which day?? facts lost between agents contract + checker
A team for every question 15× the tokens for a one-line answer over-engineering one agent for small jobs

Mini project: a college-comparison team

A lead agent gets "compare fees, placements and hostels at 3 colleges". It writes one task card per college (objective, output: a dict with fees, placements, hostel; boundaries: only that college), runs 3 workers in parallel, then a checker makes sure every college has all three fields before the lead writes the comparison table.

Practice

1. Add a fourth worker for the weather in Goa and run all four in parallel.

Solution
import time
from concurrent.futures import ThreadPoolExecutor

CARDS = [
  {"job": "train",   "objective": "Mumbai to Goa on 8 Nov", "output": "train no, time, fare"},
  {"job": "hotel",   "objective": "near Baga, 8-10 Nov, under Rs 3000", "output": "name, price, rating"},
  {"job": "food",    "objective": "veg places near Baga", "output": "3 names with prices"},
  {"job": "weather", "objective": "Baga, 8-10 Nov", "output": "rain chance per day"},
]

def worker(card):                      # toy subagent: ~1 s of web waiting
    time.sleep(1)
    return f"{card['job']:7} worker: {card['objective']} -> {card['output']}"

start = time.time()
with ThreadPoolExecutor() as pool:
    for line in pool.map(worker, CARDS):
        print(line)
print(f"4 workers in parallel: {time.time() - start:.1f} s")

Output:

train   worker: Mumbai to Goa on 8 Nov -> train no, time, fare
hotel   worker: near Baga, 8-10 Nov, under Rs 3000 -> name, price, rating
food    worker: veg places near Baga -> 3 names with prices
weather worker: Baga, 8-10 Nov -> rain chance per day
4 workers in parallel: 1.0 s

2. The lead wants the hotel worker to pick "a hotel near the station the train arrives at". Can the train and hotel workers still run in parallel?

Answer

No. The hotel task now depends on the train worker's answer (which station). Run the train worker first, then give its result to the hotel worker in the task card. The food worker can still run in parallel.

3. Add "hotel rating" to the handoff contract. What must change?

Answer

Add "rating" to REQUIRED, make the researcher return a "rating" value, and the checker will keep sending the writer back until the message includes it.

Quick quiz 1

Which job suits a team of agents? A: fix one bug, B: compare 20 colleges' fees, placements and hostels, C: "what's 2 + 2?", D: rename one variable.

Answer

B. It splits into many independent searches that can run in parallel and holds more information than one context.

Quick quiz 2

What's wrong with the task "look into hotels"?

Answer

B: no place, dates, budget or output format. The worker will guess.

Interview questions

  1. What is the orchestrator-worker pattern? A lead agent decomposes a task, delegates subtasks to worker agents (often in parallel, each with its own context), and synthesizes their results.
  2. Why can multiple agents beat one agent? Each worker gets a fresh context for its part, workers run in parallel, and the lead reads compressed summaries instead of every raw page.
  3. What are the downsides? Many more tokens (about 15× a chat in Anthropic's report), coordination errors (duplicated or missed work), and lost information at handoffs.
  4. How do you write a good subagent task? An objective, an output format, guidance on tools and sources, and clear boundaries.
  5. When should you NOT use multiple agents? When parts depend on each other or need one shared context (most coding tasks), or the job is small.
  6. How do you make handoffs reliable? Define a contract (required fields) and check it in code or with a checker agent, with a retry limit.

Summary

  • One agent's context fills up on big jobs.
  • Orchestrator-worker: a lead splits; workers dig with fresh contexts; summaries come back.
  • Task cards (objective, output, tools, boundaries) stop duplicated work.
  • Parallel workers for independent tasks; catch each worker's failure and let the lead retry or report it.
  • Pipelines hand off between agents: guard them with a contract + checker.
  • Teams cost about 15× the tokens: use them for big, parallel, valuable jobs.

Next: episode 34, Coding, browser and computer-use agents.

Sources: Anthropic Engineering, "How we built our multi-agent research system" (13 Jun 2025).