Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Multi-agent Systems

The Orchestrator-Worker Pattern

Build an orchestrator agent that plans a goal, delegates tasks to specialist workers, runs them in parallel and merges the results, with runnable Python.

Some goals cannot be planned in advance because the subtasks depend on what you find along the way. "Compare three laptops and recommend one" needs a search for each laptop, but you only know which laptops after the first search. The orchestrator-worker pattern handles this: one orchestrator agent plans, delegates focused jobs to worker agents, collects their results and assembles the final answer.

This is the backbone of most deep-research and coding agents. In this lesson you will build one in plain Python: a planner that splits a goal into tasks, workers that run them (sequentially and in parallel), and a synthesizer that merges the results with error handling.

No real model is called here. The planner and workers are deterministic stand-in functions where a real system would call a model with a role prompt. The control flow, delegation and merging are the real design.

The shape of the pattern

flowchart TD
  U["User goal"] --> O["Orchestrator"]
  O --> W1["Worker 1"]
  O --> W2["Worker 2"]
  O --> W3["Worker 3"]
  W1 --> S["Synthesize"]
  W2 --> S
  W3 --> S
  S --> A["Final answer"]

The orchestrator never does the detailed work; workers never see the whole goal.

The orchestrator has three jobs:

  1. Plan: turn the goal into a list of tasks, each with a clear instruction and expected output.
  2. Delegate: send each task to a worker with only the context it needs.
  3. Synthesize: combine worker outputs, resolve conflicts and write the answer.

Workers are ordinary agents with narrow prompts and their own tools. Because each worker has a fresh context, it can read long documents without crowding the orchestrator's window.

Step 1: a plan as data

Ask the planner for structured output, never free text. A list of tasks with ids, instructions and dependencies is easy to validate and run.

Python Plan tasks and validate them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Validation matters because a model can invent a worker name or a dependency that does not exist. Reject bad plans early, or ask the planner to fix them.

Step 2: run workers in dependency order

Run a task once everything it depends on has finished. Each worker receives its instruction plus the outputs it depends on.

Python Run the plan in dependency order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The ready list is the key idea. Everything in it has no unfinished dependencies, so those tasks could run at the same time. That is where multi-agent systems gain speed.

Step 3: parallel workers

Model calls spend most of their time waiting on the network, so threads or async work well. Python's concurrent.futures.ThreadPoolExecutor is enough to see the idea.

Python Run independent workers in parallel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In your own deployment you would use async clients and set a limit on concurrent calls, because providers rate-limit requests and each worker spends tokens.

Handling failure

Workers fail: timeouts, empty results, malformed output. The orchestrator must decide what to do:

  • Retry a failed task once or twice with a short backoff.
  • Degrade gracefully: if one of five searches fails, continue and tell the user which part is missing.
  • Replan: if a result changes the picture ("no laptop under budget exists"), let the orchestrator revise the plan.
  • Abort when a required step fails and nothing sensible remains.

Return worker results as a small object, {"ok": true, "output": ...} or {"ok": false, "error": ...}, so failures are data, not exceptions that crash the run.

Writing good worker instructions

Workers know nothing except what you send. A good delegation states the goal of this task, the inputs, the format of the output and any limits (tools allowed, number of sources). Vague delegation ("look into laptops") produces vague results. Ask for concise output with sources, since the orchestrator will read it all.

Budgets and guardrails

Put hard limits around the whole system: a maximum number of tasks, maximum workers per level, a token or cost budget and an overall timeout. Without them a planner that keeps adding "one more search" can run all night.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What are the three jobs of the orchestrator?

    It plans tasks, sends them to workers and merges the results.
  2. 2. Why should the plan be structured data rather than free text?

    Structured plans let you check workers and dependencies before running anything.
  3. 3. Which tasks can run in parallel?

    Tasks with no unfinished dependencies are independent of each other.
  4. 4. A worker times out. What is a sensible response?

    Treat failure as data and decide to retry, degrade or replan.
  5. 5. Why set a cap on tasks and cost?

    Budgets stop runaway loops and surprise bills.

Summary

  • The orchestrator plans, delegates and synthesizes; workers do narrow jobs in fresh contexts.
  • Make the plan structured data and validate it before running.
  • Run tasks in dependency order and in parallel when they are independent.
  • Treat worker failures as data: retry, degrade, replan or abort.
  • Give workers explicit goals, inputs and output formats, and cap the whole system.

Next: Agent Handoffs and Shared State