Multi-Agent Orchestration

Learn how multi-agent systems are run: routing requests to the right agent, delegating and handing off work, coordinating results, managing shared state safely, and building multi-agent workflows.

30 minAdvancedCode Examples

The Core Idea: Orchestration is the control layer of a multi-agent system. It routes each request to the right agent, delegates and hands off work, coordinates results, protects shared state from conflicts, and ties it together in a workflow.

  1. Beginner: Routing

Routing decides which agent should handle a request. A good router keeps each specialist focused and avoids waking up the wrong, expensive one.

Routing methodHow it worksTrade-off
Rules and keywordsMatch words to agent skillsFast and cheap, but brittle
Classifier or small modelA cheap model picks the agentFlexible, small cost
LLM routerA language model reads and decidesMost flexible, slowest
Embedding matchCompare the request with agent descriptionsGood for many agents

In the code: A keyword router sends invoice charged twice to billing, error at login to technical, and a request that matches nothing to a general agent.

  1. Beginner: Delegation and Handoffs

Delegation means one agent gives a task to another. A handoff transfers the whole conversation to a different agent. Both need clear instructions, context and an expected result.

Good delegation includesWhy
The goal in one sentenceThe receiver knows what to do
Only the needed contextSaves tokens and avoids confusion
The expected output formatEasy to merge
LimitsTime, budget, allowed tools

Common mistake: Handing over the whole conversation every time. Pass a short, precise brief instead.

  1. Medium: Coordination

Coordination makes sure the pieces fit: that tasks are not duplicated, results are merged and the final answer is consistent.

Coordination jobExample
Avoid duplicate workTwo agents should not research the same question
Order dependent tasksAnalysis waits for the data
Merge resultsCombine three summaries into one
Resolve conflictsTwo agents disagree: ask a judge or a human
Track progressKnow which tasks are done, running or failed

Tip: A task board (a list of tasks with status and owner) is a simple and effective coordination tool.

  1. Medium: Managing Shared State

When several agents read and write the same data, they can overwrite each other. A safe approach is optimistic concurrency: each write names the version it read, and the write fails if someone else changed the data first.

In the code: Agents A and B both read version 1. A writes first, so the version becomes 2. B's write, still based on version 1, is rejected. B reads again and its second write succeeds. Both notes survive.

TechniqueUse
Version checksDetect conflicting writes
Append-only logsNever overwrite, only add
OwnershipOnly one agent may write each field
LocksBlock others while writing (use sparingly)

  1. Advanced: Multi-Agent Workflows

A complete multi-agent workflow combines everything: a router picks the specialist, the specialist works (using tools and shared state), results are validated, and a coordinator returns the final result.

1
Receive: A request arrives.
2
Route: Pick the specialist.
3
Delegate: Send a short, clear brief.
4
Work and update state: The specialist uses its tools and writes to shared state with version checks.
5
Validate and return: Check the result, merge if needed and answer.

Do not forget: Add step limits, timeouts and escalation to a human at the orchestration level too. A system of agents can loop just like a single agent.

  1. Visual Explanation: Routing and a Shared-State Conflict

The figure shows how the router in the code sends four requests to different agents, then walks through a write conflict on shared state.

Part 1 · Routing Decisions in the CodeFour requests, four destinations
Billinginvoice, charge
Why was my invoice charged twice?
↓
billing agent
Technicalerror, login
The app shows an error at login
↓
technical agent
Salesupgrade, plan
How much is the upgrade plan?
↓
sales agent
Generalno match
Tell me a joke
↓
general agent
Part 2 · The Shared-State ConflictOptimistic concurrency
Both read
Version 1
A and B start from the same data.
A writes
Accepted
Version becomes 2.
B writes
Rejected
B used the old version 1.
B retries
Accepted
Re-read, then write; version 3.
Click to see why we do not simply overwriteCompare ▼
If B overwrote the data, A's note would be lost without anyone noticing. A version check turns a silent loss into a visible conflict that can be retried.

Part 1 shows each request with its destination. Part 2 follows the two agents through the conflict. Open the bar to see why silent overwrites are dangerous.

  1. Python Implementation: A Router, a Version-Checked State and a Workflow

This script builds a keyword router for three specialist agents with a general fallback, shows two agents writing to shared state with version checks (one write is rejected and retried), and runs a small coordinator workflow.

orchestration.pyPython 3.10+ · standard library only
# Routing, delegation, coordination and shared stateSKILLS = {    "billing": {"billing", "invoice", "refund", "charge", "payment"},    "technical": {"error", "crash", "bug", "login", "password"},    "sales": {"price", "buy", "plan", "upgrade", "discount"},} def route(question):    words = set(question.lower().replace("?", "").replace(",", "").split())    scores = {agent: len(words & vocabulary) for agent, vocabulary in SKILLS.items()}    best = max(scores, key=scores.get)    return best if scores[best] > 0 else "general" for q in ["Why was my invoice charged twice?", "The app shows an error at login", "How much is the upgrade plan?", "Tell me a joke"]:    print(q.ljust(36), "-> routed to:", route(q)) # Shared state with optimistic concurrency: a write must name the version it readclass SharedState:    def __init__(self):        self.version, self.data = 1, {"notes": []}     def update(self, expected_version, note):        if expected_version != self.version:            return False                                      # someone else changed it first        self.data["notes"] = self.data["notes"] + [note]        self.version += 1        return True state = SharedState()seen_by_a = seen_by_b = state.version                         # both agents read version 1print("Agent A writes:", state.update(seen_by_a, "A: found the invoice"), "-> version", state.version)print("Agent B writes:", state.update(seen_by_b, "B: refund approved"), "-> conflict, must re-read")print("Agent B retries:", state.update(state.version, "B: refund approved"), "-> version", state.version)print("Final notes:", state.data["notes"]) # Delegation and coordination: a coordinator hands off, then merges the resultsdef run_workflow(question):    specialist = route(question)    result = specialist + " agent handled: " + question    return {"routed_to": specialist, "result": result, "status": "done"} print(run_workflow("Why was my invoice charged twice?"))
EXPECTED OUTPUT (your numbers may differ slightly)
Why was my invoice charged twice? -> routed to: billing
The app shows an error at login -> routed to: technical
How much is the upgrade plan? -> routed to: sales
Tell me a joke -> routed to: general
Agent A writes: True -> version 2
Agent B writes: False -> conflict, must re-read
Agent B retries: True -> version 3
Final notes: ['A: found the invoice', 'B: refund approved']
{'routed_to': 'billing', 'result': 'billing agent handled: Why was my invoice charged twice?', 'status': 'done'}

The router sends each request to the right specialist and falls back to the general agent. The shared-state demo shows a rejected write and a successful retry, so both notes survive. The final line is the coordinator's result for the billing question.

Knowledge Check

Question 1: What does a router do in a multi-agent system?
Question 2: What does a version check on shared state prevent?

Key Points

✓Orchestration is the control layer: routing, delegation, coordination, shared state and workflow.
✓Routers can use rules, a small classifier, an LLM or embeddings, and need a fallback.
✓Delegate with a short brief: goal, needed context, output format and limits.
✓Coordination avoids duplicate work, orders dependent tasks, merges results and resolves conflicts.
✓Protect shared state with version checks, append-only logs or ownership.
✓Add limits, timeouts and human escalation at the orchestration level.

The Big Picture

Orchestration in One Line

Route → delegate → coordinate → update shared state safely → validate → answer

Orchestration is what turns several separate agents into one reliable system.

Up Next: You can now design teams of agents. In Agent Frameworks you will see why frameworks exist and how they package the loop, tools, state and workflows you have been building by hand.