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
- Plan: split the goal into independent tasks.
- Delegate: one clear task card per worker.
- Check: failures, gaps and duplicated work.
- 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
- 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.
- 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.
- 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.
- How do you write a good subagent task? An objective, an output format, guidance on tools and sources, and clear boundaries.
- 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.
- 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).