Supervisor Pattern (Hierarchical Multi-Agent)

1. Concept Overview & Systemic Problem

When creating multi-agent systems, developers often encounter coordination issues. If agents merely send messages to each other in a shared chat:

• Goal Loss: Agents begin commenting on peers' replies, forgetting the original user request.
• Uncontrolled Context Growth: Each agent sees the full log of messages from all other agents, leading to quadratic token consumption and attention degradation.
• Lack of Determinism: It is impossible to guarantee that a task is genuinely solved rather than simply ignored.

The Supervisor Pattern implements a classic engineering hierarchy: a central orchestrator (Supervisor) interacts with the user, builds an execution plan, decomposes it into isolated tasks, assigns them to target agents (Specialist Workers), and aggregates the final result.

2. Architectural Taxonomy & Mental Model

                       ┌─────────────────────────┐
                       │       USER PROMPT       │
                       └────────────┬────────────┘
                                    │
                                    ▼
                       ┌─────────────────────────┐
                       │    SUPERVISOR AGENT     │
                       │  (State, Plan & Router) │
                       └───┬────────┬────────┬───┘
                           │        │        │
           ┌───────────────┘        │        └───────────────┐
           │ Task A                 │ Task B                 │ Task C
           ▼                        ▼                        ▼
┌────────────────────┐   ┌────────────────────┐   ┌────────────────────┐
│   RESEARCH AGENT   │   │    CODER AGENT     │   │     QA AGENT       │
│ (Search, Docs, RAG)│   │ (AST, Git, Patch)  │   │(Evals, Tests, Lint)│
└──────────┬─────────┘   └──────────┬─────────┘   └──────────┬─────────┘
           │                        │                        │
           └───────────────┐        │        ┌───────────────┘
                           ▼        ▼        ▼
                       ┌─────────────────────────┐
                       │   AGGREGATED ARTIFACT   │
                       └─────────────────────────┘

1. State Machine / Router: The supervisor contains a finite state machine. After each step, it evaluates: Completed? -> Return response to the user, or Next step needed? -> Call the appropriate worker.
2. Task Encapsulation: Each worker receives only the necessary input information and its own set of tools (Tooling Scope). For example, the Coder Agent does not have access to Google search, while the Research Agent does not have access to modify the file system.

3. Technical Pipeline & Internal Mechanics

Supervisor Operation Algorithm:

1. Input Task Analysis: The supervisor model is invoked with a system prompt describing each worker's competencies and a decision return schema (Function Calling / Structured Output).
2. Routing Decision Generation:

   {
     "next_worker": "coder_agent",
     "task_description": "Implement authentication middleware in src/auth.ts using Better Auth",
     "expected_artifacts": ["src/auth.ts"]
   }
   

3. Isolated Worker Execution: The orchestrator initializes the worker's context, starts its autonomous cycle, and waits for the result to return.
4. Quality Control (Evaluation Gate): Upon receiving the result, the supervisor can either approve it, redirect it to the QA agent for testing, or return it to the worker for correction (Self-Correction Loop).

4. Production Engineering Scenarios

01. Autonomous Creation of Complex Functionality

The user requests: "Add PDF report export with charts to the project." The supervisor invokes:

1. Research Worker — finds a suitable library and checks the license.
2. Backend Worker — creates an API endpoint and report generator.
3. Frontend Worker — adds a button in the UI and a loading indicator.
4. Tester Worker — runs Playwright tests.

02. Crew and Security Incident Resolution

The supervisor responds to an alert in Sentry, passes the stack trace to the diagnostics agent, validates the proposed hotfix with the testing agent, and creates a pull request.

5. Pitfalls, Common Mistakes & Security

• Deadlock Loops: The supervisor believes the task is not fully resolved and returns it to the worker. The worker returns the same code. Solution: set max_iterations = 5 with an error thrown to a human.
• Context Bleed: If a worker returns 10,000 lines of code, the supervisor's context quickly overflows. Workers should store code in the file system and return only status and diff.
• Single Point of Failure: If the supervisor model hallucinates and selects the wrong worker, the entire system goes astray. Clear invariant checks must be in place before invocation.

6. Strategic Conclusion for the Engineer of 2026

The Supervisor Pattern is the foundation of reliable industrial development for multi-agent systems. Instead of relying on "magical collaboration" among many agents in an open chat, the supervisor provides clear engineering dispatching, context isolation, and cost control.