https://github.com/langchain-ai/langgraph-swarm-py多智能体协作库一、这玩意是干啥的想象你有一个客服团队Alice 是数学专家Bob 是个说话像海盗的逗比。用户来了先跟 Bob 聊天然后问57 等于几Bob 不会算就说这事儿得找 Alice然后把用户转给 Alice。Alice 算完答案对话结束。这个库就是帮你实现智能体之间自动转接的。GitHublangchain-ai/langgraph-swarm-py二、三个核心概念1. Swarm蜂群— 一群智能体的管理者就像蜂群里的蜂王它知道现在谁在干活active_agent该把活儿派给谁路由逻辑怎么让智能体们互相交接handoff 机制为什么需要它如果没有这个管理者你每次跟 AI 对话它都不知道上次是谁在回答你每次都从头开始像个金鱼记忆。2. Handoff交接— 智能体之间的传话筒每个智能体手里有个转接电话的工具。比如 Bob 会说我有个 transfer_to_alice 按钮按一下就把用户转给 Alice。交接的时候做了三件事发一条消息已成功转接给 Alice让用户知道发生了什么告诉系统下一个找 Alice 干活更新 active_agent把之前的聊天记录打包带过去这样 Alice 知道前面聊了啥为什么需要它就像医院分诊你不能让一个心脏科医生去拔牙。每个智能体有自己擅长的活遇到不擅长的就转给对的人。3. Active Agent活跃智能体— 记住上次是谁系统里有个小本本记着现在该谁干活。新消息来了先看小本本找到那个人让他继续处理。为什么需要它保证对话的连续性。你问57 等于几系统知道上次是 Alice 在干活就直接找 Alice不会又去问 Bob你要不要算一下三、代码怎么组织的langgraph_swarm/ ├── swarm.py ← 蜂群管理者怎么组队、怎么调度 ├── handoff.py ← 交接工具怎么转接、转给谁 └── __init__.py ← 对外暴露的接口三个模块各司其职模块核心功能关键函数swarm.py多智能体编排引擎create_swarm()、add_active_agent_router()handoff.py智能体间交接机制create_handoff_tool()、get_handoff_destinations()__init__.py公共 API 导出暴露 4 个符号四、一个完整的例子# 1. 创建两个智能体 alice 创建智能体(模型, 工具[加法器, 转接给Bob], 角色我是数学专家) bob 创建智能体(模型, 工具[转接给Alice], 角色我是海盗) # 2. 组建成蜂群 swarm create_swarm([alice, bob], 默认启动Alice) # 3. 用户第一句话我想跟 Bob 说话 # → 系统启动 AliceAlice 看到用户想找 Bob按转接按钮 # → 系统切到 BobBob 开始用海盗口吻聊天 # 4. 用户第二句话57 等于几 # → 系统记得上次是 Bob直接找 Bob # → Bob 不会算按转接按钮找 Alice # → Alice 算出 12返回答案五、为什么这个设计好特性说明不用手动写调度代码你只需要告诉每个智能体你能转给谁库自动处理所有路由有记忆通过 checkpointer 保存对话关了重开还能继续聊可扩展想加第三个智能体一行代码create_swarm([alice, bob, charlie])⚙️可定制不满意默认的转接方式自己写个 handoff 工具想传什么数据都行六、频繁交接问题会不会转错Q1很多智能体互相转换要维护复杂的 handoff 工具吗不需要。库自动搞定。create_swarm在添加每个智能体时会调用get_handoff_destinations()自动扫描这个智能体身上有哪些 handoff 工具自动识别路由目标。关键机制在get_handoff_destinations钻进智能体内部的图结构找到 tools 节点里的所有工具检查每个工具的 metadata 里有没有__handoff_destination标记把标记里的目标名字全部收集起来Q2会不会交接给错误的智能体有可能但责任在 LLM不在库。交接的决策者是 LLM库只负责执行。库做的防护工具描述create_handoff_tool的description参数告诉 LLM 这个工具是干啥的system_prompt 引导可以给每个智能体写清楚角色定位没有强制路由库不会替 LLM 做决定怎么降低风险给每个 handoff 工具写清晰的 description描述越具体LLM 越不容易选错。七、为什么要路由到上次干活的 Agent核心代码就一句话def route_to_active_agent(state: dict) - str: return state.get(active_agent, default_active_agent)每次新消息进来先看 state 里记的active_agent是谁就找谁。这个设计的巧妙之处特点说明保证对话连续性没有记忆的话每次都要重新判断该找谁对话会断⚡避免反复路由的性能浪费有记忆 直接跳过去省一次 LLM 调用符合人类对话直觉你跟一个人聊天不会每句话都重新自我介绍和 handoff 工具形成闭环handoff 更新 active_agent路由读取 active_agent写和读分离️支持默认值降级第一次对话时 active_agent 是空的走 default_active_agent一句话总结这个设计把谁在处理当前对话这个状态从每次都重新计算变成了记住就行。就像你在餐厅点了菜服务员不需要每上一道菜都问这桌是谁的因为订单上写着桌号。active_agent 就是那个桌号。八、从交接看执行全过程基于测试用例场景还原Turn 1用户说我想跟 Bob 说话步骤动作①系统启动active_agent 为空 → 走默认值 Alice②路由到 AliceAlice 调用 transfer_to_bob 工具③handoff 执行goto → Bob 节点update → 把 active_agent 改成 Bob④Bob 收到消息 完整历史开始用海盗口吻回复结束active_agent BobTurn 2用户说57 等于几步骤动作①路由函数读 state.get(active_agent) → Bob②直接路由到 BobBob 调用 transfer_to_alice③handoff 执行active_agent 被改成 Alice④Alice 调用 add(5, 7)返回 12结束active_agent Alice三个关键问题的答案问题答案Alice 交接给 Bob 后当前活跃的是谁Bob。handoff 在第 91 行立刻把 active_agent 改成了 Bob下次对话进来路由到谁Bob。路由函数读的是state.get(active_agent)上次结束时的值是 BobBob 知道前面聊了啥吗全知道。所有历史消息都打包传给了 Bob关键洞察active_agent 不是谁在处理而是处理完之后的最后一个人是谁。就像接力赛最后一棒是谁active_agent 就记谁。下次发令枪响直接找最后一棒的人。消息是全量传递的不是只传当前智能体的消息。所有智能体共享一个 messages 列表所以 Bob 能看到 Alice 说过什么Alice 也能看到 Bob 说过什么。九、每个智能体都充当路由器角色关键机制handoff 工具就是一个普通的 toolcreate_handoff_tool创建的本质上就是一个普通的 LangChain Tool跟add(a, b)这种计算工具没区别。它被塞进智能体的 tools 列表里LLM 看到它自己决定要不要调用。完整流程拆解场景用户说帮我算 57步骤动作①路由到 Bobactive_agent Bob②Bob 的 LLM 看到工具列表中有 transfer_to_alice③LLM 决定调用 transfer_to_alice④系统跳到 Alice 节点⑤Alice 的 LLM 看到工具列表中有 add(a, b)⑥LLM 调用 add(5, 7) → 返回 12⑦LLM 生成回复结果是 12三个关键点路由判断 LLM 的工具选择— 不是库写了 if 规则而是 LLM 自己推理每个智能体只需要知道我能转给谁— 不需要知道对方的能力没有中心调度器— 系统是去中心化的每个智能体自己决定要不要转、转给谁每个智能体都需要充当判断路由的作用——这个判断不是代码逻辑是 LLM 的工具调用决策。库只负责发按钮 → 按按钮后跳转 → 记住最后谁在干活。十、消息归属问题不是模糊记录每条 AI 消息都有name字段明确标记是谁说的。messages列表不是所有消息混在一起而是每条都有角色归属messages [ {role: user, content: 我想跟 Bob 说话}, # 用户说的 AIMessage(nameAlice, tool_calls[transfer_to_bob]), # Alice 说的 ToolMessage(content已转接给 Bob), # 系统说的handoff 工具生成 AIMessage(nameBob, contentAhoy, matey! ...), # Bob 说的 {role: user, content: 57 等于几}, # 用户说的 AIMessage(nameBob, tool_calls[transfer_to_alice]), # Bob 转接的 ToolMessage(contentadd(5,7)12), # 系统说的add 工具结果 AIMessage(nameAlice, content结果是12), # Alice 回答的 ]附代码模块详解swarm.py — 多智能体编排引擎组件说明SwarmState继承自 MessagesState核心字段是 active_agent记录当前活跃的智能体create_swarm()工厂函数接收多个智能体列表自动构建 StateGraph。验证非空、自动转换类型、添加节点、推断路由add_active_agent_router()底层路由函数在 START 处添加条件边根据 active_agent 状态字段决定路由handoff.py — 智能体间交接机制组件说明create_handoff_tool()创建标准交接工具工具名自动生成内部生成 ToolMessage 返回 Command(goto...)get_handoff_destinations()从已编译的智能体图中提取所有 handoff 目标公共 API__init__.py暴露 4 个公共符号SwarmState、add_active_agent_router、create_handoff_tool、create_swarm
