多智能体编排从入门到生产：Multi-Agent Orchestrator 路由、存储与避坑完整指南
【免费下载链接】agent-squadFlexible and powerful framework for managing multiple AI agents and handling complex conversations项目地址: https://gitcode.com/GitHub_Trending/mu/agent-squad
一个 LLM 同时应对产品咨询、订单查询和售后投诉时经常力不从心，拆成多个专职智能体是常见思路——但请求该转给谁、上下文谁来记、多个智能体怎么协同，这些都得自己搭。Multi-Agent Orchestrator 就是一个多智能体编排框架，专门解决这三件事：它用分类器（相当于前台调度员，决定把问题转给哪个部门）把请求自动路由到最合适的智能体，按智能体维度维护对话历史，并同时在 Python 和 TypeScript 两种语言里提供同一套能力。做智能客服或多领域问答应用的开发者，基本都会用到它。
架构全景：一个请求从进到出的完整链路
先看全貌。你调用编排器后，请求走一条四步流水线：用户输入先给分类器，它拿着所有已注册智能体的描述加上该用户的全部会话历史，输出最匹配的智能体名字；编排器把请求派给这个智能体，智能体取走自己的历史后生成响应，可以是流式也可以是一次性返回；最后编排器把这一轮的提问和回答写回存储，再把结果交回调用方。
这里有个值得注意的设计：分类器持有全局对话视角，但每个智能体只拿到自己的历史——路由决策"全知"，处理层彼此隔离，既保证多轮归因准确，又避免上下文互相污染。框架内置了 12 个智能体（Bedrock LLM、Lex Bot、Lambda 函数、Chain、Supervisor 等，见 agents/），也有统一接口让你挂自定义智能体。
核心机制拆解：路由、历史与协同怎么跑
分类器路由原理：为什么追问归因最难
为什么要有它：多轮对话里全是"再说详细点""选第一个"这类短句，字面上没有任何线索指向具体智能体。内部怎么跑：分类器不是关键词匹配，它把用户问题、所有智能体的描述、本会话完整历史一起交给 LLM（内置 Bedrock、Anthropic、OpenAI 三种实现，见 classifiers/），由模型推断这句话该归谁——新问题按领域选，追问则看最后一轮是谁在应答。用错了会怎样：两个智能体描述职责重叠（比如都写了"订单与商品咨询"），模型判断会摇摆，表现为随机性误路由。上线前值得先量化检查各描述两两之间的重叠度，文档里有现成的基于 TF-IDF 余弦相似度的重叠分析工具。
对话历史隔离：分类器看全部，智能体只看自己
为什么要有它：路由依赖历史，但让每个智能体读全部对话会泄露其他领域的上下文、推高 token 开销。内部怎么跑：存储按 userId + sessionId 两个键组织成两层——分类器层持有全局视图，智能体层只取自己的记录，且每个智能体保留的历史对数有上限（quickstart 默认 10 对）。用错了会怎样：上限设太小，智能体记不住前文；设太大，成本和延迟同步上涨。内置的内存、DynamoDB、SQL 三种存储都实现了这套接口，可直接替换（见 storage/）。
SupervisorAgent 协同：agent-as-tools 模式
为什么要有它：一个任务本身需要多个智能体配合时（先调研、再并行起草、最后汇总），单层分类器表达不了这种时序。内部怎么跑：SupervisorAgent 用"智能体即工具"（agent-as-tools）的架构——一个主管智能体把队友作为"工具"调用，自主决定派给谁、谁可以并行、结果怎么整合，团队上下文由它统一管理。既可以单独调用它做专项协同，也可以把它作为一个成员挂进分类器，组成分层体系。用错了会怎样：把主管的职责域写得太宽，分类器第一层路由和主管内部路由会互相打架，出错时很难定位是哪一层判断错了。给主管的边界要窄而具体。
场景串联：电商客服系统如何组合这些模块
把上面的模块拼成一个真实项目，就是 examples/ecommerce-support-simulator/ 里的示例。用户从聊天或邮件两种入口进来，分类器结合历史判断路由：查订单状态、问发货时间这类常见请求，由产品或订单智能体调用知识库检索器（Retriever，相当于给 LLM 配的"查文档的图书管理员"）作答；遇到退款纠纷这类复杂问题，智能体把会话升级给人工客服，人工处理完还能在同一会话里由 AI 跟进收尾。🔍 整个链路用 DynamoDB 存历史，所以 Lambda 扩缩容、重启都不丢上下文——这是它和内存存储版 demo 最本质的差别。
排障与调优：大概率会踩的三个坑
坑一：追问"串门"。现象是用户在订单话题里说了句"继续"，回答却从别的智能体出来。根因通常是两个智能体描述太像，分类器分不出该归谁，或历史对数太小、分类器想不起上一轮是谁在说话。处理方式是重写描述、突出各自独有领域和典型例句，跑一遍重叠分析确认成对重叠度降下来，同时把历史对数调大。
坑二：重启后"失忆"。现象是本地复现不了、上生产就丢前几轮上下文，九成是用了内存存储，进程一重启历史就没了。处理方式是切到 DynamoDB 或 SQL 存储，本地排查时固定 sessionId 重放会话。
坑三：分类器"选不出人"。现象是报错说没有匹配到任何智能体，根因是问题落在所有已注册领域之外。处理方式是打开 USE_DEFAULT_AGENT_IF_NONE_IDENTIFIED 配置并指定一个兜底默认智能体；如果怀疑是模型输出解析偶发异常，再把 MAX_RETRIES 调高观察。
收尾行动
一句话总结：Multi-Agent Orchestrator 把多智能体系统最麻烦的路由、上下文隔离和历史持久化做成了开箱即用的组件，你的精力可以全放在智能体本身的业务能力上。下一步建议直接克隆仓库，跑 examples/local-demo/ 里的本地 demo 看两个智能体之间怎么切换，再照着 docs/ 的 quickstart 注册你自己的前两个智能体——跑通后先做一次智能体重叠分析，它会替你省掉后面大量的误路由排查时间。🚀
【免费下载链接】agent-squadFlexible and powerful framework for managing multiple AI agents and handling complex conversations项目地址: https://gitcode.com/GitHub_Trending/mu/agent-squad
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
