Orchestrator-Worker Patterns for Coordinating Specialist Agents

Orchestrator-worker is the multi-agent topology where a central controller owns the user goal and dispatches bounded work to specialist workers. Workers run their own loops with narrower tools; they return structured results; the orchestrator merges, retries, re-routes, or escalates.

This page is a practical recipe for that pattern inside one product runtime (in-process or service mesh with a single control plane).

Summary

Implement an orchestrator that classifies the next subgoal, builds a handoff packet, runs a worker under a local budget, validates the return contract, then merges into shared task state until a global stop condition fires.

Recipe

1. Define the role graph: one orchestrator, N workers, optional human node.
2. Document tools per worker (least privilege) and tools the orchestrator may use (usually few or none beyond routing helpers).
3. Choose a routing policy: rules, classifier, or LLM tool-call named after agents.
4. Standardize packet and return schemas for every worker.
5. Implement dispatch + collect with per-worker max_turns and a global turn/cost/time cap.
6. Define failure policy: retry same worker, different worker, replan, or needs_human.
7. Add trace fields: run_id, agent_id, handoff id, status, budgets remaining.
8. Eval routes and return-schema validity separately from final answer quality.

Working Example

from dataclasses import dataclass, field
from typing import Any, Callable
 
@dataclass
class Packet:
    subgoal: str
    constraints: list[str]
    inputs: dict[str, Any]
    success_fields: list[str]
    max_turns: int = 6
 
@dataclass
class WorkerResult:
    status: str  # ok | failed | needs_human
    summary: str
    artifacts: dict[str, Any] = field(default_factory=dict)
    errors: list[dict] = field(default_factory=list)
 
Worker = Callable[[Packet], WorkerResult]
 
WORKERS: dict[str, Worker] = {}  # register specialists at startup
 
def route(goal: str) -> str:
    g = goal.lower()
    if "refund" in g or "billing" in g:
        return "billing"
    if "stack trace" in g or "exception" in g:
        return "coder"
    return "researcher"
 
def dispatch(goal: str, task: dict, workers: dict[str, Worker], global_left: int) -> WorkerResult:
    name = route(goal)
    worker = workers[name]
    packet = Packet(
        subgoal=goal,
        constraints=task.get("constraints", []),
        inputs={"artifacts": task.get("artifacts", {})},
        success_fields=["summary"],
        max_turns=min(6, global_left),
    )
    result = worker(packet)
    task.setdefault("history", []).append({"worker": name, "status": result.status})
    if result.status == "ok":
        task.setdefault("artifacts", {}).update(result.artifacts)
    return result
 
def run_orchestrator(user_goal: str, workers: dict[str, Worker], max_global_turns: int = 16):
    task = {"goal": user_goal, "artifacts": {}, "history": [], "constraints": []}
    left = max_global_turns
    # One-shot specialist for the basics; production often loops on subgoals
    result = dispatch(user_goal, task, workers, left)
    if result.status == "ok":
        return {"status": "ok", "answer": result.summary, "task": task}
    if result.status == "needs_human":
        return {"status": "needs_human", "detail": result, "task": task}
    return {"status": "failed", "detail": result, "task": task}

Wire real workers by implementing Worker callables that run their own model/tool loops and always emit WorkerResult.

Deep Dive

Topology variants

Start with one-shot or short sequential pipelines. Add fan-out only when merge rules are explicit.

Routing policy choices

1. Deterministic rules - keywords, ticket type, URL path. Cheap and testable.
2. Embedding / classifier - maps utterance to worker id with confidence threshold.
3. LLM router - model emits transfer_to_billing style tool calls.
4. User pin - UI forces a specialist; orchestrator still enforces tools and budgets.

Prefer rules for high-volume product paths. Use LLM routers for open-ended intents, with a safe default worker.

What the orchestrator should not do

• Run every hard subgoal itself while workers idle.
• Grant temporary superuser tools "because the user asked."
• Accept free-form worker dumps without schema validation.
• Retry forever without a replan counter or human path.

Budgets and fairness

• Local budget: worker max turns, tool-call cap, wall time.
• Global budget: sum of worker spend, total wall time, total dollars.
• Fairness: prevent one recursive worker from consuming the global budget alone by allocating slices per dispatch.

Framework mappings (verify at build)

• LangGraph: supervisor node + worker nodes, conditional edges, shared state.
• CrewAI: hierarchical process with manager agent.
• OpenAI Agents SDK: handoffs from a triage agent.
• Microsoft Agent Framework: workflow graphs with coordinator roles.

Gotchas

1. God orchestrator - reimplements all skills; workers become dead code.
2. Shared superuser tool belt - multi-agent costume with monolith risk.
3. Missing return validation - orchestrator trusts prose and invents success.
4. Unbounded retries - same worker fails 20 times with the same packet.
5. Silent context drop - worker never receives the ticket id the orchestrator assumed was obvious.
6. Fan-out without merge rules - conflicting artifacts overwrite each other.
7. No global stop - each worker is bounded but the orchestrator loops forever across workers.

Alternatives

FAQs

Related

• Multi-Agent Architecture Basics - two-agent skeleton
• Why Split One Agent Into Many Specialized Agents - when decomposition pays
• Context Handoff: Passing State Between Agents Cleanly - packet fields
• Peer-to-Peer Agent Collaboration Without a Central Orchestrator - no central controller
• Architecture Guide: Designing a Multi-Agent System's Communication Contract - formal messages
• Multi-Agent Architecture Best Practices - practices list
• Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - architecture vocabulary

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.