LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 免費帳號 帳號

結論先說

  1. 想半小時搭出「中心主管 + 幾個專職代理」的原型,裝官方擴展包 langgraph-supervisor,調用 create_supervisor 即可自動生成調度邊。
  2. 上正式生產環境,更推薦用原生「隔離子圖(Subgraph)」寫法:把每個專家團隊編譯成擁有獨立私有 State 的子圖,父圖通過一個薄包裝函數調用它,只傳精簡指令、只拿回最終結論。
  3. 檢查點儲存器(Checkpointer)千萬別在父圖和子圖裏重複傳:只需在最外層父圖 parent.compile(checkpointer=...) 傳一次,LangGraph 會自動向下傳播持久化能力。
  4. 想看清嵌套子圖內部長什麼樣,導出流程圖時加上 xray=True 參數就能一鍵把黑盒展開。

Supervisor 預置包與原生子圖對比

圖:本站根據 LangGraph 官方 Multi-agent 與 Subgraphs 文檔 整理的示意圖

本文根據 LangChain / LangGraph 官方文檔《Multi-agent systems》《Subgraphs》與 langgraph-supervisor-py 官方倉庫整理,核對日期 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 LangChain 官方網站。

適用於誰

  • 搜「langgraph 多智能體」「langgraph supervisor 怎麼用」「langgraph subgraph 子圖」的開發者;
  • 已經寫順了單個 StateGraph(基礎見 /guides/langgraph-quickstart-install-first-graph),準備把臃腫的二十個工具拆給「檢索專家」「分析專家」等多個角色協同的工程師;
  • 把所有子代理全塞進同一個 MessagesState 後,發現前一個代理的幾十條查庫報錯把後一個代理徹底繞暈的人。

一、路線一:用 langgraph-supervisor 快速搭中心主管模式

如果你的業務正好是標準的「編排者-工作者」拓撲(原理見 /guides/multi-agent-orchestration-patterns),不想自己手寫主管的路由工具,可以直接安裝官方維護的預置包:

bash
pip install -U langgraph langgraph-supervisor langchain-openai

只需先把底下的專職工作者建好(記得給每個工作者起清晰的英文 name),再交給 create_supervisor 彙總編譯:

python
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langgraph_supervisor import create_supervisor

model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# 定義兩個職責分明的底層工作者
sql_worker = create_react_agent(
    model=model,
    tools=[],  # 此處掛載只讀數據庫查詢工具
    name="sql_expert",
    prompt="你只負責查詢訂單與庫存統計數字,如實返回數據結果。",
)

doc_worker = create_react_agent(
    model=model,
    tools=[],  # 此處掛載內部退換貨規則檢索工具
    name="policy_expert",
    prompt="你只負責核對公司售後條款細則,給出明確條款依據。",
)

# 組裝中心主管工作流
workflow = create_supervisor(
    [sql_worker, doc_worker],
    model=ChatOpenAI(model="gpt-4o", temperature=0),
    prompt="你是客服主管,先視需求調度 sql_expert 與 policy_expert 收集事實,最後統一作答。",
)

app = workflow.compile()

注意主管模式的一個調優參數:預設情況下如果把子代理內部的中間工具調用全攤進主對話流,Token 消耗會漲得很快(原因見 /guides/multi-agent-token-cost-why-high-how-to-control),建議檢查 output_mode 參數只向主管保留子代理的最後一條總結消息。

用隔離 Subgraph 搭建多智能體四步

圖:本站根據 LangGraph 官方 Subgraphs 文檔 整理的示意圖

二、路線二:用原生 Subgraph(子圖)實現徹底的上下文隔離

當某個專家角色內部本身就需要走三四個固定步驟(比如「生成 SQL → 校驗語法 → 跑查詢 → 脫敏彙總」),並且你希望它內部的 raw_rows、retry_count 等髒草稿絕不污染頂層父圖的共享帳本時,原生子圖是上限最高的寫法。

官方文檔給出了兩種掛載子圖的方式:

  • 共享鍵名直接掛載:父子 State 包含同名字段時,直接 parent.add_node("team_a", compiled_sub);
  • 包裝函數轉換狀態(強烈推薦):父子 State 完全獨立,在父圖節點函數里手動調用 compiled_sub.invoke(...),做好輸入輸出的「上下文防火牆」。

下面是一個完整的「私有狀態子圖」代碼骨架:

python
from typing import TypedDict
from langgraph.graph import StateGraph, START, END

# 1. 子圖擁有完全私有的內部狀態字段(父圖看不見 scratchpad)
class AuditSubState(TypedDict):
    target_text: str
    scratchpad: str
    verdict: str

def scan_risk_node(state: AuditSubState):
    # 模擬子團隊內部多步分析,中間草稿留在 scratchpad
    found = "含外部未核實連結" if "http" in state["target_text"] else "無異常"
    return {"scratchpad": f"內部掃描日誌: {found}", "verdict": found}

sub_builder = StateGraph(AuditSubState)
sub_builder.add_node("scan", scan_risk_node)
sub_builder.add_edge(START, "scan")
sub_builder.add_edge("scan", END)
# 注意:子圖直接無參 compile(),不要單獨傳 checkpointer
audit_subgraph = sub_builder.compile()

# 2. 頂層父圖狀態乾淨清爽,只存業務主幹數據
class MainState(TypedDict):
    draft_article: str
    audit_summary: str

# 3. 用包裝函數連接父圖與子圖,實現精確的輸入輸出裁剪
def call_audit_team(state: MainState):
    sub_out = audit_subgraph.invoke({
        "target_text": state["draft_article"],
        "scratchpad": "",
        "verdict": "",
    })
    # 只把精簡結論帶回父圖,丟棄子圖內部的冗長 scratchpad
    return {"audit_summary": sub_out["verdict"]}

parent_builder = StateGraph(MainState)
parent_builder.add_node("audit_team", call_audit_team)
parent_builder.add_edge(START, "audit_team")
parent_builder.add_edge("audit_team", END)

main_graph = parent_builder.compile()

三、子圖調試與持久化注意事項

  1. 展開查看嵌套連線:調用 main_graph.get_graph(xray=True).draw_mermaid() 時,如果子圖是直接掛入節點的,Mermaid 圖會把子圖內部拓撲一併展開(可視化與 Studio 調試方法見 /guides/langgraph-debug-visualize-studio-guide);
  2. 子圖內同樣支持 interrupt() 人工審批:只要頂層父圖編譯時掛載了 checkpointer,子圖深處觸發的斷點也能被外層正常捕獲並用同一個 thread_id 恢復;除非你明確需要某個子圖維護脫離父會話的獨立記憶,否則不要給子圖設 checkpointer=True。

平時研發階段藉助前沿大模型快速拆分父子狀態 Schema 與編寫單測用例時,個人官方訂閱參考資訊可見 /chongzhi/chatgpt-plus。

常見問題

Q:包裝函數里調子圖時,怎麼讓外層的流式輸出也能實時看到子圖內部的進度?

在父圖的 stream 或 astream 調用裏傳入 subgraphs=True 參數(例如 main_graph.stream(inputs, subgraphs=True)),流事件就會帶上命名空間前綴把子圖內部每一步的變化一併吐出來。

Q:一張父圖底下最多適合掛多少個子圖?

工程上單層主管直接調度的子代理或子圖建議控制在 3 到 6 個以內;如果業務模組超過十個,建議先在入口用確定性分類節點分流到對應二級主管,避免單個主管在十幾個相似角色描述之間搖擺選錯。

Q:兩個平級子圖之間可以直接用 Command(goto=...) 互相跳轉做交接嗎?

可以。新版 LangGraph 支持在子圖節點返回 Command(goto="另一個節點名", graph=Command.PARENT),不需要中心主管居中傳話就能把執行控制權直接移交給父圖裏的下一個平級專家節點,適合多階段順序或按需轉辦流程。

相關教學

參考資料

  • LangChain / LangGraph 官方文檔:Subgraphs & Multi-agent — https://docs.langchain.com/
  • langchain-ai/langgraph-supervisor-py 官方倉庫 — https://github.com/langchain-ai/langgraph-supervisor-py

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  4. 04

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  5. 05

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0
  6. 06

    MCP 收費嗎:開源協議免費邊界、第三方 API 帳單與隱形 Token 開銷說明

    搜「mcp 收費 嗎」的人常擔心裝多了插件會被扣費。MCP(模型上下文協議)本身和官方 SDK 採用 MIT 協議完全免費;實際使用中可能產生費用的只有兩處:掛載過多工具佔用的大模型上下文 Token,以及部分外部商業數據源自帶的 API 套餐。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    MCP 協議最新版本更新了什麼:無狀態架構、OAuth 2.1、結構化輸出與異步 Tasks 詳解

    搜「mcp 重大 更新」「mcp 協議 更新」想補齊規範演進脈絡?本文對照 modelcontextprotocol.io 官方規範更新日誌,梳理從 Streamable HTTP 到無狀態優先架構、OAuth 2.1 資源伺服器、Elicitation 交互補參與異步 Tasks 擴展的核心變化。

    Claude其他 AI 工具0
  2. 02

    A2A 和 MCP 有什麼區別:工具連接協議與智能體通信協議的邊界和配合

    很多人問「有了 MCP 為什麼還要出 A2A,兩者是不是二選一的競爭關係」。兩份官方規範都明確寫明它們是上下互補關係:MCP 負責給單個智能體掛載工具與數據源,A2A 負責讓多個獨立黑盒智能體跨團隊、跨框架互相派單協作。

    Claude其他 AI 工具0
  3. 03

    A2A 協議是什麼、怎麼用:Agent2Agent 智能體互聯規範、名片發現與 Python 接入流程

    A2A(Agent2Agent)是由 Google 發起並移交 Linux 基金會託管的開放智能體通信協議,用來讓不同團隊、不同框架開發的獨立智能體跨網絡互相派單協作。本文按官方規範講清 Agent Card、Task 狀態機與 Python SDK 接入步驟。

    Gemini其他 AI 工具0
  4. 04

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  5. 05

    CrewAI 多輪對話與記憶怎麼配:memory=True 三層記憶、人工介入與 Flows 狀態持久化

    剛用上 CrewAI 的人常疑惑 kickoff 跑完就結束,怎麼做多輪連續對話與跨次記憶。本文按官方文檔拆解 memory=True 的短期/長期/實體三層記憶、嵌入模型配置,以及用 Flows 狀態流和 @persist 搭建多輪會話的實戰寫法。

    其他 AI 工具0
  6. 06

    CrewAI 入門教學:Agent 角色、Task 任務、執行流程(Process)與第一個團隊示例

    CrewAI 是主打「擬人化角色分工」的 Python 多智能體開源框架。本文按官方文檔講清安裝要求、Agent(角色/目標/背景)、Task(任務描述與預期輸出)和 Process(順序接力與經理層級模式)的配合邏輯,並給出最小可運行代碼。

    其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~