langgraph-supervisor 包已不再积极维护。请改用 子代理 模式:主代理通过将子代理作为 工具 来调用,从而协调专门的工作代理。
本指南介绍如何从 create_supervisor 迁移到 create_agent,包括使用 interrupt 和外部 API 回调的设置。
变更摘要
基础迁移
使用langgraph-supervisor 时,工作代理是图节点,监督器使用交接工具在它们之间路由:
迁移中断和恢复流程
常见的langgraph-supervisor 设置在工作代理的工具内使用 interrupt,以暂停执行直到外部服务完成:
interrupt 通过工具包装的 create_agent 层向上传播到最外层的图。您的外部回调仍然可以使用 Command(resume=result) 恢复。
中断传播的要求
为了让interrupt 通过嵌套的 create_agent 层向上传播,请遵循以下规则:
- 仅使用检查点器编译最外层的图。 不要为子代理设置
checkpointer=...,这样它们使用 按次调用持久性,并在运行时继承父级的检查点器。 - 在
configurable中传递thread_id。 外层的invoke()或stream_events()调用必须包含thread_id,以便图可以保存检查点并恢复。
StateGraph 外层、中间的 create_agent 监督器以及内部的 create_agent 子代理都遵循相同的机制:
preview_tool 调用 interrupt 时,异常通过两个 create_agent 层向上传播,并作为 __interrupt__ 出现在外层 StateGraph 的调用结果中。您现有的 Command(resume=result) 回调路径仍然有效。
有关中断如何在子图中传播的更多信息,请参阅 子图持久性:中断 和 检查点和状态检查。
何时使用自定义 StateGraph 代替
当您需要将确定性步骤与代理步骤混合时,请使用自定义StateGraph。例如,固定路由、验证或外部 API 调用与 create_agent 节点并行。
迁移嵌套监督器
langgraph-supervisor 通过编译监督器并将其传递给另一个 create_supervisor 调用来支持多级层次结构。使用子代理模式,您有两个选择:
- 展平为单个监督器,每个叶子代理对应一个工具。当每个工作代理独立时,这是最简单的方法。
- 嵌套工具调用,当您需要中间协调时。将中间层代理(本身是一个带有自己子代理工具的
create_agent)包装为顶层监督器上的工具。
StateGraph。
迁移消息历史记录选项
create_supervisor 公开了 output_mode 以控制工作消息在对话历史中的显示方式:
full_history:包含来自工作代理的所有消息。last_message:仅包含工作代理的最终响应。
last_message 行为,仅返回最终消息;对于 full_history 行为,返回格式化后的完整对话摘要。有关将额外状态传回监督器的模式,请参阅 子代理输出。
另请参阅
- 子代理:模式概述和设计决策
- 使用子代理构建个人助理:分步监督器教程
- 使用子图:子图持久性、中断和状态检查
- 中断:暂停和恢复图执行
- LangGraph v1 迁移指南:从
create_react_agent迁移到create_agent
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

