AgentScope多智能体开发框架教程

AgentScope 多智能体开发框架教程

一套教程的价值，不在于它覆盖了多少术语，而在于你合上它时，能不能亲手把几个智能体连起来跑通一段真实任务。这篇导读先把这个目标摆清楚，再告诉你后面 23 篇是怎么为你铺路的。

你有没有遇到过这种处境：单个大模型已经能满足问答，但如果要让"调研、写稿、审校"三件事串起来自动跑，光靠 prompt 就很难管住中间状态——谁该在什么时候说话、上一轮的结论怎么传给下一轮、某个环节出错怎么兜底，全都成了散落各处的胶水代码。我写这套教程的出发点很直接：多智能体不是把多个聊天框摆在一起，而是一套有消息路由、有环境约束、有容错兜底的运行系统。AgentScope 是少数把这件事做得既有工程边界、又对开发者透明的开源框架，我们就在它上面把这台机器拆开重装一遍。

这套教程在讲什么

AgentScope 由模型厂商开源，核心思路是"以消息为中心的异步协作"。一个智能体（Agent）对外只暴露一件事：收到一条消息，返回一条消息。它内部怎么调模型、怎么查工具、怎么记上下文，都被收进自己的边界里。多个智能体之间不直接耦合，而是通过消息中枢（MsgHub）或环境（Environment）来交换信息。这样的设计让"加一个智能体""换一种协作模式"变成改配置而不是重写系统。

我们沿一条主线推进：搭一个能跑的多智能体系统。从认识框架、读懂架构，到写代码、做编排、上生产，最后看生态和取舍。整条线不是平铺的知识点，而是层层依赖——你不先理解消息模型，就写不好工具；不先理解环境，就做不出有状态的协作；不先理解容错，就只能停留在 demo 阶段。

全册知识地图

下图把四章的依赖关系和主线串起来，你随时可以回来对照自己走到了哪一步。

阅读路线建议

• 如果你在犹豫"我的项目到底要不要上多智能体"，先读第一章，它会用对照的方式帮你判断，而不是劝你用。
• 如果你已经决定动手，第二章是地基。消息模型、环境、记忆这三块理解不透，后面写代码会反复踩坑。
• 第三章是本教程的重心，几乎每节都带可运行代码。建议边读边敲，尤其是 3.4 任务编排那一节，msghub 和 GroupChat 的用法是分水岭。
• 第四章偏方法论和视野，适合在你已经跑通一个小系统之后回头看，会更有体感。

我们对代码示例的处理

教程里的代码以 AgentScope 2.0 主线 API 为主（ReActAgent、DialogAgent、MsgHub、Toolkit、InMemoryMemory、OpenAIChatModel/DashScopeChatModel 等）。考虑到不少存量项目仍沿用 1.x 风格（继承 AgentBase、用 @tool 装饰器），涉及工具定义和自定义智能体的章节会同时给出两种写法并标注差异，你会清楚哪段该在新项目里用、哪段只是兼容老代码。

所有模型调用都需要你自己的 API Key，文中统一用环境变量占位，不写死任何密钥。运行输出是我们基于真实 API 行为描述的典型结果，你的实际返回会因模型而异，但结构和字段一致。

一个先说清楚的前提

多智能体系统不是银弹。当任务能被一个提示词加少量工具解决时，上多智能体只会徒增延迟和调试成本。我们会在第一章就划出边界，在第四章总结反模式。把"该不该用"想清楚，比"怎么用"更重要——这是这套教程和一般框架文档最大的不同：我们不止教你怎么拼，还教你怎么判断什么时候不拼。

接下来，第一章我们先把"多智能体"这件事本身掰开：它解决了什么单智能体解决不了的麻烦，又带来了什么新麻烦。