Agentic Architectures

Catalogue / Multi-agent Coordination

Supervisor & Specialists

One coordinator splits the work among specialist agents

Shape
orchestrator
Model calls
2 + specialists × turns (often 5 to 12)
Latency
medium
Complexity
medium

Also known as Orchestrator–Workers, Hierarchical team

1

What if one agent cannot be good at every part of the job?

A supervisor reads the task, cuts it into subtasks and hands each one to a specialist with its own instructions and tools. The supervisor keeps the overall picture, and a final step merges the contributions into one result.

You may need it if

  • The work spans different skills, such as research, calculation and writing.
  • A single prompt has grown long and the agent confuses its roles.
  • Parts of the work are independent and could run at the same time.
2

When does a team of agents cost more than it returns?

Use it when

  • Subtasks need different tools, sources or instructions.
  • The division of work can be decided from the task before any work starts.
  • Specialists can work without talking to each other, only to the supervisor.

Avoid it when

What it costs

Model calls
2 + specialists × turns (often 5 to 12)
Latency
medium
Complexity
medium
3

How does work travel between the supervisor and its team?

A hub and spokes. The supervisor assigns a subtask, a specialist returns a result, and the supervisor decides what to assign next. When every subtask is covered, a synthesizer writes the single final result.

subtask toassignresult returnedevery subtaskcoveredTask: The overall goal, with any constraints on the final deliverable.TaskSupervisor: Splits the task, assigns subtasks, checks returned work and decides when to stop.SupervisorSpecialists: Each one handles a single kind of subtask with its own instructions and tools.SpecialistsSynthesizer: Merges the accepted contributions into one coherent result.SynthesizerResult: The merged deliverable, with a note of who contributed what.Result
  1. Step 1 of 4

    The supervisor plans the split

    The supervisor reads the task and lists the subtasks, naming the specialist for each. It does none of the work itself.

  2. Step 2 of 4

    Subtasks go out

    Each specialist receives one subtask and only the context it needs. Independent subtasks can be sent at the same time.

  3. Step 3 of 4

    Results come back to the hub

    Specialists report to the supervisor, never to each other. The supervisor checks each result and may send a follow-up subtask.

  4. Step 4 of 4

    One voice at the end

    When nothing is missing, the synthesizer turns the accepted contributions into a single result with one style and no repetition.

What each part does
Task
The overall goal, with any constraints on the final deliverable.
Supervisor
Splits the task, assigns subtasks, checks returned work and decides when to stop.
Specialists
Each one handles a single kind of subtask with its own instructions and tools.
Synthesizer
Merges the accepted contributions into one coherent result.
Result
The merged deliverable, with a note of who contributed what.
  • Supervisor → Specialists: subtask to assign
  • Specialists → Supervisor: result returned
  • Supervisor → Synthesizer: every subtask covered

Where it connects

Entry
task
TaskPlan

A goal that can be divided into subtasks, or a plan whose steps are the subtasks.

Exit
result
AnswerDocument

When: The supervisor judges every subtask covered and the synthesizer has merged the results.

One merged deliverable, followed by the list of subtasks and the specialist that handled each.

4

What do I ask my assistant to set up?

The agents to launch

Supervisor

Split the task into at most five subtasks and name one specialist role for each. After each returned result, decide whether it is acceptable, needs a follow-up, or whether all subtasks are covered. Resolve contradictions yourself. Never do a specialist's work.

Sees: The task and every result returned by the specialists.

Specialist, one per specialist role named by the supervisor, at most five

You hold one role. Complete the single subtask you are given, using only your own expertise and tools. Return the result, then list anything you could not determine.

Sees: Its own subtask and the minimum context the supervisor attaches. Not the other specialists' work.

Synthesizer

Write the final deliverable from the accepted contributions. Use one consistent style, remove repetition and add no new facts.

Sees: The task and the contributions the supervisor accepted.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Supervisor & Specialists" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Supervisor & Specialists
One coordinator splits the work among specialist agents.
Input: the task above. It must provide: A goal that can be divided into subtasks, or a plan whose steps are the subtasks. If something essential is missing, ask for it before starting.

Agents to launch:
- Supervisor: Split the task into at most five subtasks and name one specialist role for each. After each returned result, decide whether it is acceptable, needs a follow-up, or whether all subtasks are covered. Resolve contradictions yourself. Never do a specialist's work.
  Context for this agent: The task and every result returned by the specialists.
- Specialist (one per specialist role named by the supervisor, at most five): You hold one role. Complete the single subtask you are given, using only your own expertise and tools. Return the result, then list anything you could not determine.
  Context for this agent: Its own subtask and the minimum context the supervisor attaches. Not the other specialists' work.
- Synthesizer: Write the final deliverable from the accepted contributions. Use one consistent style, remove repetition and add no new facts.
  Context for this agent: The task and the contributions the supervisor accepted.

Procedure:
1. Launch the supervisor on the task and obtain the list of subtasks with their specialist roles.
2. Launch one specialist per role as a separate agent. Run independent subtasks in parallel.
3. Return each result to the supervisor. If it asks for a follow-up, send that subtask to the same specialist. Allow at most two follow-ups per specialist.
4. When the supervisor declares every subtask covered, launch the synthesizer on the accepted contributions.

Stop rule: Stop when the synthesizer has delivered, or when a specialist has used its two follow-ups without an acceptable result. In that case report the gap.

Exit:
- `result`, when: The supervisor judges every subtask covered and the synthesizer has merged the results. Deliver: One merged deliverable, followed by the list of subtasks and the specialist that handled each.

# Final deliverable
The merged result, then a table of subtasks with the specialist role, the status and any open gap.

The same thing in code

LangGraph, python, package langgraph
import operator
from typing import Annotated, Literal, TypedDict

from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from langgraph.types import Send
from pydantic import BaseModel, Field

MAX_ROLES, MAX_FOLLOW_UPS = 5, 2
SUPERVISOR = ("Split the task into at most five subtasks and name one specialist role for each. After each "
              "returned result, accept it or ask a precise follow-up. Never do a specialist's work.")
SYNTHESIZER = ("Write the final deliverable from the accepted contributions. Use one consistent style, "
               "remove repetition and add no new facts.")


class Subtask(BaseModel):
    role: str
    subtask: str
    context: str  # the minimum context this specialist needs


class Assignment(BaseModel):
    subtasks: list[Subtask] = Field(max_length=MAX_ROLES)


class Review(BaseModel):
    decision: Literal["accept", "follow_up"]
    follow_up: str


class Work(TypedDict):
    role: str
    prompt: str
    status: str  # open, accepted or gap
    result: str
    follow_ups: int


class State(TypedDict):
    task: str
    work: list[Work]
    returned: Annotated[list[tuple[int, str]], operator.add]
    seen: int
    result: str


class SpecialistInput(TypedDict):  # all a specialist sees: its role and its subtask
    index: int
    role: str
    prompt: str


model = init_chat_model("anthropic:claude-sonnet-5-5")


async def supervisor(state: State) -> dict:
    if not state["work"]:
        raw = await model.with_structured_output(Assignment).ainvoke([SystemMessage(SUPERVISOR), HumanMessage(state["task"])])
        subs = Assignment.model_validate(raw).subtasks[:MAX_ROLES]
        return {"work": [Work(role=s.role, prompt=f"{s.subtask}\n\nContext: {s.context}", status="open", result="", follow_ups=0) for s in subs]}
    work = [Work(**w) for w in state["work"]]
    for i, text in state["returned"][state["seen"]:]:
        check = f"Task: {state['task']}\nSubtask for {work[i]['role']}: {work[i]['prompt']}\nReturned result:\n{text}"
        review = Review.model_validate(await model.with_structured_output(Review).ainvoke([SystemMessage(SUPERVISOR), HumanMessage(check)]))
        work[i]["result"] = text
        if review.decision == "accept":
            work[i]["status"] = "accepted"
        elif work[i]["follow_ups"] == MAX_FOLLOW_UPS:  # two follow-ups spent: a gap
            work[i]["status"] = "gap"
        else:
            work[i]["follow_ups"] += 1
            work[i]["prompt"] += f"\n\nYour previous result:\n{text}\n\nFollow-up: {review.follow_up}"
    return {"work": work, "seen": len(state["returned"])}


def assign(state: State) -> list[Send] | str:
    if any(w["status"] == "gap" for w in state["work"]):
        return END  # stop rule: report the gap
    open_work = [i for i, w in enumerate(state["work"]) if w["status"] == "open"]
    if not open_work:
        return "synthesizer"
    # fan-out: one specialist per open subtask, run in parallel
    return [Send("specialist", SpecialistInput(index=i, role=state["work"][i]["role"], prompt=state["work"][i]["prompt"])) for i in open_work]


async def specialist(state: SpecialistInput) -> dict:
    brief = (f"You hold one role: {state['role']}. Complete the single subtask you are given, using only your own "
             "expertise and tools. Return the result, then list anything you could not determine.")
    reply = await model.ainvoke([SystemMessage(brief), HumanMessage(state["prompt"])])
    return {"returned": [(state["index"], reply.text)]}


async def synthesizer(state: State) -> dict:
    accepted = "\n\n".join(f"[{w['role']}]\n{w['result']}" for w in state["work"])
    reply = await model.ainvoke([SystemMessage(SYNTHESIZER), HumanMessage(f"Task: {state['task']}\n\n{accepted}")])
    return {"result": reply.text}


builder = StateGraph(State)
builder.add_node("supervisor", supervisor)
builder.add_node("specialist", specialist, input_schema=SpecialistInput)
builder.add_node("synthesizer", synthesizer)
builder.add_edge(START, "supervisor")
builder.add_conditional_edges("supervisor", assign, ["specialist", "synthesizer", END])
builder.add_edge("specialist", "supervisor")
builder.add_edge("synthesizer", END)
graph = builder.compile()


async def run(task: str) -> dict:
    s = await graph.ainvoke({"task": task, "work": [], "returned": [], "seen": 0, "result": ""})
    table = [{"role": w["role"], "status": w["status"], "follow_ups": w["follow_ups"]} for w in s["work"]]
    return {"result": s["result"] or None, "table": table}

Give each specialist role its own tools; here they rely on instructions alone, and the supervisor reviews each result on its own, not against the others.

Claude Agent SDK, python, package claude-agent-sdk
import asyncio
import re
from typing import Literal

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel, Field

MAX_ROLES, MAX_FOLLOW_UPS = 5, 2


class Subtask(BaseModel):
    role: str
    subtask: str
    context: str  # the minimum context this specialist needs


class Assignment(BaseModel):
    subtasks: list[Subtask] = Field(max_length=MAX_ROLES)


class Review(BaseModel):
    decision: Literal["accept", "follow_up"]
    follow_up: str


AGENTS = {
    "supervisor": AgentDefinition(
        description="Splits the task, assigns subtasks and checks returned work.",
        prompt="Split the task into at most five subtasks and name one specialist role for each. After each "
               "returned result, accept it or ask a precise follow-up. Never do a specialist's work.",
    ),
    "synthesizer": AgentDefinition(
        description="Merges accepted contributions into one deliverable.",
        prompt="Write the final deliverable from the accepted contributions. Use one consistent style, "
               "remove repetition and add no new facts.",
    ),
}


def slug(role: str) -> str:
    return re.sub(r"[^a-z0-9]+", "-", role.lower()).strip("-")


async def delegate(agent: str, message: str, schema: type[BaseModel] | None = None) -> ResultMessage:
    # one fresh session per call, so each sub-agent sees only the message it is given
    options = ClaudeAgentOptions(
        agents=AGENTS,
        allowed_tools=["Agent"],
        output_format={"type": "json_schema", "schema": schema.model_json_schema()} if schema else None,
    )
    prompt = f"Delegate this to the {agent} agent, passing it verbatim, and return its reply unchanged:\n\n{message}"
    async for msg in query(prompt=prompt, options=options):
        if isinstance(msg, ResultMessage):
            return msg
    raise RuntimeError("no result")


async def handle(task: str, sub: Subtask) -> dict[str, str]:
    name, prompt, text, ask = slug(sub.role), f"{sub.subtask}\n\nContext: {sub.context}", "", ""
    for _ in range(MAX_FOLLOW_UPS + 1):  # first attempt plus at most two follow-ups
        text = (await delegate(name, prompt)).result or ""
        check = f"Task: {task}\nSubtask for {sub.role}: {sub.subtask}\nReturned result:\n{text}"
        review = Review.model_validate((await delegate("supervisor", check, Review)).structured_output)
        if review.decision == "accept":
            return {"role": sub.role, "subtask": sub.subtask, "status": "accepted", "result": text, "gap": ""}
        ask = review.follow_up
        prompt = f"{sub.subtask}\n\nContext: {sub.context}\n\nYour previous result:\n{text}\n\nFollow-up: {ask}"
    return {"role": sub.role, "subtask": sub.subtask, "status": "gap", "result": text, "gap": ask}


async def run(task: str) -> dict:
    plan = await delegate("supervisor", f"Split this task:\n{task}", Assignment)
    subtasks = Assignment.model_validate(plan.structured_output).subtasks[:MAX_ROLES]
    for sub in subtasks:  # one sub-agent per role the supervisor named
        AGENTS[slug(sub.role)] = AgentDefinition(
            description=f"Specialist: {sub.role}.",
            prompt=f"You hold one role: {sub.role}. Complete the single subtask you are given, using only your "
                   "own expertise and tools. Return the result, then list anything you could not determine.",
        )
    # independent subtasks run in parallel; each specialist sees only its subtask and context
    outcomes = await asyncio.gather(*(handle(task, s) for s in subtasks))
    table = [{k: o[k] for k in ("subtask", "role", "status", "gap")} for o in outcomes]
    if any(o["status"] == "gap" for o in outcomes):
        return {"result": None, "table": table}  # stop rule: report the gap instead of synthesising
    accepted = "\n\n".join(f"[{o['role']}]\n{o['result']}" for o in outcomes)
    final = await delegate("synthesizer", f"Task: {task}\n\nAccepted contributions:\n{accepted}")
    return {"result": final.result, "table": table}

Give each specialist role its own tools; here they rely on instructions alone, and the supervisor reviews each result on its own, not against the others.

OpenAI Agents SDK, python, package openai-agents
import asyncio
from typing import Literal

from agents import Agent, Runner, TResponseInputItem
from pydantic import BaseModel, Field

MAX_ROLES, MAX_FOLLOW_UPS = 5, 2
SUPERVISOR = ("Split the task into at most five subtasks and name one specialist role for each. After each "
              "returned result, accept it or ask a precise follow-up. Never do a specialist's work.")


class Subtask(BaseModel):
    role: str
    subtask: str
    context: str  # the minimum context this specialist needs


class Assignment(BaseModel):
    subtasks: list[Subtask] = Field(max_length=MAX_ROLES)


class Review(BaseModel):
    decision: Literal["accept", "follow_up"]
    follow_up: str


supervisor = Agent(name="Supervisor", instructions=SUPERVISOR, output_type=Assignment)
reviewer = supervisor.clone(output_type=Review)
synthesizer = Agent(
    name="Synthesizer",
    instructions="Write the final deliverable from the accepted contributions. Use one consistent style, "
                 "remove repetition and add no new facts.",
)


def specialist(role: str) -> Agent:
    return Agent(
        name=role,
        instructions=f"You hold one role: {role}. Complete the single subtask you are given, using only your "
                     "own expertise and tools. Return the result, then list anything you could not determine.",
        tools=[],  # plug in this role's own tools
    )


async def handle(task: str, sub: Subtask) -> dict[str, str]:
    agent = specialist(sub.role)
    # the specialist sees its subtask and the attached context, not the other specialists' work
    items: list[TResponseInputItem] = [{"role": "user", "content": f"{sub.subtask}\n\nContext: {sub.context}"}]
    text, ask = "", ""
    for _ in range(MAX_FOLLOW_UPS + 1):  # first attempt plus at most two follow-ups
        result = await Runner.run(agent, items)
        text = result.final_output_as(str)
        check = f"Task: {task}\nSubtask for {sub.role}: {sub.subtask}\nReturned result:\n{text}"
        review = (await Runner.run(reviewer, check)).final_output_as(Review)
        if review.decision == "accept":
            return {"role": sub.role, "subtask": sub.subtask, "status": "accepted", "result": text, "gap": ""}
        ask = review.follow_up
        items = result.to_input_list() + [{"role": "user", "content": ask}]  # same specialist, same thread
    return {"role": sub.role, "subtask": sub.subtask, "status": "gap", "result": text, "gap": ask}


async def run(task: str) -> dict:
    assignment = (await Runner.run(supervisor, task)).final_output_as(Assignment)
    # independent subtasks run in parallel, each reporting back to the supervisor
    outcomes = await asyncio.gather(*(handle(task, s) for s in assignment.subtasks[:MAX_ROLES]))
    table = [{k: o[k] for k in ("subtask", "role", "status", "gap")} for o in outcomes]
    if any(o["status"] == "gap" for o in outcomes):
        return {"result": None, "table": table}  # stop rule: report the gap instead of synthesising
    accepted = "\n\n".join(f"[{o['role']}]\n{o['result']}" for o in outcomes)
    final = await Runner.run(synthesizer, f"Task: {task}\n\nAccepted contributions:\n{accepted}")
    return {"result": final.final_output_as(str), "table": table}

Give each specialist role its own tools; here they rely on instructions alone, and the supervisor reviews each result on its own, not against the others.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { Output, ToolLoopAgent, type ModelMessage } from 'ai';
import { z } from 'zod';

const MAX_ROLES = 5;
const MAX_FOLLOW_UPS = 2;
const model = anthropic('claude-sonnet-5-5');
const SUPERVISOR =
  'Split the task into at most five subtasks and name one specialist role for each. After each ' +
  "returned result, accept it or ask a precise follow-up. Never do a specialist's work.";

const subtaskSchema = z.object({ role: z.string(), subtask: z.string(), context: z.string() });
type Subtask = z.infer<typeof subtaskSchema>;

const supervisor = new ToolLoopAgent({
  model,
  instructions: SUPERVISOR,
  output: Output.object({ schema: z.object({ subtasks: z.array(subtaskSchema).max(MAX_ROLES) }) }),
});
const reviewer = new ToolLoopAgent({
  model,
  instructions: SUPERVISOR,
  output: Output.object({ schema: z.object({ decision: z.enum(['accept', 'follow_up']), followUp: z.string() }) }),
});
const synthesizer = new ToolLoopAgent({
  model,
  instructions:
    'Write the final deliverable from the accepted contributions. Use one consistent style, ' +
    'remove repetition and add no new facts.',
});

const specialist = (role: string) =>
  new ToolLoopAgent({
    model,
    instructions:
      `You hold one role: ${role}. Complete the single subtask you are given, using only your ` +
      'own expertise and tools. Return the result, then list anything you could not determine.',
    tools: {}, // plug in this role's own tools
  });

async function handle(task: string, sub: Subtask) {
  const agent = specialist(sub.role);
  // the specialist sees its subtask and the attached context, not the other specialists' work
  const messages: ModelMessage[] = [{ role: 'user', content: `${sub.subtask}\n\nContext: ${sub.context}` }];
  let text = '';
  let ask = '';
  for (let attempt = 0; attempt <= MAX_FOLLOW_UPS; attempt++) { // first attempt plus at most two follow-ups
    const result = await agent.generate({ messages });
    text = result.text;
    const { output: review } = await reviewer.generate({
      prompt: `Task: ${task}\nSubtask for ${sub.role}: ${sub.subtask}\nReturned result:\n${text}`,
    });
    if (review.decision === 'accept') return { ...sub, status: 'accepted', result: text, gap: '' };
    ask = review.followUp;
    messages.push(...result.response.messages, { role: 'user', content: ask }); // same specialist, same thread
  }
  return { ...sub, status: 'gap', result: text, gap: ask };
}

export async function run(task: string) {
  const { output: plan } = await supervisor.generate({ prompt: task });
  // independent subtasks run in parallel, each reporting back to the supervisor
  const outcomes = await Promise.all(plan.subtasks.slice(0, MAX_ROLES).map((s) => handle(task, s)));
  const table = outcomes.map(({ subtask, role, status, gap }) => ({ subtask, role, status, gap }));
  if (outcomes.some((o) => o.status === 'gap')) return { result: null, table }; // stop rule: report the gap
  const accepted = outcomes.map((o) => `[${o.role}]\n${o.result}`).join('\n\n');
  const { text } = await synthesizer.generate({ prompt: `Task: ${task}\n\nAccepted contributions:\n${accepted}` });
  return { result: text, table };
}

Give each specialist role its own tools; here they rely on instructions alone, and the supervisor reviews each result on its own, not against the others.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • A supervisor that starts answering subtasks itself removes the benefit of specialists. Restrict it to assigning and checking.
  • Passing the whole conversation to every specialist recreates the crowded context the pattern is meant to avoid.
  • More specialists means more hand-offs. Above five roles, coordination errors usually outweigh the gain.

Chain it

Its result can feed

It can take the result of

Directly