AgentScope多智能体框架实战：从核心原理到多角色协作研究助手

1. 为什么我会盯上 AgentScope 这个多智能体框架

第一次听到 AgentScope 这个名字，是在一个做智能客服系统的朋友那里。他当时吐槽说，用传统方式编排多个 AI 角色协作，代码写得像蜘蛛网，一个角色改个提示词，整条链路都得跟着调。后来他换了 AgentScope，两周时间把原来一个月的活干完了。我当时的第一反应是：又一个包装过度的框架吧？但真正上手跑了一个多智能体协作的 Demo 之后，我改观了。

AgentScope 是阿里巴巴开源的一个多智能体（Multi-Agent）应用开发框架，核心解决的事情就一件：让多个 AI 智能体像一支团队一样协作，而不是各说各话。它把智能体的定义、消息传递、工作流编排、工具调用、记忆管理这些脏活累活都封装好了，你只需要关注"我要让哪些角色、按什么规则、完成什么任务"。适合谁用？如果你正在做智能客服、自动化研究助手、多角色内容生成、复杂任务拆解这类需要"多个 AI 配合"的场景，或者你单纯想搞明白多智能体到底怎么落地，那这个框架值得花时间研究。

我写这篇东西的出发点很简单：网上关于 AgentScope 的中文资料要么太官方、要么太碎片，真正从"我要动手做一个东西"角度出发的实操记录不多。所以我把这段时间踩过的坑、验证过的方案、以及一些官方文档里不会明说的细节，整理成一篇能直接抄作业的实战笔记。不管你是刚接触多智能体的小白，还是已经用过其他框架想对比的老手，应该都能从里面捞到点有用的东西。

2. AgentScope 到底解决了什么问题：核心设计思路拆解

2.1 多智能体开发的三个老大难

在 AgentScope 出现之前，想搞多智能体协作，基本绕不开三个坑。

第一个坑是通信机制自己造。多个智能体之间要传消息，你得自己设计消息格式、自己写分发逻辑、自己处理消息顺序。稍微复杂一点，比如 A 等 B 的回复、B 又要参考 C 的输出，代码里全是回调嵌套，调试的时候根本不知道消息走到哪一步了。

第二个坑是角色行为难复用。每个智能体本质上就是"一段提示词 + 一套工具 + 一个记忆"，但很多框架把这些东西耦合在一起，你想把一个"研究员"角色从项目 A 搬到项目 B，得把代码拆得七零八落。

第三个坑是工作流编排靠硬编码。串行、并行、条件分支、循环，这些在业务里太常见了，但很多框架只给你最基础的对话接口，编排逻辑全靠 if-else 堆，改一个流程等于重写一遍。

AgentScope 的设计思路，就是把这三点分别抽象成独立的模块：消息层、智能体层、工作流层。消息层负责"怎么传"，智能体层负责"是谁、会什么"，工作流层负责"按什么顺序干"。三层解耦之后，你改任何一层都不影响其他层，这是它跟很多"一体化"框架最大的区别。

2.2 消息传递：为什么用消息驱动而不是函数调用

AgentScope 最核心的一个设计决策，是用消息驱动（Message-Driven）而不是函数调用（Function Call）来组织智能体协作。

这两者的区别，打个比方：函数调用就像你打电话给同事，必须等对方接、等对方说完、你才能说下一句，中间对方在忙你就得干等；消息驱动就像发微信，你把消息丢进群里，谁该处理谁处理，处理完了再往群里丢结果，你不需要阻塞等待。

具体到实现上，AgentScope 里每个智能体都有一个reply方法，接收一条消息，返回一条消息。智能体之间不直接互相调用，而是通过一个统一的消息枢纽来转发。这样做的好处有三个：

• 解耦：A 不需要知道 B 的存在，只需要知道"我把消息发给枢纽，枢纽会转给该处理的人"。
• 可观测：所有消息都经过枢纽，你想加日志、加监控、加拦截，在一个地方改就行。
• 可扩展：想加一个新角色，注册进去就行，不用改现有角色的代码。

我实测下来，这个设计在角色数量超过 3 个之后优势特别明显。之前用函数调用方式写过一个 5 角色的协作流程，光理清调用关系就花了大半天；换成消息驱动之后，每个角色的逻辑是独立的，加角色就是加一个文件。

2.3 工作流编排：把"流程"和"角色"分开

AgentScope 的工作流编排，我理解下来核心就一句话：流程是流程，角色是角色，两者通过消息接口对接。

它提供了几种典型的编排模式：

这里有个经验：不要一上来就用最复杂的编排模式。我见过不少人，明明一个顺序执行就能搞定的事，非要用群组对话，结果调试成本翻了好几倍。编排模式的选择标准很简单——看任务本身有没有"并行"或"反复"的需求，没有就用最简单的。

3. 核心模块逐个拆：从智能体定义到工具调用

3.1 智能体定义：一个角色由哪几部分组成

在 AgentScope 里定义一个智能体，本质上是在回答四个问题：

1. 它是谁：名字、角色描述、系统提示词。
2. 它会什么：可以调用的工具列表。
3. 它记得什么：记忆模块，决定它能记住多少轮对话、要不要做长期记忆。
4. 它怎么说话：用哪个大模型、温度设多少、要不要流式输出。

这四部分里，最容易出问题的是系统提示词和记忆配置。

系统提示词不是越长越好。我踩过的坑是：一开始把角色描述写得特别详细，恨不得把这个人设的前世今生都写进去，结果模型反而抓不住重点，回复变得又臭又长。后来改成"一句话定位 + 三条行为准则 + 两个输出示例"，效果明显好了。核心原则是：提示词要约束行为，而不是描述背景。

记忆配置这块，AgentScope 默认是保留全部对话历史。这在短对话里没问题，但一旦对话轮次多了，token 消耗会爆炸式增长。我的做法是：给每个智能体设一个记忆窗口，比如只保留最近 10 轮，超出的部分做摘要压缩。摘要压缩的逻辑可以自己写，也可以让模型来总结，后者效果更好但多一次调用。

3.2 工具调用：让智能体真正"能干活"

光会聊天的智能体价值有限，能调用工具才是关键。AgentScope 的工具调用机制，我总结下来是"注册 - 描述 - 调用"三步。

注册就是把你的函数挂到智能体上。这里有个细节：函数的参数类型和返回值类型一定要写清楚，因为框架要靠这些信息生成给模型看的工具描述。我试过用没有类型标注的函数，结果模型经常传错参数，加上类型标注之后就稳了。

描述是给模型看的"说明书"。工具描述写得好不好，直接决定模型会不会用、用得对不对。我的经验是：描述里要包含"什么时候用"和"什么时候不用"。比如一个搜索工具，描述里除了写"用于搜索信息"，还要写"当问题涉及实时数据时使用，当问题涉及常识时不要使用"。这样能减少很多无效调用。

调用环节要注意异常处理。工具执行失败是常态，网络超时、参数错误、返回格式不对，都可能发生。AgentScope 允许你给工具调用设重试次数和超时时间，我的建议是：重试次数设 2-3 次，超时时间根据工具类型设，搜索类 10 秒，计算类 3 秒。超过这个范围还没结果，基本就是有问题了，重试也是浪费时间。

3.3 记忆管理：短期记忆和长期记忆怎么配合

记忆这块我想单独拎出来说，因为它是最容易被忽视、但影响最大的模块。

AgentScope 的记忆分两层：短期记忆是当前对话的上下文，长期记忆是跨对话的知识沉淀。

短期记忆的管理，核心是"窗口 + 压缩"。窗口决定保留多少轮原始对话，压缩决定超出的部分怎么处理。我的配置是：窗口 10 轮，压缩用模型摘要。实测下来，10 轮是个比较平衡的值——太少会丢失上下文，太多会拖慢响应。

长期记忆的管理，核心是"存什么"和"怎么取"。存的时候，我一般只存三类信息：用户偏好、关键事实、历史决策。取的时候，用向量检索找最相关的几条，而不是全量塞进上下文。这里有个坑：长期记忆的检索质量，取决于你存的时候有没有做好结构化。如果存进去的是一大段自然语言，检索出来的往往不精准；如果存的时候拆成"事实 + 标签"，检索效果会好很多。

4. 动手实操：搭一个多角色协作的研究助手

4.1 场景定义与角色划分

光讲理论没意思，我拿一个实际做过的项目来演示：一个多角色协作的研究助手，输入一个研究主题，输出一份结构化的研究报告。

这个场景需要三个角色：

• 规划者（Planner）：把研究主题拆成若干子问题。
• 研究员（Researcher）：针对每个子问题搜集信息、整理要点。
• 撰写者（Writer）：把研究员的输出整合成一份报告。

为什么是这三个角色而不是两个或四个？因为"拆解 - 执行 - 整合"是研究类任务的最小闭环。规划者负责"想清楚要研究什么"，研究员负责"把每个点搞清楚"，撰写者负责"把搞清楚的东西说明白"。三个角色职责清晰，没有重叠，也没有遗漏。

4.2 环境准备与依赖安装

环境这块，Python 版本建议 3.9 以上，我用的 3.10。依赖安装分两步：

pip install agentscope pip install openai

AgentScope 本身不绑定特定的大模型，你可以接 OpenAI 兼容的接口，也可以接其他模型服务。我这边用的是 OpenAI 兼容接口，配置方式是在代码里设好 base_url 和 api_key。

注意：api_key 不要硬编码在代码里，用环境变量或者配置文件。我见过太多人把 key 提交到代码仓库，然后被刷爆的案例。

4.3 三个角色的具体实现

先定义规划者。它的核心任务是接收研究主题，输出子问题列表。提示词我这样写：

planner_prompt = """你是一个研究规划专家。 你的任务是把用户给出的研究主题拆解成 3-5 个具体的子问题。 要求： 1. 子问题之间要有逻辑递进关系 2. 每个子问题要具体到可以直接研究 3. 输出格式为编号列表，每条不超过 30 字 """

这里的关键是输出格式约束。如果不约束格式，模型可能给你一段散文，后面解析起来很麻烦。约束成编号列表之后，解析逻辑就很简单了。

再定义研究员。它的任务是接收一个子问题，输出研究要点。提示词：

researcher_prompt = """你是一个严谨的研究员。 针对给定的子问题，输出 3-5 条关键要点。 要求： 1. 每条要点要有具体信息，不要空泛 2. 如果涉及数据，要标注来源 3. 输出格式为编号列表 """

研究员这个角色，我建议给它配一个搜索工具。没有搜索工具的研究员，本质上是在"回忆"而不是"研究"，输出质量会差很多。

最后定义撰写者。它的任务是接收所有研究要点，整合成报告。提示词：

writer_prompt = """你是一个专业的报告撰写者。 根据给定的研究要点，撰写一份结构化的研究报告。 要求： 1. 报告包含引言、主体、结论三部分 2. 主体部分按子问题组织 3. 语言简洁专业，避免口语化 """

4.4 工作流编排与消息流转

三个角色定义好了，接下来是编排。这个场景是典型的顺序 + 循环结构：

1. 规划者接收主题，输出子问题列表。
2. 对每个子问题，研究员依次处理，输出要点。
3. 所有要点汇总后，交给撰写者输出报告。

用 AgentScope 的编排接口，大概是这样：

# 第一步：规划 sub_questions = planner.reply(topic) # 第二步：逐个研究 research_results = [] for question in sub_questions: result = researcher.reply(question) research_results.append(result) # 第三步：整合撰写 report = writer.reply(research_results)

看起来简单，但实际跑的时候有几个细节要注意：

• 子问题列表的解析：规划者输出的是文本，要解析成列表。我用的方法是按行分割，去掉编号前缀。如果模型输出格式不稳定，可以加一层正则匹配。
• 研究员的上下文隔离：每个子问题应该独立处理，不要让研究员看到之前子问题的结果，否则会串味。AgentScope 里可以通过重置记忆来实现。
• 撰写者的输入长度：如果子问题很多，研究要点会很长，可能超出模型上下文。我的做法是先把要点做一次压缩，再交给撰写者。

4.5 参数选择与性能调优

跑通之后，下一步是调优。我调的主要是三个参数：

温度（temperature）：规划者和撰写者用 0.7，研究员用 0.3。为什么不一样？规划需要一点发散性，太死板拆不出好问题；研究需要严谨，温度高了容易编造；撰写需要流畅，0.7 是个平衡点。

最大 token 数：规划者 500，研究员 800，撰写者 2000。这个根据输出长度预估，留 20% 余量就行。设太大浪费，设太小会被截断。

重试次数：统一设 2 次。实测下来，第一次失败往往是网络问题，第二次基本能成；如果两次都失败，说明是逻辑问题，重试也没用。

调优之后，整个流程的耗时从最初的 90 秒降到了 45 秒左右，输出质量也稳定了很多。

5. 踩坑实录：那些文档里不会写的问题

5.1 消息死循环：最常见的翻车现场

多智能体协作最容易出的问题就是死循环。两个智能体互相等对方回复，或者一个智能体反复调用同一个工具，都会导致流程卡死。

我遇到过一次：研究员调用搜索工具，搜索结果不理想，它就换个关键词再搜，搜了十几次还没满意，token 烧了一大半。后来加了个限制：同一个工具连续调用不超过 3 次，超过就强制返回当前结果。这个限制写在智能体的配置里，不用改工具本身的代码。

还有一种死循环是角色之间的。A 等 B 的确认，B 等 A 的补充，互相等。解决办法是设一个全局最大轮次，比如 20 轮，到了就强制结束，把当前结果返回。虽然可能不完美，但至少不会卡死。

5.2 上下文爆炸：token 消耗失控

第二个坑是 token 消耗。多智能体协作，每个角色都有自己的上下文，加起来消耗是单角色的好几倍。我做过统计：一个 3 角色的流程，如果不管控，跑一次消耗的 token 是单角色的 5-8 倍。

管控手段有三个：

• 记忆窗口：每个角色只保留最近 N 轮，我设的 10 轮。
• 消息摘要：长消息先摘要再传递，尤其是角色之间的中间结果。
• 按需加载：不是所有历史都要传给模型，只传跟当前任务相关的。

这三个手段组合使用，我把 token 消耗压到了原来的三分之一左右。

5.3 输出格式不稳定：解析失败的根源

第三个坑是输出格式。你让模型输出 JSON，它有时候给你带 markdown 代码块，有时候给你加解释文字，解析起来很头疼。

我的应对策略是双重保险：提示词里明确要求格式，同时在解析代码里做容错。比如要求输出 JSON，解析的时候先尝试直接解析，失败就提取代码块内容再解析，再失败就用正则提取关键字段。虽然麻烦，但比流程中断强。

还有一个技巧：给模型一个输出示例。提示词里写"输出格式如下：{示例}"，比单纯描述格式效果好得多。模型是模仿型选手，给它看例子比给它讲规则管用。

5.4 常见问题速查表

6. 进阶玩法：RAG 与多智能体的结合

6.1 为什么多智能体需要 RAG

多智能体协作有个天然短板：每个智能体的知识都来自模型本身，模型不知道的东西，它们也不知道。这在处理企业私有数据、最新信息、专业领域知识时特别明显。

RAG（检索增强生成）就是来解决这个问题的。它的思路是：先把知识存进向量库，智能体需要的时候去检索，把检索结果作为上下文传给模型。这样模型就能"知道"它原本不知道的东西。

AgentScope 跟 RAG 的结合，我理解下来有两种模式：

• 工具式 RAG：把检索封装成一个工具，智能体需要时调用。灵活，但需要智能体自己判断什么时候该检索。
• 注入式 RAG：在智能体处理任务前，自动检索相关内容注入上下文。省心，但可能注入不相关的内容。

我的选择是混合模式：研究员用工具式，因为它需要主动判断检索时机；撰写者用注入式，因为它只需要参考已有资料。

6.2 检索质量优化的几个实操点

RAG 的效果，七分靠检索，三分靠生成。检索做不好，后面全白搭。我踩过的坑和对应的优化：

坑一：切分粒度太粗。一开始按段落切，一段几百字，检索出来的内容太泛。后来改成按语义切，一段控制在 100-200 字，检索精度明显提升。

坑二：只做向量检索。纯向量检索对关键词不敏感，用户搜"2024 年数据"，可能返回一堆不相关的。后来加了关键词检索，做混合检索，效果好了很多。

坑三：检索结果不排序。检索出来一堆结果，直接全塞给模型，模型反而抓不住重点。后来加了重排序，只取最相关的 3-5 条，输出质量稳定多了。

6.3 一个可复用的 RAG 智能体模板

基于上面的经验，我整理了一个可复用的 RAG 智能体模板，核心配置如下：

rag_agent_config = { "name": "knowledge_researcher", "system_prompt": """你是一个知识检索专家。 根据问题检索相关知识，并基于检索结果回答问题。 要求： 1. 只基于检索到的内容回答，不要编造 2. 如果检索结果不足以回答，明确说明 3. 回答时标注信息来源 """, "tools": ["vector_search", "keyword_search"], "memory_window": 5, "retrieval_config": { "top_k": 5, "rerank": True, "hybrid": True } }

这个模板可以直接套用到大部分"基于知识库问答"的场景，改改提示词和工具配置就行。

7. 我对 AgentScope 的一些个人判断

用了一段时间，我对这个框架的整体评价是：设计思路清晰，抽象层次合理，适合做中等复杂度的多智能体应用。

它的优势在于把消息、角色、编排三层分得很干净，你不需要理解框架内部实现，就能把应用搭起来。中文文档也比较全，遇到问题查起来方便。

它的局限在于，如果你的场景特别简单（单角色 + 几个工具），用 AgentScope 有点杀鸡用牛刀；如果你的场景特别复杂（几十个角色、动态编排），框架的抽象可能又不够用，需要自己写不少扩展代码。

我个人的使用建议是：先从两三个角色的简单场景入手，跑通了再逐步加复杂度。不要一上来就设计一个庞大的多智能体系统，那样调试成本会高到让你怀疑人生。多智能体协作的本质是"分工"，分工的前提是"每个角色的职责足够清晰"，职责不清，角色再多也是互相添乱。

最后分享一个我常用的调试技巧：把每个角色的输入输出都打日志，按时间顺序排好。多智能体的问题，十有八九能从日志里看出来——要么是某个角色理解错了任务，要么是消息传递丢了信息，要么是某个环节卡住了。日志打得好，排查效率能提升一大截。