Courses / Agentic AI from Scratch (Python)
Session 31 of 40
Several agents: a supervisor, hand-offs, and how agents pass work to each other
Notes
How to Build a Multi-Agent System in Python: Supervisor Agent, Hand-offs and Agent Communication
Agentic AI Foundations · Session 31
Before you start: what do I need before I build a multi-agent system?
You need the code folder for this session open in your terminal. It holds the new code/multi_agent.py (the supervisor, the policy agent and the ticket agent), a rewritten code/ask_copilot.py, four new role prompts in code/model_prompts/ (supervisor.md, policy_agent.md, ticket_agent.md and report.md), and the pieces carried over: the MCP ticket server in code/ticket_server.py with code/governance.py and code/call_server.py from session 30, and the policy search in code/helpdesk_rag.py. The router graph from session 29 is not in this folder: the supervisor replaces it. Install the libraries with pip install mcp langchain langchain-openai langchain-chroma langchain-community langchain-text-splitters, set LLM_BASE_URL, LLM_API_KEY, LLM_MODEL and EMBED_MODEL as in earlier sessions, then build the policy index and the ticket database with python code/build_index.py and python code/make_tickets_db.py. The demos call a model, so the settings must be in place. Have paper or a notes app ready for the flashcards and the model answer.
Summary: what is a multi-agent system, and when do I need one?
A multi-agent system splits a job between several agents, each with its own tools and its own instructions, and puts a coordinator in front of them. In this session the HelpDesk Copilot gets a policy agent, a ticket agent and a supervisor that calls them as tools. The supervisor decides which agent to ask, sends it the question and combines the answers into one reply. When the policy answer shows a ticket is needed, a hand-off passes a short summary to the ticket agent. You also learn how agents communicate: as tool calls and summaries inside one app, and through a shared protocol when they live in different products. The honest starting point is one agent; you split when it starts choosing badly.
Key concepts: what do the multi-agent terms mean?
| Term | Definition |
|---|---|
| Agent | A program that uses a model to decide the next step, calls tools and repeats until the job is done. |
| Multi-agent system | Several agents, each with its own tools and instructions, working on one job. |
| Supervisor | A main agent that coordinates other agents by calling them as tools. |
| Subagent | An agent that a supervisor calls as a tool, usually with a clean context on each call. |
| Hand-off | Passing the work, and what the next agent needs to know, from one agent to another. |
Command |
A LangGraph object a hand-off tool returns to update state and move to a new step or agent. |
| Typed report | A structured reply, such as AgentReport, that carries fields the next step can read. |
| Context window | The text a model can read in one call; a subagent call starts with a fresh one. |
| A2A protocol | An open protocol for communication between agent applications that do not share their internals with each other. |
| MCP | An open protocol for connecting an agent to tools and data, as in sessions 29 and 30. |
Explanations: how do supervisors, hand-offs and agent communication work?
Why would I use several agents instead of one?
Think of a person handed forty tools at once: they will pick the wrong one more often than a specialist who has five. The same happens with a model. LangChain’s documentation says a multi-agent design pays off once one agent holds so many tools that it starts making poor choices between them. It adds that one agent with the right tools and prompt can often reach similar results. Microsoft’s agent framework guidance goes further and advises writing a plain function whenever a function can handle the task.
So the order of tries is: a plain function, then one agent with the right tools, then several agents. For the Copilot, two agents earn their place because policy questions and ticket questions need different tools and different prompts. A specialist also works with a clean desk: by default subagents are stateless, so each call starts with a clean context window while the supervisor keeps the conversation.
What is a supervisor agent, and how do I build one?
At a help desk, the shift lead passes policy questions to one specialist and ticket questions to another, then writes the reply. A project manager works the same way: they do not do each task, but they know who does and they put the results together. A supervisor is that role in code. In LangChain’s subagents pattern a central main agent, often called a supervisor, coordinates subagents by calling them as tools. It is a full agent that keeps the conversation and decides which subagents to call across several turns, unlike a router, which is typically a single classification step.
The mechanism is simple: wrap a subagent as a tool. This is the shape of code/multi_agent.py, shortened:
policy_agent = create_agent(model, tools=[search_policy],
system_prompt=read_prompt("policy_agent.md"))
@tool("ask_policy_agent",
description="Answer a company policy question and name the source.")
def ask_policy_agent(question: str) -> str:
result = policy_agent.invoke(
{"messages": [{"role": "user", "content": question}]})
...
supervisor = create_agent(model, tools=[ask_policy_agent, ask_ticket_agent],
system_prompt=read_prompt("supervisor.md"))
The policy agent’s one tool, search_policy, calls session 19’s ask_helper and returns the answer with its source and section. The ticket agent is built the same way with two tools, lookup_ticket and create_ticket, which reach the tickets through the MCP server as the caller ticket-agent. The supervisor has no search or ticket tool of its own, and each of the three agents has its own prompt in code/model_prompts/.
The supervisor calls ask_policy_agent as it would call any tool and waits for the result; by default these calls are synchronous. Note that create_agent takes system_prompt=; the older prompt= name belongs to a retired helper. The course builds the supervisor this way, with agents wrapped as tools, and does not use a separate supervisor package.
"My laptop cannot join the office Wi-Fi. What does policy say,
and please raise a ticket."
|
Supervisor (main agent)
|-- tool call: ask_policy_agent --> policy agent --> search_policy
| <-- the policy answer and a "Hand-off summary" line
|-- hand-off: only that summary
'-- tool call: ask_ticket_agent --> ticket agent --> MCP ticket server
create_ticket waits for a person's yes
|
One reply: the rule, what happened to the ticket and the next step
The employee asks once and reads one reply. In the lab you also see the steps in between: python code/ask_copilot.py prints “What the agents did” before the reply.
What is a hand-off between agents?
Think of a nurse’s shift note. The next nurse gets a summary of the patient, not the whole night’s chat. A relay baton works the same way: one runner stops, the next starts, and the baton is what moves. A hand-off passes the work, and what the next agent needs to know, from one agent to another. LangChain describes a handoff tool whose core mechanism is returning a Command that updates state and triggers a move to a new step or agent. In that pattern behaviour changes dynamically based on state. One detail catches people out: a handoff tool that updates the messages has to include a tool message with the matching tool call id, or the conversation history becomes malformed.
The lab keeps the idea visible as one function you can test.
class AgentReport(BaseModel):
answer: str
needs_ticket: bool
summary: str
def hand_off(report):
if report.needs_ticket and report.summary.strip():
return report.summary.strip()
return None
The policy agent’s answer is turned into a typed report (code/model_prompts/report.md tells the model how to fill the three fields). When needs_ticket is true and there is a summary, ask_policy_agent adds it to its reply on a line that starts “Hand-off summary for the ticket agent:”. The supervisor’s prompt tells it to give exactly that text to ask_ticket_agent as its whole input, and the ticket agent prints what it received, so you can read the hand-off. When no ticket is needed, hand_off returns None and nothing is handed over.
Where is the person’s yes checked before a ticket is written?
A ticket changes data, so a person says yes first. The question is where that yes is enforced. A line in a prompt is a sign on a door: a model can be talked round it. In code/multi_agent.py the check is in the tool’s own code:
@tool("create_ticket")
def create_ticket(title: str) -> str:
"""Raise a new help desk ticket. A person is asked first."""
if not approver(title):
note("person said no: no ticket created")
return "A person said no. No ticket was created."
return call_ticket_tool("create_ticket", {"title": title},
"ticket-agent", READ_WRITE)
approver asks you Approve? (yes / no) in the terminal; it is a variable so a script can replace the person, as the Milestone 3 script does in session 32. Try the Wi-Fi question twice. Type no the first time and look the tickets up: nothing new exists. Type yes the second time: the new ticket gets the next id after the highest one in the table, T-1047 in the sample data, and you can look it up with call_ticket_tool('lookup_ticket', {'ticket_id': 'T-1047'}) from code/call_server.py. Run python code/make_tickets_db.py afterwards to reset the table.
To see the supervisor choose, ask a question that needs only one agent: python code/ask_copilot.py "How many days a week can I work from home?" and python code/ask_copilot.py "What is the status of ticket T-1043?". Which agent is used each time, and is a ticket asked about? A model’s choices vary, so if one run looks wrong, run it again before you call it a real problem.
How do agents communicate with each other?
Agents pass work in three ways, and which one you use depends on where the other agent lives.
| Where the other agent lives | How the work passes | Example in the Copilot |
|---|---|---|
| Inside the same app, called by a supervisor | A tool call out and a result back, with the supervisor keeping the conversation | ask_policy_agent("...") returns a text answer |
| Inside the same app, taking over the work | A hand-off: a summary, or a Command that updates shared state |
The summary “laptop cannot join office Wi-Fi” goes to the ticket agent |
| In a different product or from a different vendor | An open protocol between agents, such as A2A | Another team’s agent asked for a status, through its own service |
The A2A protocol describes itself as an open protocol for communication and interoperability between agent applications that keep their insides private. Its design lets agents interact without sharing their internal memory, tools or logic. A2A and MCP are complementary: one connects agents to tools and resources, the other enables collaboration between agents. In this course MCP is the tool side, as in sessions 29 and 30, and the supervisor pattern covers agents inside one app.
What goes wrong with several agents?
Three situations show up in a first multi-agent build.
- The ticket agent writes a reply about the wrong laptop. The whole chat was passed to it, and the extra text pulled it off the point. A short summary was the right hand-over.
- A simple lookup takes three model calls and costs more. One agent with the right tool would have done it. The split added steps without a reason.
- The hand-off tool’s reply leaves the history malformed. The tool updated the messages without the matching tool message the model expects.
| What you learned | The design decision | Where it shows |
|---|---|---|
| A single agent with too many tools chooses badly | Give each agent its own few tools | policy_agent, ticket_agent |
| Subagent calls start with a clean context | Keep the conversation on the supervisor | supervisor in code/multi_agent.py |
| A hand-off carries a summary | Pass summary, not the chat |
hand_off() in code/multi_agent.py |
| A prompt can be talked round | Check the person’s yes in the tool’s code | create_ticket and approver |
| A function or one agent may be enough | Try those first and split for a reason | Your design note |
Flashcards: how well do I know multi-agent supervisors and hand-offs?
Say the answer aloud before revealing it. Speaking is a different skill from reading, so practise both.
1. When is a multi-agent design worth it?
When one agent holds so many tools that it starts choosing between them badly. Before that, try a plain function or one agent with the right tools and prompt, which often gets similar results.2. What is a supervisor?
A main agent that coordinates other agents by calling them as tools. Like a shift lead at a help desk, it decides who to ask, sends the question and combines the answers into one reply.3. How do you make a subagent callable by a supervisor?
You wrap it as a tool: a function decorated with `@tool` that invokes the subagent with the question and returns the last message's content. The supervisor then lists that tool among its own.4. What does it mean that subagents are stateless by default?
Each call to a subagent starts with a clean context window, and the supervisor keeps the conversation. That keeps each specialist focused on one job.5. How is a supervisor different from a router?
A router is typically one classification step that sends a request somewhere. A supervisor is a full agent that keeps conversation context and decides which subagents to call across several turns.6. What is a hand-off?
Passing the work and what the next agent needs to know from one agent to another, like a nurse's shift note. Hand over a summary, not the whole conversation.7. What is a `Command` in a hand-off?
An object a hand-off tool returns to update state and trigger a move to a new step or agent. A tool that updates messages also needs the matching tool message with the right tool call id.8. How does the lab's hand-off decide whether to hand over?
The policy agent's answer becomes an `AgentReport`. When `needs_ticket` is true and there is a summary, `hand_off` returns the `summary` for the ticket agent; otherwise it returns nothing and no hand-over happens. A new ticket is still written only after a person's yes, checked in the `create_ticket` tool's code.9. How do agents in different products talk to each other?
Through an open protocol between agents, such as A2A, which lets separate agent applications communicate without sharing their internal memory or tools. MCP is the complementary protocol that connects an agent to tools and data.10. What is a sign a split into several agents was a mistake?
A simple request now takes several model calls and costs more, with no better answer. A single agent with the right tool, or a plain function, would have done it.Model answer: how do I explain a multi-agent design in an interview?
The core question this session answers: “A teammate asks: why would we use several agents, how does a supervisor use them, and how does one agent hand work to the next?”
Four beats a teammate listens for, in this order: one job each · supervisor calls agents as tools · hand over a summary · try one agent first. Skip any of these four and the answer is incomplete.
- One job each: each agent gets its own few tools and prompt.
- Supervisor calls agents as tools: it routes, sends and combines.
- Hand over a summary: the next agent gets what it needs, not the chat.
- Try one agent first: split when one agent chooses badly.
The full answer, said aloud:
(One job each) “A single agent with too many tools picks the wrong one more often. So I give a policy agent the policy search and a ticket agent the ticket tools, each with its own prompt.
(Supervisor calls agents as tools) A supervisor agent sits in front. I wrap each agent as a tool, so the supervisor decides which to ask, sends the question, waits for the result and writes one reply. The supervisor keeps the conversation; each subagent call starts fresh.
(Hand over a summary) When the policy answer shows a ticket is needed, the next agent gets a short summary of the problem, not the whole chat. In LangChain that can be a tool that returns a command updating the state.
(Try one agent first) I would add agents once a single agent with the right tools starts choosing badly. If a plain function does the job, I use the function.“
Missing a beat is a failure state. The follow-up question lands where you went quiet: skip the last beat and you are asked why you did not use one agent. Practise until the four come out without prompting, then stop talking and let the questions come.
Why this matters: why do multi-agent designs matter at work?
In a conversation with a teammate or manager: teams are quick to say “let’s use several agents”. The people who build well ask when one agent stops being enough, and what each agent hands to the next. Your four beats give that answer.
On the job: a support lead reviewing a hard case needs to see which agent did what and who decided. A supervisor that names the agents it called gives that record, and a typed hand-off is something you can test.
In the rest of this course: session 32 compares other frameworks and brings the multi-agent Copilot together as Milestone 3. Session 33 traces these calls in Langfuse, and session 34 scores whether each agent picked the right tool.
After this unit: what do I do after this lesson, and what comes next?
Assignment. Run python code/ask_copilot.py twice on the Wi-Fi question, say no the first time and yes the second, and read the summary the ticket agent received. Project step. In code/multi_agent.py, build a policy agent, a ticket agent and a supervisor that calls them as tools, add AgentReport and hand_off(), and rewrite code/ask_copilot.py to run the supervisor. The build prompts are code/prompts/1-write-multi-agent.md and code/prompts/2-write-ask-copilot.md. Keep the write tool behind the person’s yes. The brief for the project work is the project file. Next session: other frameworks, and Milestone 3.
Want help building this with someone?
Tell us what you are working on and we will write back about a mentor-led cohort, live sessions or 1:1 training. It is only an enquiry: you choose whether to go further.
Ask about mentor-led trainingTechEazy Consulting training material — not affiliated with or endorsed by OpenAI, Anthropic, LangChain or any other company named in this course.