lesson-17

20 MIN READ | UPDATED: 2026-05-07

Hey there, future AI architects! Welcome back to our LangGraph Masterclass. I'm your old friend—the mentor who is picky about technology and even pickier about teaching. Today, we're going to inject a real "brain" into our "AI Content Agency"—a "Supervisor Agent" that doesn't do the grunt work itself but orchestrates the big picture and commands the entire operation.

Imagine this: your content agency now has experts like a Researcher, a Writer, and an Editor, each with their own unique set of skills. But here's the catch: when a client throws a request your way, who decides whether it needs market research first, or if it's ready to be written immediately, or if it requires data collection? You can't just have the Writer asking the client, "What should I write?" That's just unprofessional!

This is the core pain point we are solving today: an intelligent dispatcher, a supervisor who only delegates tasks and never gets their hands dirty. It will serve as our central command, ensuring that every user request lands precisely in the hands of the most suitable expert.

🎯 Learning Objectives for This Episode

In this episode, you won't just be typing a few lines of code; you'll be grasping the essence of multi-agent collaboration and mastering the core skills to build an intelligent dispatch system. Specifically, you will:

Understand the core value and positioning of the Supervisor Agent: Why do we need a dispatcher who "doesn't work"? What is its strategic significance in a multi-agent system?
Master the implementation techniques of the Supervisor pattern in LangGraph: Learn how to leverage LangGraph's StateGraph and Conditional Edges to build a flexible and powerful supervisor agent.
Learn how to design efficient routing strategies: Master the essence of Prompt Engineering so the Supervisor can intelligently route tasks to specific agents like the Researcher or Writer based on user needs.
Elevate the overall intelligence and efficiency of the AI agency: By introducing a Supervisor, our AI content agency will gain stronger adaptability and automation capabilities, reducing manual intervention and boosting response speed.

📖 Principle Analysis

Why Do We Need a Supervisor Agent?

In our AI Content Agency project, as the number of agents increases and task complexity grows, explicitly defining the task flow becomes crucial. Initially, we might have had a Planner Agent break down tasks directly, but this still lacks flexibility in certain scenarios. For example:

Ambiguity in requirements: A user says, "I need an article about AI." This could mean researching the latest AI breakthroughs first, or it could just be a primer on basic AI concepts. Who makes that call?
Optimal resource allocation: If a request is ready to be written, we shouldn't waste time researching. Conversely, writing blindly without background knowledge severely compromises quality. Who makes this decision?
Scalability challenges: When we add more agents in the future (like an SEO Expert, Translator, or Image Generator), how do we ensure these new agents integrate seamlessly into the workflow and are invoked correctly?

The Supervisor Agent exists to solve these exact problems. It acts as a "decision node," a "higher-order brain" whose core responsibility is: based on its understanding of the user input and current system state, deciding which expert agent should handle the task next. It doesn't execute specific business logic (like writing or researching); it just "directs traffic."

How the Supervisor Agent Works

The core idea behind implementing a Supervisor Agent in LangGraph is utilizing the graph's Conditional Edges.

Supervisor as an independent LLM node: We configure a dedicated LLM with a very explicit instruction: analyze the user's request and output a pre-defined operational command (e.g., "RESEARCH", "WRITE", "FINISH").
State passing: The entire workflow shares an AgentState, which contains information like the original user request and the Supervisor's decision.
Conditional routing function: We define a routing function that checks the decision output by the Supervisor in the AgentState. Based on this decision, the routing function dynamically determines the next node in the graph.
- If the Supervisor says "RESEARCH", route to the Researcher Agent.
- If the Supervisor says "WRITE", route to the Writer Agent.
- If the Supervisor says "FINISH", end the current process.
- We can expand this in the future: if the Supervisor says "EDIT", route to the Editor Agent.

The power of this pattern lies in its complete separation of decision logic from execution logic. The Supervisor focuses on "what to do," while the specific agents focus on "how to do it." This makes the system highly modular, easier to maintain, and highly scalable.

Core Concepts Illustrated with Mermaid

Let's use a Mermaid diagram to visually understand the Supervisor Agent's workflow:

graph LR
    A[User Request] --> B(Supervisor Agent);

    subgraph Supervisor Agent Logic
        B -- Analyze User Request --> C{Decision: Which Agent is best?};
        C -- "Needs Research" --> D[Researcher Agent];
        C -- "Ready to Write" --> E[Writer Agent];
        C -- "No Task or Completed" --> F[END];
    end

    D -- Research completed, may return to Supervisor or end directly --> F;
    E -- Writing completed --> F;

    style A fill:#f9f,stroke:#333,stroke-width:2px;
    style B fill:#bbf,stroke:#333,stroke-width:2px;
    style C fill:#ccf,stroke:#333,stroke-width:2px;
    style D fill:#dfd,stroke:#333,stroke-width:2px;
    style E fill:#ffd,stroke:#333,stroke-width:2px;
    style F fill:#eee,stroke:#333,stroke-width:2px;

Diagram Explanation:

User Request: The starting point of everything. A client submits a content creation request to our AI Content Agency.
Supervisor Agent: Receives the user request. It is the core of this episode's design—an independent LLM that doesn't generate content directly but analyzes the request to make the next decision.
Decision: The core output of the Supervisor Agent. Based on a preset Prompt, it judges the nature of the request and outputs a clear instruction (e.g., "RESEARCH" or "WRITE").
Conditional Routing: This is where the LangGraph magic happens. Based on the Supervisor's decision, the workflow is dynamically routed to different expert agents.
- Researcher Agent: If the Supervisor determines that information gathering or background research is needed first, the task is dispatched to the Researcher.
- Writer Agent: If the Supervisor determines that content creation can begin immediately, the task is dispatched to the Writer.
- END: In this episode's simplified model, the process ends once the Researcher or Writer completes their task. Alternatively, the Supervisor can directly judge the status as "no task" or "completed," ending the process immediately.

Through this architecture, our AI Content Agency becomes much smarter and more flexible. The Supervisor acts like an experienced product manager: upon receiving a user request, it quickly determines which department's expert should execute it, drastically improving the agency's overall operational efficiency.

💻 Hands-on Code Practice (Application in the Agency Project)

Alright, enough theory—nothing beats actual code. It's time to put our concepts into practice and integrate the Supervisor Agent into our AI content agency.

We will use Python and langgraph to build this system.

import os
from typing import TypedDict, Annotated, List, Union
import operator

from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langgraph.graph import StateGraph, END

# Ensure you have the OPENAI_API_KEY environment variable set up
# os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"

# 1. Define our AgentState
class AgentState(TypedDict):
    """
    AgentState represents the shared state in LangGraph.
    It will contain the user request, supervisor's decision, and outputs from different agents.
    """
    user_request: str
    supervisor_decision: Annotated[str, operator.setitem] # Supervisor's decision, used for routing
    research_output: Annotated[str, operator.setitem]     # Researcher's output
    writing_output: Annotated[str, operator.setitem]      # Writer's output
    messages: Annotated[List[BaseMessage], operator.add] # Message history, allowing Agents to view context

# 2. Initialize our LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

# 3. Define the Supervisor Agent
def create_supervisor_agent():
    """
    Creates a Supervisor Agent. It's an LLM that decides the next action based on the user request.
    It doesn't perform specific tasks, only routes decisions.
    """
    system_prompt = """
    你是一个AI内容机构的主管调度员。你的任务是根据用户的请求，决定将任务分发给哪个专家Agent。
    你不能自己执行内容创作或研究。你的职责是分析请求，并输出一个明确的指令，指出下一步应该由谁来处理。
    
    可用的专家Agent有：
    - 'researcher': 当用户请求需要进行信息搜集、背景研究、事实核查或获取最新数据时。
    - 'writer': 当用户请求可以直接进行内容创作、文章撰写、文案生成或内容润色时。
    - 'FINISH': 当请求明确表示无需进一步处理，或者已经完成时。
    
    你的输出必须是上述三个字符串之一，不要包含其他任何内容。
    例如：
    用户请求: "我需要一篇关于 LangGraph Supervisor 模式的简介。"
    你的输出: "writer"
    
    用户请求: "我需要关于 LangChain 最新版本更新的资料，然后写一份总结报告。"
    你的输出: "researcher"
    
    用户请求: "谢谢，我已经拿到资料了。"
    你的输出: "FINISH"
    
    请严格按照这个格式输出，不要有额外的解释或寒暄。
    
    You are the supervisor dispatcher for an AI content agency. Your task is to determine which expert agent
    should handle the user's request. You do not perform content creation or research yourself.
    Your role is to analyze the request and output a clear instruction indicating who should handle the next step.
    
    Available expert agents are:
    - 'researcher': When the user request requires information gathering, background research, fact-checking, or obtaining the latest data.
    - 'writer': When the user request can directly proceed with content creation, article writing, copywriting, or content refinement.
    - 'FINISH': When the request clearly indicates no further processing is needed, or the task is complete.
    
    Your output must be one of the three strings above, without any additional content.
    Example:
    User request: "I need an introduction to the LangGraph Supervisor pattern."
    Your output: "writer"
    
    User request: "I need information about the latest LangChain updates, then write a summary report."
    Your output: "researcher"
    
    User request: "Thanks, I have the information."
    Your output: "FINISH"
    
    Please strictly adhere to this output format, without any extra explanations or greetings.
    """
    prompt = ChatPromptTemplate.from_messages([
        ("system", system_prompt),
        ("human", "{user_request}")
    ])
    return prompt | llm.bind(stop=["\n"]) # Use bind(stop=["\n"]) to ensure only one line of decision is output

supervisor_agent = create_supervisor_agent()

# 4. Define Researcher Agent and Writer Agent (simplified, for routing demonstration only)

def researcher_node(state: AgentState):
    """
    Researcher Agent node. Here, it simply simulates a research process and returns a result.
    """
    print(f"\n--- Researcher Agent 正在处理请求: {state['user_request']} ---")
    # In a real project, this would involve calling search tools, database queries, etc.
    research_result = f"根据请求 '{state['user_request']}'，我搜集到了以下关键信息：\n" \
                      f"1. LangGraph Supervisor模式是用于多Agent系统中的任务调度和路由。\n" \
                      f"2. 它通过一个独立的LLM来决策，将任务分发给不同的执行Agent。\n" \
                      f"3. 核心是利用LangGraph的条件边实现动态工作流。"
    print("--- 研究完成 ---")
    return {"research_output": research_result, "messages": [AIMessage(content=f"Research completed: {research_result}")]}

def writer_node(state: AgentState):
    """
    Writer Agent node. It generates content based on the user request and potential research output.
    """
    print(f"\n--- Writer Agent 正在处理请求: {state['user_request']} ---")
    content_to_write = state['user_request']
    if state.get('research_output'):
        content_to_write += f"\n\n参考研究结果：\n{state['research_output']}"
    
    # In a real project, this would involve calling an LLM to generate high-quality content
    writing_result = f"以下是根据您的请求生成的文章：\n\n" \
                     f"**标题：{state['user_request']}**\n\n" \
                     f"尊敬的客户，根据您的需求，我们为您精心撰写了以下内容。\n" \
                     f"内容核心旨在围绕 '{state['user_request']}' 展开，力求精准传达信息。\n" \
                     f"如果之前有研究结果，则会在内容中融入研究发现，确保内容的深度和广度。\n" \
                     f"（此处省略长篇内容，仅为演示）"
    print("--- 写作完成 ---")
    return {"writing_output": writing_result, "messages": [AIMessage(content=f"Writing completed: {writing_result}")]}

# 5. Define the router function
def route_supervisor_decision(state: AgentState):
    """
    Decides the next node to execute based on the Supervisor Agent's decision.
    """
    decision = state['supervisor_decision'].strip().lower() # Clean and convert to lowercase to ensure matching
    print(f"\n--- Supervisor 决策: {decision} ---")
    if "researcher" in decision:
        return "researcher_node"
    elif "writer" in decision:
        return "writer_node"
    elif "finish" in decision:
        return "END"
    else:
        # Fallback mechanism to prevent unexpected output from Supervisor
        print(f"警告：Supervisor 输出了无法识别的决策: {decision}。默认路由到 Writer。")
        return "writer_node" # Default routing, or an error could be raised

# 6. Construct the LangGraph
workflow = StateGraph(AgentState)

# Add nodes
workflow.add_node("supervisor", lambda state: {"supervisor_decision": supervisor_agent.invoke({"user_request": state["user_request"]}).content, "messages": [AIMessage(content=f"Supervisor decided: {state['supervisor_decision']}")]})
workflow.add_node("researcher_node", researcher_node)
workflow.add_node("writer_node", writer_node)

# Set the entry point
workflow.set_entry_point("supervisor")

# Add conditional edges: from supervisor to different agents
workflow.add_conditional_edges(
    "supervisor",
    route_supervisor_decision,
    {
        "researcher_node": "researcher_node",
        "writer_node": "writer_node",
        "END": END
    }
)

# Add normal edges: from Researcher and Writer to END (simplified flow, no complex loops in this episode)
workflow.add_edge("researcher_node", END)
workflow.add_edge("writer_node", END)

# Compile the graph
app = workflow.compile()

# 7. Run the demo
print("\n--- 演示开始 ---")

# Scenario 1: Request that requires direct writing
print("\n=== 场景 1: 直接写作 ===")
inputs_1 = {"user_request": "请帮我写一篇关于 LangGraph Supervisor 模式的简介。", "messages": [HumanMessage(content="请帮我写一篇关于 LangGraph Supervisor 模式的简介。")]}
for s in app.stream(inputs_1):
    print(s)
    print("---")
print("\n=== 场景 1 结束 ===\n")

# Scenario 2: Request that requires research first
print("\n=== 场景 2: 需要研究 ===")
inputs_2 = {"user_request": "我需要关于 LangChain 最新版本更新的资料，然后写一份总结报告。", "messages": [HumanMessage(content="我需要关于 LangChain 最新版本更新的资料，然后写一份总结报告。")]}
for s in app.stream(inputs_2):
    print(s)
    print("---")
print("\n=== 场景 2 结束 ===\n")

# Scenario 3: Request explicitly indicating completion
print("\n=== 场景 3: 明确结束 ===")
inputs_3 = {"user_request": "谢谢，我已经拿到资料了，不需要其他内容了。", "messages": [HumanMessage(content="谢谢，我已经拿到资料了，不需要其他内容了。")]}
for s in app.stream(inputs_3):
    print(s)
    print("---")
print("\n=== 场景 3 结束 ===\n")

print("\n--- 演示结束 ---")

Code Walkthrough:

AgentState Definition: We define a TypedDict as the shared state for our LangGraph. It contains user_request (the original user request), supervisor_decision (the supervisor's decision, which is key for routing), research_output and writing_output (results from the respective agents), and messages (used to pass context between agents).
create_supervisor_agent(): This is the core of this episode. We build a ChatOpenAI instance and design an extremely detailed system_prompt for it. This Prompt explicitly tells the Supervisor its role (dispatcher), what it can do (decision routing), what it cannot do (actual work), and what format it should output ("researcher", "writer", or "FINISH"). llm.bind(stop=["\n"]) is a neat trick to ensure the LLM stops generating after the first newline character, helping to keep the output concise and properly formatted.
researcher_node and writer_node: For simplicity, these two agent nodes merely simulate their respective tasks here and return a string as the result. In a real project, they would integrate much more complex logic, such as calling external tools (search engines, databases, etc.) or leveraging more powerful LLMs to execute tasks.
route_supervisor_decision(): This is the routing function required by LangGraph's conditional edges. It receives the current AgentState, parses the supervisor_decision field, and returns the name of the next node (as a string). Note that we added strip().lower() to enhance robustness, along with a simple fallback mechanism just in case the Supervisor outputs something unexpected.
Graph Construction:
- We initialize the graph using StateGraph(AgentState).
- add_node() registers the Supervisor, Researcher, and Writer nodes.
  - The supervisor node is a lambda function that calls supervisor_agent to get the decision and updates the supervisor_decision field.
- set_entry_point("supervisor") explicitly states that the workflow starts at the Supervisor.
- add_conditional_edges() is the key here. It tells LangGraph: after exiting the supervisor node, call the route_supervisor_decision function to determine where to go next. The string returned by this function (e.g., "researcher_node") will match a key in the dictionary provided as the third argument to add_conditional_edges, thereby directing the flow to the corresponding node.
- add_edge("researcher_node", END) and add_edge("writer_node", END): In this episode, to highlight the Supervisor's routing capability, we have the Researcher and Writer end the workflow directly after completing their tasks. In more complex scenarios, they might return to the Supervisor for a secondary decision or proceed to other agents (like an Editor).
Demo Execution: We demonstrate the Supervisor Agent's effectiveness using three different user requests: one goes straight to the Writer, one goes to the Researcher first, and one ends directly. By observing the console output, you will clearly see the Supervisor's decisions and the flow of tasks.

Through this hands-on exercise, you have now mastered how to build a powerful Supervisor Agent in LangGraph to serve as the central dispatcher for your multi-agent system.

坑与避坑指南

As an experienced AI architect, I've seen countless pitfalls caused by taking things for granted. While the Supervisor pattern is powerful, it's not a silver bullet and requires careful refinement.

Prompt Engineering is King, but also an Abyss:
- Pitfall: Assuming that giving the LLM a rough instruction is enough for it to work perfectly. The Supervisor's output fails to meet expectations, leading to routing errors or system crashes.
- Best Practice: The Supervisor Agent's Prompt is the lifeline of this entire pattern. You must define its responsibilities, output format, and allowable output values with extreme precision and rigor. Providing clear positive and negative examples (few-shot prompting) in the Prompt is the ultimate way to improve stability. For instance, explicitly tell it to "output only one word, with no explanations."
- My Personal Experience: More often than not, a seemingly simple routing issue stems from the Supervisor LLM misunderstanding the user's intent or producing unformatted output. Spending extra time polishing the Prompt is far more efficient than debugging complex logic after the fact.
Balancing Decision Granularity and Agent Responsibilities:
- Pitfall: The Supervisor's decision granularity is too fine, forcing it to make too many micro-decisions, which increases its burden and the likelihood of errors. Alternatively, the granularity is too coarse, leaving the specific agents with ambiguous instructions.
- Best Practice: Ensure the Supervisor focuses on high-level routing decisions (i.e., "who does it"), rather than specific execution details (i.e., "how to do it"). The specific agents should have enough intelligence and tools to handle the complexities of their own domains. For example, if the Supervisor decides on "writing," the Writer Agent can have its own internal subgraph or tools to handle drafting, polishing, and formatting.
Exception Handling and Fallback Mechanisms:
- Pitfall: The Supervisor sometimes "acts dumb" and outputs content not on your expected list, causing the routing function to fail and the program to crash.
- Best Practice: Your routing function must include robust exception handling and a fallback mechanism. For instance, if the Supervisor's output is unrecognizable, you could default to an "Error Handling Agent," or route back to the Supervisor node with an error message attached so it can decide again. I provided a simple example of defaulting to the writer_node in the code, but in a production environment, you might need a more sophisticated strategy.
State Management and Information Passing:
- Pitfall: The Supervisor makes a decision, but the relevant information isn't properly passed to the next agent, rendering the agent unable to work effectively.
- Best Practice: Carefully design your AgentState to ensure all the information required by the agents is correctly stored and updated within the StateGraph. For example, user_request must persist from the very beginning, while research_output is only updated by the Researcher node but needs to be read by the Writer node. Clarify the read and write permissions for each node regarding the state.
Cost Considerations:
- Pitfall: Introducing a Supervisor adds an extra LLM call, which introduces additional latency and cost.
- Best Practice: Weigh the pros and cons. For simple, deterministic tasks, direct routing might be more efficient. But for complex, ambiguous tasks or those requiring dynamic decisions, the Supervisor's value far outweighs its cost. Choosing the right LLM model is also crucial; the Supervisor can use a more lightweight, faster-responding model since it only makes decisions and doesn't generate long-form content.

Remember, building a multi-agent system is like assembling a special forces unit. The Supervisor is your commander; it doesn't need to go to the front lines, but every single one of its commands is critical.

📝 Episode Summary

Congratulations, hardcore developers! In this episode, we successfully introduced the Supervisor Agent pattern into our "AI Content Agency."

We delved deep into the strategic significance of the Supervisor Agent: it's an intelligent dispatch center that doesn't do the grunt work but orchestrates the big picture and delegates tasks with precision. Through LangGraph's StateGraph and powerful conditional edges, we implemented a flexible workflow that allows the Supervisor to intelligently route tasks to specialized agents like the Researcher or Writer based on user requests.

The introduction of this pattern marks our AI content agency's transition from a simple "one-shot deal" to a smarter...

← PREVIOUS LESSON lesson-16

NEXT LESSON → lesson-18