|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 给一个 Agent 挂 20 个工具，它反而开始犯迷糊------这不是模型不够聪明，是你让它一个人干了整个团队的活。本文拆透 Multi-Agent 多智能体 的核心机制：Handoff 交接 ，以及 Supervisor 主管 与 Swarm 蜂群两大架构，最后用 LangGraph 手把手搭一个能跑起来的旅行规划多智能体，代码完整可复制。 |
01 一个 Agent，快要被工具"淹死"了
先讲个真实的坑。
你给一个 AI Agent 挂了 20 个工具：查订单、改地址、退款、发邮件、算运费......想着"一个 Agent 全搞定，多省事"。
结果它开始犯迷糊：用户明明问的是"退款"，它却去查了订单；你把提示词写得更详细，它反而更不听话。
这不是模型不够聪明。是你让它一个人干了整个团队的活。
现实世界里，公司不会招一个"既做法务又做财务还兼前台"的员工。AI 也一样------这，就是 **Multi-Agent（多智能体）**在 2026 年全面爆发的根本原因。
今天这篇文章，我们把多智能体的核心架构讲透，再用 LangGraph 手把手搭一个能跑起来的多智能体系统。全程代码完整，装上就能跑。
02 为什么单个 Agent 会"撑不住"
把三个原因摊开看，你对多智能体的理解就完成一半了。
|--------------------------------------------------------------------|
| ① 工具选择困难症 工具越多，模型选错的概率越高。20 个工具摆在面前，"退款"和"查订单"的语义又很接近，选错几乎是必然。 |
|-------------------------------------------------------------------------------------------|
| ② 上下文被污染 每个工具的说明、每次调用的返回结果，都会塞进同一个上下文窗口。查订单的冗长数据留在里面，紧接着做退款决策时，它就成了噪音。上下文越脏，判断越差。 |
|---------------------------------------------------------------------|
| ③ 提示词精神分裂 "你要热情耐心地安抚用户"和"你要严格按财务规则拒绝退款"，这两条写进同一个系统提示词，模型只能精神分裂。 |
打个比方：单 Agent 像一个全科医生，什么病都看；Multi-Agent 像一家专科医院，分诊台判断你该去哪个科室，各科医生只干自己最擅长的事。
03 核心机制：Handoff（交接）
多智能体要解决的关键问题只有一个：Agent 之间怎么把活交出去？
LangGraph 的答案是 Handoff（交接）。一个 Handoff 只需要描述清楚两件事：
|--------------------------------------------------------------|
| destination（交给谁）：目标 Agent 是谁 payload（带什么）：把哪些信息一起递过去 |
就这么简单。比如订机票 Agent 发现用户还要订酒店，它不需要自己去查酒店------直接 Handoff 给酒店 Agent，把"城市、日期、预算"打包递过去就行。
理解了交接，两大主流架构就是它的两种排列方式。
04 两大核心架构：Supervisor 与 Swarm
架构一：Supervisor（主管模式）
一个中心化的主管 Agent，所有任务由它分派，所有结果汇总到它这里。
就像项目经理：他不写代码，只负责"谁该干哪件事"。
|-------------------------------|
| 适合场景：职责边界清晰、需要统一决策和审计的场景。 |
架构二：Swarm（蜂群模式）
没有主管。每个 Agent 手里都有"转交工具"，谁发现自己搞不定，就直接把控制权交给下一位。
就像同事之间互相转接电话------"这事不归我管，我帮你转给张三"。
|-------------------------------|
| 适合场景：流程动态、难以预先画出完整路由图的场景。 |
两者怎么选？
|--------|-----------------|-------------|
| 对比维度 | Supervisor 主管模式 | Swarm 蜂群模式 |
| 控制方式 | 中心化，主管统筹 | 去中心化，互相转交 |
| 可预测性 | 高，路径清晰 | 较低，动态灵活 |
| 调试难度 | 低，有统一审计轨迹 | 较高，链路分散 |
| LLM 调用 | 多（每次都要问主管） | 少（直接交接，省延迟） |
| 典型场景 | 客服工单分派、报告生成 | 多轮对话转接、专家接力 |
一句话记忆：要可控选 Supervisor，要灵活选 Swarm。
实际生产中，最常见的做法是混合------团队内部用 Swarm，团队之间用 Supervisor 串起来。
05 实战：搭一个"旅行规划多智能体"
我们做一个旅行助手，它要同时搞定三件事：订机票、订酒店、查天气。
如果塞进一个 Agent，它得同时管三套工具。现在我们把它们拆成三个专家 Agent，再用主管统一调度。
第一步，安装依赖（Python 3.10 以上）：
pip install -U langgraph langgraph-supervisor langchain-openai第二步，定义三个"干活"的工具函数：
def book_flight(from_airport: str, to_airport: str) -> str: """预订机票""" return f"已成功预订 {from_airport} 飞往 {to_airport} 的航班。"def book_hotel(hotel_name: str) -> str: """预订酒店""" return f"已成功预订 {hotel_name}。"def get_weather(city: str) -> str: """查询城市天气""" return f"{city} 未来三天晴，气温 18-26 度。"注意每个函数上那行 """...""" 文档字符串。它不是写给人看的，是写给模型看的------模型靠它判断该在什么时候调用这个工具。写不清楚，模型就选错。
第三步，把每个工具"包装"成独立的 Agent：
from langgraph.prebuilt import create_react_agentflight_agent = create_react_agent( model="openai:gpt-4o", tools=[book_flight], prompt="你是机票预订助手，只负责机票相关事务。", name="flight_agent", # 名字必须显式指定)hotel_agent = create_react_agent( model="openai:gpt-4o", tools=[book_hotel], prompt="你是酒店预订助手，只负责酒店相关事务。", name="hotel_agent",)weather_agent = create_react_agent( model="openai:gpt-4o", tools=[get_weather], prompt="你是天气查询助手，只负责天气查询。", name="weather_agent",)这里的 name 参数是关键。主管要靠这个名字来决定"把活派给谁"，不写名字，多智能体就散了架。
第四步，创建主管并把系统编译成图：
from langchain_openai import ChatOpenAIfrom langgraph_supervisor import create_supervisorsupervisor = create_supervisor( agents=[flight_agent, hotel_agent, weather_agent], model=ChatOpenAI(model="gpt-4o"), prompt=( "你是旅行规划主管。根据用户需求，把任务分派给" "机票、酒店、天气三个助手，最后由你汇总成一份完整方案。" ),).compile()第五步，跑起来：
for chunk in supervisor.stream({ "messages": [{ "role": "user", "content": "帮我订一张北京到上海的机票，再订外滩附近的酒店，顺便看看天气", }]}): print(chunk) print("\n")运行后你会看到一条清晰的执行链：主管先读懂需求 → 派给 flight_agent → 收到结果 → 再派给 hotel_agent → 再派 weather_agent → 最后由主管汇总成一份完整答复。
**整个过程你只写了一个 create_supervisor。**路由逻辑、消息传递、结果汇总，框架全包了。
|-----------------------------------------------------------------|
| 小提示 ：model 不绑定特定厂商。把 "openai:gpt-4o" 换成你熟悉的模型即可，接口完全一致。 |
06 换个姿势：Swarm 版本
拿刚才的机票和酒店两个助手，改成蜂群模式，代码只换签名和最后一段。
第一步，给每个 Agent 装上"转交工具"：
from langgraph_swarm import create_swarm, create_handoff_tool# 定义转交通道to_hotel = create_handoff_tool( agent_name="hotel_agent", description="把用户转交给酒店助手",)to_flight = create_handoff_tool( agent_name="flight_agent", description="把用户转交给机票助手",)flight_agent = create_react_agent( model="openai:gpt-4o", tools=[book_flight, to_hotel], # 多了转交工具 prompt="你是机票预订助手。用户还提到酒店时，转交给酒店助手。", name="flight_agent",)hotel_agent = create_react_agent( model="openai:gpt-4o", tools=[book_hotel, to_flight], prompt="你是酒店预订助手。用户还提到机票时，转交给机票助手。", name="hotel_agent",)第二步，创建蜂群并编译：
swarm = create_swarm( agents=[flight_agent, hotel_agent], default_active_agent="flight_agent", # 谁是"第一接待").compile()对比一下就很清楚了：
|---------------------------------------------------|
| Supervisor ：每个 Agent 必须干完活回到主管汇报，主管再派下一个。 |
|------------------------------------------------------|
| Swarm ：机票 Agent 发现要订酒店，直接把用户"转接"过去，中间没有主管插话。 |
少了一层往返，延迟更低，但代价是路径不再可预测。这就是灵活性和可控性的经典权衡。
07 生产落地，还得注意这 3 件事
Demo 跑通只是起点。真要上生产，这三件事绕不开。
|-------------------------------------------------------------------------------------------------------------------------------------------|
| ① State（状态）怎么设计 所有 Agent 共享一份 State，默认用 messages 累加。但多个 Agent 同时写同一份状态时会冲突，需要用 reducer 明确"合并规则"。比如让每个 Agent 的结果各自追加到列表，而不是互相覆盖。 |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ② 一定要加 Checkpoint（持久化） LangGraph 支持把每一步状态存进数据库（如 SQLite、Postgres）。这一步带来的能力是质变的： · 进程崩了，能从断点恢复 · 危险操作前暂停，等人工确认再继续 · 结合 interrupt 实现人工介入（HITL） 涉及下单、付款、发邮件这类不可逆操作，HITL 不是可选项，是必需品。 |
|--------------------------------------------------------------------------------------------------------|
| ③ 可观测性决定你能不能睡着觉 多智能体比单 Agent 更容易出问题，因为链路长、参与者多。建议配合 LangSmith 做全链路追踪，把每一次 Handoff、每一次工具调用都记下来。 |
生产上最常见的两个坑：Agent 之间互相转交形成死循环 ，以及 Token 消耗失控。都需要用重试计数和调用上限来兜底。
✓ 总结
回到最开始那个问题：为什么单个 Agent 会撑不住？
因为它被要求同时做太多事------工具太多选不准，上下文太脏判断差，提示词太杂会精神分裂。
Multi-Agent 的本质，是承认"分工"这件事在 AI 世界里同样成立。
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Handoff 是机制------交给谁，带什么。 Supervisor 是集中调度------可控、好调试，但慢一点。 Swarm 是去中心转交------灵活、延迟低，但路径难预测。 而 LangGraph 的价值在于：它把上面这些复杂的编排，压缩成了 create_supervisor 和 create_swarm 两行调用。 一句话决策：要可控选 Supervisor，要灵活选 Swarm，真实项目里两者混着用。 |
从"写一个更长的提示词"，到"把问题拆给一个团队"------这是 2026 年做 AI 应用，最值得完成的一次思维转变。