Professional, lesson 3

Orchestration patterns

Match the pattern to the task, and write every seam down

Lumen Supply moved its support reports to a team of agents to go faster. The run cost more and was no quicker, and two workers returned shapes the next step could not read. This lesson picks the pattern by the shape of the task. This is the analytics desk at Lumen Supply, an online electronics shop. You will run four tasks, each with its own pattern, then write the rule that chooses one and the contract at every seam.

I doWatch the failure and its fix.

One desk, four shapes of work

Orchestrator-workers, sectioning, voting and evaluator-optimizer each fit one shape. In orchestrator-workers the model splits the work. In the other three, the code splits it.

A seam is the point where one step hands its output to the next, such as a worker's answer going to the merge. The code owns each seam and checks what crosses it. The team owns the budget.

Three things go wrong. A linear task is split across workers. A seam has no contract, so workers return shapes nobody can read. A loop has no cap.

Independent sections run together

The weekly report has two parts that do not depend on each other: delivery times and refunds. Each goes to its own worker, and the code merges the two findings. It took 2 requests and 154 input tokens.

Open a card to see a worker's brief and what it returned. Each worker answered with the two keys its contract names, so the merge could read both.

TaskWrite the weekly report: delivery times and refunds.

Codeplan_task

Show the result

{
  "parts": [
    "Delivery times: the median rose from 2.6 to 3.1 days.",
    "Refund rate: it rose from 3.9 to 4.2 percent."
  ]
}

Clauderun_worker: Write the weekly report. Your part: Delivery times: the…

Show the result

{
  "finding": "Median delivery time rose from 2.6 days to 3.1 days week over week.",
  "evidence": "Delivery times median: 2.6 days (prior period) vs. 3.1 days (current period)."
}

Clauderun_worker: Write the weekly report. Your part: Refund rate: it rose…

Show the result

{
  "finding": "Refund rate rose from 3.9% to 4.2% week over week.",
  "evidence": "Refund rate moved from 3.9 percent to 4.2 percent, an increase of 0.3 percentage points."
}

Codemerge

Show the result

{
  "findings": [
    "Median delivery time rose from 2.6 days to 3.1 days week over week.",
    "Refund rate rose from 3.9% to 4.2% week over week."
  ]
}

Coderesult: Median delivery time rose from 2.6 days to 3.1 days week over week. Refund rate rose from 3.9% to 4.2% week over week.
Show the result
```
Median delivery time rose from 2.6 days to 3.1 days week over week. Refund rate rose from 3.9% to 4.2% week over week.
```

MERGED: 2 requests, 1 round, 204 input tokens.

The pattern rule, written as code

The starting plan sends every task to an orchestrator and never caps a loop. The fix reads the shape of the task. Independent parts are sectioned and one question is voted. An open split is orchestrated, and a draft is evaluated with a turn cap.

A fifth shape exists, where each step needs the one before. That is a chain, and it needs nothing more than order.

starter/orchestrate.py

1"""EDIT THIS FILE. plan() splits every task across workers.2A linear job gets three workers that cannot overlap, and no seam has a3contract. Run `./workshop check orchestration-strategies` until it is4green, then `./workshop watch orchestration-strategies`.5"""67from kit.api import Json8910def plan(task: Json) -> Json:11 """Return {"pattern": ..., "turns": ...} for a task with a `shape`.12 Shapes: independent, one_question, open_split, draft and dependent.13 Patterns: sectioning, voting, orchestrator, evaluator and chain.14 A loop gets a turn cap; anything else has turns of None.15 """16 return {"pattern": "orchestrator", "turns": None}171819def contract(step: str) -> Json | None:20 """Return {"input": ..., "output": ...} for a seam, or None.21 The seams are worker, vote and draft. Each output is a dict of keys.22 The worker output has exactly the keys finding and evidence, and the23 draft input names the lab sheet under the key sheet.24 """25 return None

Does adding agents speed up a linear task?

The policy has three steps, and each reads the step before it: summarise the policy, write the reply from the summary, write the subject line from the reply. Splitting them across workers looks like a way to save time.

Predict: Does splitting a linear task across more workers make it faster?

AYes. More workers finish sooner.
BNo. Each step waits for the one before, and each seam adds cost.

Show the answer

B. Parallel workers help only where the parts are independent. A dependent task gains seams and tokens, and no speed.

A linear task split across workers gains nothing

With the starting code, the orchestrator spends one request planning the split, then runs the three steps one after another. It took 4 requests, 4 rounds and 504 input tokens. Each step still waited for the one before it, so the planner added a request and saved no time.

The fix step runs the same task as a chain, so the two costs can be set side by side. This is a real Claude Haiku 5.5 run, recorded once.

TaskSummarise the policy, write the reply, write the subject.

Codeplan_task

Show the result

{
  "parts": [
    "What is the refund policy, summarised in one sentence?",
    "Using that one-sentence summary, how should we write a reply to a customer at day 45?",
    "Using that reply, what five-word subject line fits it?"
  ]
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…

Show the result

{
  "text": "Refunds are given in full within 30 days of delivery, store credit is offered between 31 and 90 days, and anything after 90 days is decided case by case by a person."
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…

Show the result

{
  "text": "At day 45, the reply should explain that the item is outside the 30-day full-refund window but still eligible for store credit, which we can offer now, and that a team member is available if they have questions."
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…
Show the result
```
{
  "text": ""
}
```
Codemerge
Show the result
```
{
  "last": ""
}
```
Coderesult: no result
Show the result

SLOWER: 4 requests, 4 rounds, 576 input tokens.

Pick by shape, and write what crosses each seam

plan returns the pattern for the shape, and a turn cap of 3 for a loop. contract returns the input and output of a seam. A worker returns a finding and evidence, a vote returns yes or no, and a draft returns text. The code refuses an output that does not fit, so nothing downstream reads free text.

Run as a chain, the same linear task skips the planner: 3 requests, 3 rounds and 394 input tokens, against 4, 4 and 504 for the orchestrator. Each step reads the one before it and returns the one key its seam names, draft.

A loop needs a cap and a contract. The starting plan has neither, so the worker never got the lab sheet and ran to the harness ceiling of 3 rounds, marked a runaway. The fixed plan's contract carries the sheet and the first draft passed. The cap is for the day a draft never passes.

orchestrate.pygreen lines are what the fix adds

1"""Pick the pattern from the shape of the task, and write the seams."""23from kit.api import Json45PATTERNS = {6 "independent": "sectioning",7 "one_question": "voting",8 "open_split": "orchestrator",9 "draft": "evaluator",10}11TURN_CAP = 312CONTRACTS: dict[str, Json] = {13 "worker": {14 "input": {"brief": "string"},15 "output": {"finding": "string", "evidence": "string"},16 },17 "vote": {18 "input": {"brief": "string"},19 "output": {"answer": "yes or no"},20 },21 "draft": {22 "input": {23 "brief": "string",24 "sheet": "the lab sheet to cite",25 "verdict": "list of problems",26 },27 "output": {"draft": "string"},28 },29}303132def plan(task: Json) -> Json:33 """The pattern for this task, and a turn cap for a loop."""34 pattern = PATTERNS.get(task.get("shape", ""), "chain")35 turns = TURN_CAP if pattern == "evaluator" else None3637 return {"pattern": pattern, "turns": turns}383940def contract(step: str) -> Json | None:41 """The input and output schema of one seam, or None if nobody wrote it."""42 return CONTRACTS.get(step)

TaskSummarise the policy, write the reply, write the subject.

Codeplan_task

Show the result

{
  "parts": [
    "Summarise the refund policy in one sentence.",
    "Write a reply to a customer at day 45 using the summary.",
    "Write a five-word subject line for that reply."
  ]
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…

Show the result

{
  "draft": "Full refunds are given within 30 days of delivery, store credit is offered between 31 and 90 days, and any request after 90 days is decided by a person."
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…

Show the result

{
  "draft": "Thank you for reaching out. Since your order was delivered 45 days ago, we can offer you store credit for its value, though a full refund is only available within 30 days of delivery."
}

Clauderun_worker: Policy: Refund in full within 30 days of delivery. Between…
Show the result
```
{
  "draft": "Your Store Credit Options Explained"
}
```

Codemerge

Show the result

{
  "last": "Your Store Credit Options Explained"
}

Coderesult: Your Store Credit Options Explained
Show the result
```
Your Store Credit Options Explained
```

MERGED: 3 requests, 3 rounds, 490 input tokens.

TaskWrite a keyboard blurb in 20 words that names the warranty.
Clauderun_worker: Write a product blurb for the Lumen keyboard in at most 20…
Show the result
```
{
  "text": ""
}
```

Coderun_judge:

Show the result

{
  "problems": [
    "mention the warranty",
    "cite the test report id from the lab sheet"
  ]
}

Clauderun_worker: Write a product blurb for the Lumen keyboard in at most 20…
Show the result
```
{
  "text": "I don't have the lab sheet or the warranty terms, so I"
}
```
Coderun_judge: I don't have the lab sheet or the warranty terms, so I
Show the result
```
{
  "problems": [
    "cite the test report id from the lab sheet"
  ]
}
```
Clauderun_worker: Write a product blurb for the Lumen keyboard in at most 20…
Show the result
```
{
  "text": ""
}
```

Coderun_judge:

Show the result

{
  "problems": [
    "mention the warranty",
    "cite the test report id from the lab sheet"
  ]
}

Coderesult: no result
Show the result

RUNAWAY: 3 requests, 3 rounds, 356 input tokens.

We doChange one setting at a time and predict.

The same split, with and without contracts

Switch between the two runs. The merge card is where the runs split. Without contracts the workers answered in free text, so the merge refused: 3 requests, 232 input tokens, no result.

With contracts the same split merged. It took 3 requests and 258 input tokens, and every worker returned a finding.

This part is interactive in the lab: run ./workshop watch orchestration-strategies.

Try it: pattern and plan code

Change one setting at a time. Pick a pattern, then the plan code. Watch voting: without a contract the three answers are free text and cannot be counted, and with one all 3 answered yes.

Watch the evaluator too. The rubric wants a test report id from the lab sheet. Without a contract the sheet never reaches the worker, so the loop ran to the harness ceiling of 3 rounds. With the contract the first draft passed.

This part is interactive in the lab: run ./workshop watch orchestration-strategies.

The same shapes as subagents

In the Claude Agent SDK the orchestrator spawns workers with the Agent tool, and only the workers you define. A worker has its own prompt and its own tool list. Here a worker has one tool, which looks up the figure for its topic.

This is a real Claude Haiku 5.5 run on the Agent SDK. The orchestrator spawned two workers in one response. Each looked up its figure and returned the two keys the contract names, finding and evidence, and the code merged them. The contract became the subagent's return format.

app/subagents.pyfile: 183 lines

···40 lines not shown4142 return {43 "worker": {44 "description": "Does one part of a split job.",45 "prompt": WORKER.format(keys=keys),46 "tools": [FIGURE],47 "model": "haiku",48 "background": False,49 }50 }515253def options() -> Json:54 """The session holds the spawn tool and the one tool a worker may use."""55 return {"allowed_tools": [SPAWN, FIGURE], "agents": subagent()}565758def topic(part: str) -> str:59 """The name of a part: the words before its colon."""60 return part.split(":", maxsplit=1)[0].lower()616263def build_server(task: Task) -> McpSdkServerConfig:64 """Serve `figure`: the line of the sheet that a topic names."""65···118 lines not shown

TaskWrite the weekly report: delivery times and refunds.

Clauderun_worker (refused): Look up the figure for the topic "delivery times" using…

Show the result

{
  "error": {
    "category": "contract",
    "message": "output does not fit"
  }
}

Clauderun_worker (refused): Look up the figure for the topic "refund rate" using your…

Show the result

{
  "error": {
    "category": "contract",
    "message": "output does not fit"
  }
}

Codemerge (refused)

Show the result

{
  "error": {
    "category": "shape",
    "message": "no finding"
  }
}

Coderesult: Weekly report: Median delivery time rose from 2.6 to 3.1 days. Refund rate rose from 3.9% to 4.2%, an increase of 0.3 percentage points. Neither figure…

Show the result

Weekly report: Median delivery time rose from 2.6 to 3.1 days. Refund rate rose from 3.9% to 4.2%, an increase of 0.3 percentage points. Neither figure came with a reporting period or comparison window, so the weeks they cover are unconfirmed. The delivery figure also has no sample size, and the refund figure doesn't say whether it counts refunds or their value. Confirm those before publishing.

MISMATCHED: 8 model turns, workers spawned in 1.

You doFix the starting code, then test yourself.

You do: pick by shape and write the seams

Copy the starting code and open work/orchestration-strategies/orchestrate.py. plan() sends every task to an orchestrator with no turn cap, and contract() returns nothing for any seam.

Terminal

./workshop start orchestration-strategies
./workshop check orchestration-strategies
./workshop watch orchestration-strategies

The checks give each task shape its pattern and keep a linear task in one chain. Only a loop gets a turn cap. Every seam has a contract, and the draft seam carries the lab sheet.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

1. A weekly report has four sections, and no section reads another. It must be ready in 20 seconds, with each worker call taking about 8, and one call can write only about 500 words against the 2,000 needed. The cost cap allows four calls and one merge. How should you build it?

ARun one worker for the whole report, then a checker that reviews the finished text for quality.
BPut all four sections in one prompt and ask for one long answer, then trim the result to fit.
CRun the four sections as parallel workers, then merge their findings.
DRun the four sections in order, each worker reading the finished text of the one before it.

Show the answer

Answer: C

A One worker takes the sections one by one, so it will not fit the 20 seconds, and it cannot write 2,000 words. A checker adds one more call.
B One prompt is one call, not a split. It hits the 500 word cap, gives no seam to check and no parallel speedup.
C Correct. Independent parts are sectioning. The four calls overlap, so the run takes about one call's time.
D Running in order makes the time four calls long, about 32 seconds. The sections do not need each other.

2. A compliance check asks one yes or no question about a message, such as whether it leaks a card number, and a wrong answer is costly. The budget allows three calls per message. A single call is right 9 times in 10, and the errors look random. How do you raise confidence in one decision?

AAsk the same question three times and take the majority answer.
BAsk three differently worded questions, each leaning toward a yes, and count the yes answers.
CSplit the message into three parts and send one part to each call, then combine the three answers.
DAdd three more workers that each write a longer explanation of why the message is safe or not.

Show the answer

Answer: A

A Correct. Voting repeats one check and takes the majority, which cuts the chance of a one-off error.
B Different wording changes the question, and a lean toward yes biases every vote. Votes are comparable only on the same prompt.
C A part of a message may miss the card number that sits in another part. This is sectioning, and it does not vote.
D Longer explanations are not votes. Nothing gets counted, and the answer is no more certain.

3. An analyst asks why ticket volume rose last month, and nobody knows how many causes there are. The subtopics only appear once the data is read, so two workers may be enough, or six. The budget is a flat 10 calls for the request. Which pattern fits it?

AOne prompt that lists every cause the team has seen before and asks the model for each one.
BSix fixed workers, one per cause the team thought of last year, each reading the same data.
CWorkers that return free text, joined by the next step exactly as it arrives.
DAn orchestrator that splits at run time, then workers on each part.

Show the answer

Answer: D

A A fixed list in one prompt cannot name causes that the data has not shown yet.
B A fixed count of workers assumes the split is known. It wastes calls when there are two causes.
C Free text at the seam is the failure. Joining whatever comes back breaks on the first odd shape.
D Correct. The split is open, so the orchestrator decides it at run time and hands each part to a worker.

4. A team is choosing where an evaluator and drafter loop fits, with a hard spend limit and one more call for each pass. The draft is a product blurb that must meet a score the code can compute. Which conditions make a task fit this pattern? Select two.

AThe draft can be scored by a clear rule that the code checks.
BA good draft is worth any number of turns, so the loop needs no cap.
CThe checker's reasons name what to change, so a second draft can fix it.
DOne prompt can carry the draft, the rubric and the retries together.

Show the answer

Answer: A, C

A Correct. A checkable rubric gives the loop a test that does not depend on the drafter's opinion.
B A loop with no cap has no end if the rubric is never met, and the spend limit is hard.
C Correct. Reasons the drafter can act on make each turn better than the last, which is what pays for the loop.
D One prompt has no checker outside the model and no loop in code. It is not this pattern.

5. Two workers feed a merge step. On 1 run in 4 the merge fails, because one worker returns a sentence and the other returns a JSON object. The prompts were reviewed twice and are fine, and the model version is unchanged since the failures began. What is the fix?

ARewrite the merge step so it tries to read whatever shape it receives from each worker.
BWrite an input and output contract for the seam, and refuse output that does not fit.
CMerge the two workers into one prompt so the two outputs can no longer differ in shape.
DAdd a third worker to read both outputs, decide which is right and pass that one on.

Show the answer

Answer: B

A A merge that accepts any shape hides the fault. It fails later, somewhere harder to see.
B Correct. The contract names the keys, and the code refuses a bad output at the seam where it is made.
C This drops the split and its speed. The seam still exists between the prompt and the next step.
D A third worker adds a seam with no contract, and a third place for the shape to differ.

6. A five-step pipeline passes each output straight to the next step. A bad output at step 2 surfaces as a wrong answer at step 4, two steps later. Engineers lose hours finding where it began, and the retry budget is one rerun per request. Where should the check go?

AAt step 4, where the wrong answer first shows, because that is where it hurts the user.
BAt the start, in a longer prompt that tells every step to be careful with its output.
CAt every seam, so a bad output is refused at the step that made it.
DAt the end, with a retry of the whole pipeline until the final answer passes.

Show the answer

Answer: C

A Step 4 only sees the symptom. The fault is two steps upstream, and the error points at the wrong step.
B A prompt asks the model to be careful. Only code at the seam can refuse an output.
C Correct. A check at each seam stops the fault where it starts and names the step that owns it.
D Retrying the whole pipeline pays for five steps each time and does not say where it broke.

7. An evaluator and drafter loop has no stop rule. One night it ran 14 turns on a blurb whose rubric could not be met, and the cost rose each turn. The team wants the worst case bounded before the next nightly run, without losing the good drafts. What should be added?

AA turn budget, and a stop rule on the score so the loop ends when it passes.
BA turn count of 40 instead of 14, so the loop has more time to meet the rubric.
CA second drafter, so two drafts are tried in each turn and the better one is kept.
DA rule that the checker may skip its reasons on later turns to save tokens.

Show the answer

Answer: A

A Correct. A cap ends the loop when the score is never met, and a stop rule ends it when it is.
B More turns raise the worst case. A rubric that cannot be met will still run out the budget.
C Two drafters double the cost of each turn, and the loop still has no end.
D Without reasons the drafter has nothing to fix, so the loop is less likely to converge.

8. A multi-agent design with three workers and one merge is under audit, and the reviewer asks what a decomposition must state at each seam. The audit is written down, and each answer must be something a test can check. What must each seam name? Select two.

AThe model name that each worker runs on, so a run can be repeated.
BThe input schema that the worker receives.
CA note that the next step will work out the shape from the text it gets.
DThe output schema that the next step reads.

Show the answer

Answer: B, D

A The model is a setting of the worker. It says nothing about what crosses the seam.
B Correct. The input schema says what the worker is given, so a wrong input is refused.
C A shape left to the next step is the missing contract, and it is where the merge fails.
D Correct. The output schema is what the next step reads, so a bad output is refused where it was made.

9. A team built a five-step task as a multi-agent system to go faster, and each step needs the output of the one before. The cost tripled and the time did not fall. The steps cannot change order, and each step still needs its own check. What should it have been?

AFive workers run in parallel, with a longer timeout on each one so none is cut off.
BFive workers run in parallel, merged by one more worker at the end of the run.
COne prompt with the five steps numbered, run as a single long call with no seams.
DA workflow that runs the steps in order, each reading the last output.

Show the answer

Answer: D

A Parallel workers cannot start a step before its input exists. A longer timeout only waits longer.
B A merge after parallel workers still cannot run dependent steps together, and it adds a call.
C A numbered prompt drops the seams, so no step can be checked or retried alone.
D Correct. Dependent steps are a chain. Order is the only thing they need, so no split is worth its cost.

10. A support bot answers one question per message by reading one help article, and it needs no steps after that. A teammate proposes an orchestrator with three workers. Latency is 2 seconds now, the budget is flat, and answers are already correct. What is the right call?

ABuild the orchestrator, because a team of workers is more reliable than a single call.
BKeep the single call that reads the article, the lowest complexity that works.
CBuild it, but run the three workers in parallel so the latency holds at 2 seconds.
DSplit the article into three parts and have one worker read each part in order.

Show the answer

Answer: B

A More workers add seams and cost. Reliability comes from a check at the seam, not from headcount.
B Correct. One call with retrieval answers a single question. Step up only when that fails.
C Parallel workers still add calls and a merge to a job that one call already does.
D Reading parts in order adds steps with nothing to decide, and it slows a 2 second answer.

Play: predict the output

This vote asks four times whether a message leaks a card number.

python

def leaks(message: str) -> bool:
    votes = [ask(message) for _ in range(4)]
    return votes.count("yes") > votes.count("no")

Predict: Two voters say yes and two say no. What does the check decide?

AFalse, so the message goes out as safe.
BTrue, because half the voters saw a leak.

Show the answer

A. An even count can tie, and this tie falls on the unsafe side. Use an odd number of voters, and send a tie or a split vote to the cautious answer.

References

Building effective agents: sectioning, voting, orchestrator-workers and the evaluator loop.
Agent SDK subagents: the same patterns built from subagents.
How we built our multi-agent research system: what an orchestrator costs, and when it pays.
Structured outputs: holding each seam to the shape its contract names.

Conclusions

Pick the pattern from the shape of the task, not from habit.
Write the input and output of every seam, and refuse what does not fit.
Put a turn cap on every loop.

You can now match a pattern to a task and contract each seam.

Sectioning

Independent parts run in parallel and are merged

Voting

One question asked several times, the majority answers

Orchestrator-workers

A planner splits the job at run time

Evaluator-optimizer

A drafter and a checker loop, with a turn cap

Contract

The input and output a seam names, checked in code