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 条评论

登录 后参与评论

还没有评论,来抢沙发~