很多同学第一次搭 Swarm 系统会这样设计用一个总 Agent 做调度接到需求就派发给对应子 Agent子 Agent 干完就把结果返回给总 Agent总 Agent 再决定下一步。结果上线后发现总 Agent 变成了瓶颈——每次都得经过它延迟高、token 消耗大Agent 之间的对话上下文丢了——子 Agent 不知道之前发生了什么用户多轮追问时频繁失忆——“我刚才说要订上海的酒店你怎么忘了”这些坑的根源都是没搞懂 Swarm 里的 handoff 到底在做什么。01 Swarm 的本质接力赛不是派单Swarm 的名字来自蜂群行为——没有中央控制每只蜂根据感知到的局部信息自主决策。映射到 Multi-Agent就是每个 Agent 自己决定任务完成了该交给谁继续。对比 Supervisor 模式维度Supervisor 模式Swarm 模式控制权位置中央 Supervisor当前活跃 Agent路由决策者Supervisor LLM当前 Agent 的 handoff 工具上下文传递通过 Supervisor 中转共享 State 直接传递适合场景任务需要全局视角协调任务可明确切割给专家token 消耗高每步都过 Supervisor低Agent 直接移交整个 Swarm 系统只有三个核心角色SwarmState共享状态active_agent字段就是接力棒谁持有谁执行Active Agent Router挂在 START 后读active_agent决定去哪个 Agent专家 Agent持有接力棒时执行任务干完通过 handoff 工具把棒传给下一个整个系统的数据流向START → Router → Agent A → (handoff) → Agent B → END。active_agent在整个过程里就是那根被传递的接力棒。02 handoff 机制用工具调用触发控制权转移Swarm 里的 handoff 不是什么神秘机制本质就是一个返回Command对象的工具。Command是 LangGraph 的特殊返回类型同时做两件事更新 State把active_agent改成目标 Agent 名 跳转到指定节点goto: hotel_agent。这两件事同步发生就是状态更新 控制权转移的原子操作。整个 handoff 链路LLM 判断该移交了 → 调用 handoff 工具 →Command触发状态更新和节点跳转 → 目标 Agent 接管带着完整对话历史继续干。用createHandoffTool创建 handoff 工具重点是description写成明确的触发条件importfromlangchain/langgraph/prebuiltimportfromlangchain/langgraph-swarmimportChatOpenAIfromlangchain/openaiconstnewChatOpenAImodelgpt-4o// description 要写触发条件 动作动词不能只写酒店相关constcreateHandoffToolagentNamehotel_agentdescription当用户需要查询、预订或取消酒店时立即调用此工具移交给酒店专家constcreateReactAgentllmtoolsnameflight_agentprompt你是航班预订专家。完成航班任务后如果用户还需要酒店移交给 hotel_agent。03 SwarmState为什么上下文不会丢Swarm 上下文不丢的秘密在于SwarmState。它在MessagesState基础上增加了active_agent字段Reducer 是直接替换不像messages是追加每次 handoff 就改这一个字段importAnnotationMessagesAnnotationfromlangchain/langgraphconstSwarmStateAnnotationRootMessagesAnnotationspecactive_agentAnnotationstringreducer(_, update) // 直接替换不累加default() 移交前{ messages: [完整对话历史], active_agent: flight_agent }移交后{ messages: [完整对话历史原封不动], active_agent: hotel_agent }Agent B 启动时拿到的是完整的对话历史——它知道用户要去上海知道已经订好了 CA1234不需要重新问一遍。Swarm 比 Supervisor 在上下文连贯性上更好就是因为没有中转损耗State 直接共享。04 完整实战旅行预订 Swarm 系统一个真实可运行的旅行预订 Swarm包含航班 Agent 和酒店 Agentimportfromlangchain/langgraph/prebuiltimportfromlangchain/langgraph-swarmimportMemorySaverfromlangchain/langgraphimportChatOpenAIfromlangchain/openaiimportfromlangchain/core/toolsimportfromzodconstnewChatOpenAImodelgpt-4o-mini// 业务工具consttoolasyncfromJSONstringifyidCA1234airline国航fromprice980idMU5678airline东航fromprice850namesearch_flightsdescription查询航班schemaobjectfromstringtostringdatestringconsttoolasyncJSONstringifyidH001name和平饭店price1200rating5idH002name全季酒店price450rating4namesearch_hotelsdescription查询酒店schemaobjectcitystringcheckInstringcheckOutstring// Agent 名称常量——用枚举不手写字符串坑2的修复方案constAGENTSFLIGHTflight_agentHOTELhotel_agentasconst// handoff 工具互相授权constcreateHandoffToolagentNameAGENTSHOTELdescription用户需要预订酒店时调用constcreateHandoffToolagentNameAGENTSFLIGHTdescription用户需要预订航班时调用// 创建专家 AgentconstcreateReactAgentllmtoolsnameAGENTSFLIGHTprompt你是航班预订专家。必须完成航班查询或预订后才能移交给其他 Agent。constcreateReactAgentllmtoolsnameAGENTSHOTELprompt你是酒店预订专家。必须完成酒店查询或推荐后才能移交给其他 Agent。// 组装 SwarmconstcreateSwarmagentsdefaultActiveAgentAGENTSFLIGHTcompilecheckpointernewMemorySaver// 运行——同一会话必须用同一 thread_idconstawaitinvokemessagesroleusercontent帮我订明天北京到上海的机票顺便订个外滩附近的酒店configurablethread_iduser-123-trip-booking// 固定 thread_id// 输出航班 CA1234 已查到外滩和平饭店推荐给您create_swarm内部自动完成了校验defaultActiveAgent在列表里把active_agent类型收窄为具体 Agent 名的LiteralIDE 能帮你检查拼写注册 Active Agent Router 到 START遍历 agents 调用getHandoffDestinations自动发现 handoff 目标并提前注册好所有跳转边。05 active_agent Router图的入口交通指挥Active Agent Router 是 Swarm 的心脏每次 Swarm 被调用都先经过它逻辑很简单读active_agent为空就去defaultActiveAgent否则去active_agent指向的节点。三种情况第一轮active_agent为空 → 去入口 Agent后续轮active_agent保存着上次的 Agent → 直接恢复handoff 后active_agent更新为目标 → 去新 Agent对用户的感知就是无论中间 handoff 了几次对话始终连贯。这比 Supervisor 的每步中转效率高得多也不会因为中转丢失上下文细节。06 自定义 handoff完全掌控图结构不想用create_swarm想完全控制图结构手写 handoff 工具核心是返回Command对象同时用ToolMessage关闭 tool_call这一步很容易漏掉importStateGraphMessagesAnnotationCommandAnnotationfromlangchain/langgraphimportToolMessagefromlangchain/core/messagesimportfromlangchain/core/toolsimportfromzodconstMyStateAnnotationRootMessagesAnnotationspecactive_agentAnnotationstringreducer(_, n) default() triage_agent// 工厂函数生成 handoff 工具functionmakeHandoffTooltargetAgent: string, description: stringreturntoolasyncnewCommandupdateactive_agent// ⚠️ 必须用 ToolMessage 关闭 tool_call否则消息链非法messagesnewToolMessagecontent移交给 ${targetAgent}tool_call_idtoolCallidgotonametransfer_to_${targetAgent}schemaobject// 手动构建图可插入审批节点、限制跳转关系、加 Human-in-the-LoopconstnewStateGraphMyStateaddNodetriage_agentaddNodebilling_agentaddNodetech_agentaddConditionalEdges__start__(s) active_agenttriage_agenttriage_agentbilling_agentbilling_agenttech_agenttech_agentconstcompilecheckpointernewMemorySaver手写 vscreate_swarm的选择简单场景用create_swarm省事需要审批拦截、限制 Agent 间跳转关系、复杂路由逻辑时选手写。07 常见坑5个让人崩溃的问题坑 1handoff 工具配了但 LLM 不调description太模糊LLM 判断不出该移交了。“酒店相关改成当用户需要查询、预订或取消酒店时立即调用此工具”——触发条件 动作动词缺一不可。坑 2defaultActiveAgent 拼错上线才报错createSwarm在运行时才校验不是编译期类型错误。用枚举常量管理 Agent 名见第04节AGENTS常量模式不在参数里手写字符串。坑 3多轮对话上下文丢失每次invoke传了不同的thread_idCheckpoint 匹配不上上下文全断。同一会话必须用同一个固定thread_id。坑 4Agent 之间循环 handoff两个 Agent 都没干完活就互相推死循环。Prompt 里明确必须完成本职任务后才能移交。配合recursionLimit做保底防止无限循环把 API 额度耗干{ configurable: { thread_id: SESSION_ID }, recursionLimit: 10 }坑 5手写 handoff 忘记关闭 tool_call移交后目标 Agent 报messages 格式非法。手写Command时ToolMessage里的tool_call_id必须填对应 LLM 发出的 tool_call 的 id——这是关闭 tool_call 的钥匙缺了消息链就断了。createHandoffTool自动处理手写必须自己保证见第06节代码注释。总结Swarm 的接力棒是active_agent字段谁持有它谁就在执行handoff 工具改变它来转移控制权。handoff 的本质是返回Command对象一次原子操作同时更新 State 和跳转节点不经过中间层。SwarmState的 messages 全程共享移交后目标 Agent 拿到完整历史上下文不断。create_swarm自动处理路由和边注册手写图可以获得完全控制权两者都可以用。最容易出问题的是 handoff description、thread_id 管理和手写 tool_call_id这三个细节认真写能省掉90%的调试时间。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】