The Supervisor Pattern
One boss, many specialists.
In a restaurant, the head chef doesn't cook every dish. They read each order, tell the stations what to do, and check every plate before it goes out. That's a supervisor. One agent decides who does what, and specialists do the work.
- The head chef
- Reads orders, directs stations
- Specialists do the work
A supervisor and a team
Here's the shape. The supervisor receives the request. It calls one specialist, which does its work and reports back. The supervisor looks at the result, and then decides who's next, or whether it's finished. All communication goes through the middle.
Building a supervisor
The supervisor is a model call, with a schema that only allows three choices. Billing and technical are simple nodes here, though each one could be a full agent. The important part is the edges. Each specialist returns to the supervisor. This customer's request has two parts. Run it. The supervisor sent the work to one, then to the other, and then it finished. Nobody wrote that order. It worked it out from the request.
from typing import Literal, TypedDict
from pydantic import BaseModel
from langgraph.graph import StateGraph, START, END
from llm import ask
class State(TypedDict):
request: str
notes: list
next: str
class Choice(BaseModel):
next: Literal["billing", "technical", "finish"]
def supervisor(state):
c = ask(f"Request: {state['request']}\nDone so far: {state['notes']}\n"
"Pick who should act next. Pick finish once both parts are handled.", schema=Choice)
print("Supervisor chose:", c.next)
return {"next": c.next}
def billing(state):
return {"notes": state["notes"] + ["Billing: refund of the $28 chain is approved."]}
def technical(state):
return {"notes": state["notes"] + ["Technical: use a 12-speed chain on that cassette."]}
g = StateGraph(State)
g.add_node("supervisor", supervisor)
g.add_node("billing", billing)
g.add_node("technical", technical)
g.add_edge(START, "supervisor")
g.add_conditional_edges("supervisor", lambda s: s["next"],
{"billing": "billing", "technical": "technical", "finish": END})
g.add_edge("billing", "supervisor")
g.add_edge("technical", "supervisor")
out = g.compile().invoke({"request": "Refund my wrong chain, and tell me which chain fits.",
"notes": [], "next": ""}, {"recursion_limit": 12})
print(out["notes"])Supervisor chose: billing Supervisor chose: technical Supervisor chose: finish ['Billing: refund of the $28 chain is approved.', 'Technical: use a 12-speed chain on that cassette.']
Also uses llm.py
from google import genai
from google.genai import types
client = genai.Client()
def ask(prompt, system=None, schema=None):
config = types.GenerateContentConfig(temperature=0.2, system_instruction=system)
if schema:
config.response_mime_type = "application/json"
config.response_schema = schema
r = client.models.generate_content(model="gemini-flash-latest",
config=config, contents=prompt)
return r.parsed if schema else r.textMaking supervisors work
Tips from real systems. Describe each specialist clearly, because the supervisor picks just as it would pick a tool. Keep what the specialists return short. Cap the total number of rounds. And log each decision. The supervisor is a single point of failure, but it's also a single place to look when things go wrong.
Summary
One boss, and clear specialists. It's simple and easy to control. But the boss can become a bottleneck. Next, a team without one.
Key takeaways- The supervisor routes all work
- Specialists report back
- Cap the rounds