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 的工作流编排我理解下来核心就一句话流程是流程角色是角色两者通过消息接口对接。它提供了几种典型的编排模式编排模式适用场景特点顺序执行流水线式任务A 的输出是 B 的输入简单直接易调试并行执行多个独立子任务同时跑省时间但要注意结果合并条件分支根据中间结果决定走哪条路灵活但分支逻辑要清晰循环迭代需要反复打磨的任务如写作、代码审查要设好终止条件否则死循环群组对话多角色讨论、辩论、投票最接近团队协作的形态这里有个经验不要一上来就用最复杂的编排模式。我见过不少人明明一个顺序执行就能搞定的事非要用群组对话结果调试成本翻了好几倍。编排模式的选择标准很简单——看任务本身有没有并行或反复的需求没有就用最简单的。3. 核心模块逐个拆从智能体定义到工具调用3.1 智能体定义一个角色由哪几部分组成在 AgentScope 里定义一个智能体本质上是在回答四个问题它是谁名字、角色描述、系统提示词。它会什么可以调用的工具列表。它记得什么记忆模块决定它能记住多少轮对话、要不要做长期记忆。它怎么说话用哪个大模型、温度设多少、要不要流式输出。这四部分里最容易出问题的是系统提示词和记忆配置。系统提示词不是越长越好。我踩过的坑是一开始把角色描述写得特别详细恨不得把这个人设的前世今生都写进去结果模型反而抓不住重点回复变得又臭又长。后来改成一句话定位 三条行为准则 两个输出示例效果明显好了。核心原则是提示词要约束行为而不是描述背景。记忆配置这块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 openaiAgentScope 本身不绑定特定的大模型你可以接 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 工作流编排与消息流转三个角色定义好了接下来是编排。这个场景是典型的顺序 循环结构规划者接收主题输出子问题列表。对每个子问题研究员依次处理输出要点。所有要点汇总后交给撰写者输出报告。用 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 常见问题速查表问题现象可能原因排查方向解决办法流程卡住不动消息死循环看日志里哪个角色在反复调用设最大轮次和工具调用上限token 消耗异常高上下文未管控统计每个角色的输入长度加记忆窗口和消息摘要输出解析失败格式不稳定看原始输出长什么样加输出示例和解析容错角色行为不符合预期提示词太模糊检查提示词有没有约束行为改成定位 准则 示例结构工具调用失败率高参数类型不清看工具描述是否完整补类型标注和使用场景说明响应速度慢串行执行太多看哪些步骤可以并行把独立任务改成并行编排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 有点杀鸡用牛刀如果你的场景特别复杂几十个角色、动态编排框架的抽象可能又不够用需要自己写不少扩展代码。我个人的使用建议是先从两三个角色的简单场景入手跑通了再逐步加复杂度。不要一上来就设计一个庞大的多智能体系统那样调试成本会高到让你怀疑人生。多智能体协作的本质是分工分工的前提是每个角色的职责足够清晰职责不清角色再多也是互相添乱。最后分享一个我常用的调试技巧把每个角色的输入输出都打日志按时间顺序排好。多智能体的问题十有八九能从日志里看出来——要么是某个角色理解错了任务要么是消息传递丢了信息要么是某个环节卡住了。日志打得好排查效率能提升一大截。 
长河君 · 2026/9/28 13:14:27 · 阅读 1.2k 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 的工作流编排我理解下来核心就一句话流程是流程角色是角色两者通过消息接口对接。它提供了几种典型的编排模式编排模式适用场景特点顺序执行流水线式任务A 的输出是 B 的输入简单直接易调试并行执行多个独立子任务同时跑省时间但要注意结果合并条件分支根据中间结果决定走哪条路灵活但分支逻辑要清晰循环迭代需要反复打磨的任务如写作、代码审查要设好终止条件否则死循环群组对话多角色讨论、辩论、投票最接近团队协作的形态这里有个经验不要一上来就用最复杂的编排模式。我见过不少人明明一个顺序执行就能搞定的事非要用群组对话结果调试成本翻了好几倍。编排模式的选择标准很简单——看任务本身有没有并行或反复的需求没有就用最简单的。3. 核心模块逐个拆从智能体定义到工具调用3.1 智能体定义一个角色由哪几部分组成在 AgentScope 里定义一个智能体本质上是在回答四个问题它是谁名字、角色描述、系统提示词。它会什么可以调用的工具列表。它记得什么记忆模块决定它能记住多少轮对话、要不要做长期记忆。它怎么说话用哪个大模型、温度设多少、要不要流式输出。这四部分里最容易出问题的是系统提示词和记忆配置。系统提示词不是越长越好。我踩过的坑是一开始把角色描述写得特别详细恨不得把这个人设的前世今生都写进去结果模型反而抓不住重点回复变得又臭又长。后来改成一句话定位 三条行为准则 两个输出示例效果明显好了。核心原则是提示词要约束行为而不是描述背景。记忆配置这块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 openaiAgentScope 本身不绑定特定的大模型你可以接 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 工作流编排与消息流转三个角色定义好了接下来是编排。这个场景是典型的顺序 循环结构规划者接收主题输出子问题列表。对每个子问题研究员依次处理输出要点。所有要点汇总后交给撰写者输出报告。用 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 常见问题速查表问题现象可能原因排查方向解决办法流程卡住不动消息死循环看日志里哪个角色在反复调用设最大轮次和工具调用上限token 消耗异常高上下文未管控统计每个角色的输入长度加记忆窗口和消息摘要输出解析失败格式不稳定看原始输出长什么样加输出示例和解析容错角色行为不符合预期提示词太模糊检查提示词有没有约束行为改成定位 准则 示例结构工具调用失败率高参数类型不清看工具描述是否完整补类型标注和使用场景说明响应速度慢串行执行太多看哪些步骤可以并行把独立任务改成并行编排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 有点杀鸡用牛刀如果你的场景特别复杂几十个角色、动态编排框架的抽象可能又不够用需要自己写不少扩展代码。我个人的使用建议是先从两三个角色的简单场景入手跑通了再逐步加复杂度。不要一上来就设计一个庞大的多智能体系统那样调试成本会高到让你怀疑人生。多智能体协作的本质是分工分工的前提是每个角色的职责足够清晰职责不清角色再多也是互相添乱。最后分享一个我常用的调试技巧把每个角色的输入输出都打日志按时间顺序排好。多智能体的问题十有八九能从日志里看出来——要么是某个角色理解错了任务要么是消息传递丢了信息要么是某个环节卡住了。日志打得好排查效率能提升一大截。