langgraph-supervisor 包已不再积极维护。请改用 子代理 模式:主代理通过将子代理作为 工具 来调用,从而协调专门的工作代理。 本指南介绍如何从 create_supervisor 迁移到 create_agent,包括使用 interrupt 和外部 API 回调的设置。

变更摘要

基础迁移

使用 langgraph-supervisor 时,工作代理是图节点,监督器使用交接工具在它们之间路由:
通过将每个工作代理包装为主代理上的工具,迁移到子代理模式:
完整演练请参阅 使用子代理构建个人助理。

迁移中断和恢复流程

常见的 langgraph-supervisor 设置在工作代理的工具内使用 interrupt,以暂停执行直到外部服务完成:
使用子代理模式,相同的流程仍然有效。子代理工具内的 interrupt 通过工具包装的 create_agent 层向上传播到最外层的图。您的外部回调仍然可以使用 Command(resume=result) 恢复。

中断传播的要求

为了让 interrupt 通过嵌套的 create_agent 层向上传播,请遵循以下规则:
  1. 仅使用检查点器编译最外层的图。 不要为子代理设置 checkpointer=...,这样它们使用 按次调用持久性,并在运行时继承父级的检查点器。
  2. 在 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 调用来支持多级层次结构。使用子代理模式,您有两个选择:
  1. 展平为单个监督器,每个叶子代理对应一个工具。当每个工作代理独立时,这是最简单的方法。
  2. 嵌套工具调用,当您需要中间协调时。将中间层代理(本身是一个带有自己子代理工具的 create_agent)包装为顶层监督器上的工具。
如果您需要静态子图发现、按层级检查点命名空间或层级之间的共享状态键,请改用带有 子图节点 的自定义 StateGraph。

迁移消息历史记录选项

create_supervisor 公开了 output_mode 以控制工作消息在对话历史中的显示方式:
  • full_history:包含来自工作代理的所有消息。
  • last_message:仅包含工作代理的最终响应。
使用子代理模式,在工具包装器中控制此行为。对于 last_message 行为,仅返回最终消息;对于 full_history 行为,返回格式化后的完整对话摘要。有关将额外状态传回监督器的模式,请参阅 子代理输出。

另请参阅