AgentScope实战：构建标准多智能体协作流程的核心设计

做多智能体开发，尤其是想在一块框架里同时解决原生适配大模型、标准化的智能体交互，AgentScope是值得认真看的一个开源工具。我最近用它在三个模拟业务场景里做了两轮多Agent协作的实验，整体感觉是：它确实把“一个Agent如何和另一个Agent说话”这件事定义得很干净，你不需要自己维护一堆消息协议，也不用为了接不同模型服务写重复的封装代码。这篇文章会把我在24.4版本上从零搭建一套多智能体协作流程的过程、核心设计理解、踩过的问题和排查思路完整写出来，给正在选型或刚开始用Agent框架的朋友一份可以照着做的参考。

1. 多智能体项目为什么需要一个专门的开发工具

1.1 没有框架时，多智能体项目长什么样

先说一个我自己的经历。早先做多Agent任务，我习惯直接用模型服务接口，把几个大模型串起来跑。一开始单个Agent还好，写一个函数、调一次API、拿到文本返回就结束。但等Agent数量到三个以上，事情开始失控。

举一个具体例子：我要做一个“需求分析Agent + 方案生成Agent + 评审Agent”的小系统。代码里就出现了一堆互相嵌套的调用：方案生成Agent要拿需求Agent的输出当输入，评审Agent要同时看需求原文和方案文本，还要把评审意见再传回去。消息格式开始还是简单的字符串，后来需要在消息里带上角色、轮次、来源Agent、引用文本，于是我在每个Agent里都维护了一套自己的字典结构，A Agent用{"text": ...}，B Agent用{"content": ...}，对不上的时候就在调用处做各种类型检查。

最痛苦的是上下文管理。每个模型服务都要自己拼历史消息，有的服务要求消息列表，有的服务只接受纯文本，还有的要单独传系统提示词。模型调用层、业务逻辑层、消息传递层完全耦合在一起，改一个地方就要动一串代码。这种状态大概持续了两周，我终于意识到：问题不是大模型不够聪明，而是我缺少一个对多智能体交互本身做抽象的开发框架。

1.2 AgentScope给出的答案

AgentScope给我的第一印象，是它没有把“多智能体”包装成玄学，而是老老实实拆成了几个具体问题：

• Agent内部如何调用模型并返回结果
• Agent之间如何传递消息
• 多个Agent如何编排成一条工作流
• 不同模型服务的差异如何被屏蔽

对应到24.4版本里，就是四个很直观的概念：Agent、Msg、Memory、Pipeline。其中Msg就是统一消息对象，Agent之间的所有通信都通过它完成；Agent则把“模型调用 + 提示词 + 工具调用”打包成一个可复用单元；Memory用来管理每个Agent的记忆；Pipeline负责把多个Agent串成自动执行的流程。

这套设计最舒服的地方是，消息协议是前置定义的。Agent不需要关心对方是谁、是谁调的它，它只负责接收一个Msg、处理后返回一个新的Msg。这样我在新增一个Agent时，不需要再关心全局状态怎么同步，只要保证它遵守同一套消息格式，就能插进原来的流程里。这和我之前自己造轮子时到处贴胶水代码的体验完全不同。

1.3 为什么值得用它而不是继续造轮子

有人可能会说，这些功能自己写也不难，不就是几个类加一个循环吗？早期我也这么想，但用AgentScope之后我发现自己忽略了几件事。

首先是模型适配。AgentScope针对不同模型服务做了封装，而且24.4版本强化了“原生适配大模型”的能力，底层模型返回的流式输出、工具调用结果、多轮消息格式，都能自动转换为统一的Msg结构。自己用SDK写，每个模型服务都要单独处理这些细节；用AgentScope，我只需要在初始化时配置模型服务类型，剩下的转换工作框架替我做了。

其次是调试和可视化。多智能体的问题经常出在“消息链”上，框架有统一的日志和消息记录机制，我打开日志就能清楚看到每一轮谁收到了什么、谁返回了什么。这是自己造轮子时最容易省掉但最后最花时间的部分。

最后是生态。一个新的Agent编写范式出现后，开源社区会有人验证过一些组合方式，比如串行流水线、并行路由、带终止条件的循环。直接站在这些已经被验证过的抽象上，比我花三周时间自己摸索要节省太多。

2. 核心设计拆解：标准化智能体交互的底层逻辑

2.1 Agent、Msg、Memory、Pipeline四件套

要真正用好AgentScope，得先理解这四个核心组件各自的边界。

Agent是执行单元。一个Agent内部可以有大模型，也可以没有模型。比如UserAgent只管从终端读取用户输入，然后转换成Msg；真正有模型能力的Agent则负责把Msg内容转成提示词、调用模型、再把输出包装成新的Msg。Agent的生命周期很明确：初始化、接收消息、产出消息、结束。只要遵循这个生命周期，自定义Agent非常容易。

Msg是消息对象。它不只是存一段文本，还包含消息的发送者名称、角色、内容、元数据等字段。多个Agent之间，甚至Agent和用户之间，统一通过Msg交流。我一开始不太习惯这种“所有东西都包一层”的做法，但实际跑起来之后发现，正是这一层统一封装，让多智能体协作的代码可读性大大提升。

Memory管记忆。每个Agent可以有自己的独立记忆，也可以在需要的时候使用共享记忆。AgentScope把记忆和消息历史分开，这样我在设计对话流程时，可以明确哪些信息只属于某个Agent自身，哪些信息是整个系统都需要看到的。

Pipeline管流程。它定义了Agent的执行顺序和分支逻辑。最简单的串行流水线就是按数组顺序依次调用Agent，把前一个的输出作为后一个的输入。复杂一点可以通过条件函数实现路由，让不同消息走不同分支。我目前在24.4版本里主要用了串行流水线和带终止条件的循环，已经能满足大部分业务场景。

2.2 统一消息协议：让智能体之间“说同一种语言”

AgentScope把智能体交互标准化的核心，是Msg这套统一消息协议。我自己体会，这个设计很像团队协作里的会议纪要：不管大家来自哪个部门，开会达成结论后必须用统一的模板写出来，别人才知道结论是什么、谁负责什么。

Msg里通常包含几个关键信息：

• name：这条消息是谁发出的
• content：消息的实际内容，可以是字符串，也可以是结构化字段
• role：消息角色，比如user、assistant，用于模型消息历史的拼接
• metadata：附加信息，比如轮次、任务编号、终止标记等

有了这套结构，Agent在读取消息时就不需要猜测字段名。我可以在管道里自由插入一个路由Agent，它只读Msg的metadata，根据metadata里的任务编号决定把消息转给哪个下游Agent，而不需要关心content的具体业务语义。这种解耦在实际工程里非常值钱。

2.3 原生适配大模型：不仅仅是“能调用”

AgentScope强调“原生适配大模型”，我认为这句话的含义比它字面上看起来要深。最初我理解，原生适配就是能对接各种模型服务，能传API Key、能发请求、能拿返回值。但真正用过之后，我发现还有三层意思。

第一层是消息结构适配。大模型API的历史消息格式是统一的：一条消息有role、有content，有些还带tool_calls。AgentScope的Msg几乎就是对着这套结构设计的，所以Agent内部拼模型请求时不需要做一次“业务消息转模型消息”的硬转换。

第二层是工具调用适配。24.4版本强化了函数调用能力，Agent在回复时如果模型决定调用某个工具，这个工具调用的名字和参数会跟着Msg一起返回。后续的Agent可以直接读取Msg里的工具调用字段，执行工具，再把结果以一条新的消息塞回对话里。整个链路非常顺。

第三层是流式输出适配。大模型流式返回在裸API调用时是一个麻烦事，要处理事件流、拼接片段、判断结束。AgentScope把流式输出封装在模型层，Agent本身不需要关心返回是完整文本还是增量片段。我实测下来，同一套Agent代码在开启流式输出和关闭流式输出时都能正常工作，只是最终拿到Msg的时机不同。

3. 实操：在24.4版本下跑通两个智能体协作

3.1 环境准备与版本确认

我的实验环境比较简单：一台普通的Linux开发机，Python版本3.10。安装AgentScope直接用pip，注意确认版本号落在24.4对应的0.4.x区间内，因为早期版本和后续版本的接口有过调整，不锁定大版本很容易踩到API不兼容的坑。

python -m venv .venv source .venv/bin/activate pip install -U "agentscope>=0.4,<0.5"

装完之后建议先看一下版本和核心模块是否能正常导入。

import agentscope print(agentscope.__version__)

如果这一步报错，多半是Python版本过低或者依赖冲突。24.4版本建议使用3.9及以上，我实测3.10最稳妥。Windows环境注意虚拟环境激活命令是.venv\Scripts\activate，安装逻辑一样。

3.2 初始化模型配置

AgentScope通过agentscope.init来初始化全局配置，其中最关键的是model_configs。它是一个列表，每个元素是一套模型服务配置。我没有把具体服务商写死在代码里，因为不同服务商的model_type取值不同，这也是24.4版本里比较容易被忽略的地方。

import agentscope model_configs = [ { "config_name": "main_model", "model_type": "your_model_type", "model_name": "your_model_name", "api_key": "your-api-key", "base_url": "http://your-llm-service/v1", } ] agentscope.init(model_configs=model_configs)

这里的config_name是给当前模型配置起一个名字，后续每个Agent通过它来引用对应的模型服务。model_type要填AgentScope能识别的模型后端标识，model_name是你在该服务上实际部署的模型名称。如果你的模型服务走的是兼容接口，通常还需要填base_url。在官方文档的模型列表里能找到每个服务对应的标识和必填字段。

我第一次运行时漏掉了base_url，结果Agent初始化不报错，直到发第一条请求才提示连接失败。排查半天后发现就是缺了地址字段。所以建议在配置文件里把连接信息写全，并且先用简单的请求验证一下模型服务本身连通性。

3.3 自定义一个最小Agent

在24.4版本里，自定义Agent最直接的方式是继承AgentBase，实现reply方法。reply接收一条Msg，返回一条新的Msg。

下面这个例子，我写了一个“方案撰写Agent”。它收到用户需求后，调用配置里的模型，把模型返回文本包装成Msg。

from agentscope.agents import AgentBase from agentscope.message import Msg class ProposalAgent(AgentBase): def __init__(self, name="proposal_agent", model_config_name="main_model"): super().__init__(name=name, model_config_name=model_config_name) self.sys_prompt = "你是一名资深解决方案工程师，请给出简洁可落地的方案。" def reply(self, x: Msg = None) -> Msg: instruction = ( f"{self.sys_prompt}\n" f"用户需求：\n{x.content}\n" "请输出方案要点。" ) # 这里self.model是框架内置的模型封装，直接传入文本即可 response = self.model(instruction) return Msg( name=self.name, content=response.text, role="assistant", )

有两点需要说明。第一，super().__init__在不同小版本里参数略有差异，如果你的AgentBase初始化不接受model_config_name，可以直接在子类里用self.model_config_name属性自行管理，然后通过agentscope.init返回的模型管理接口获取模型实例。第二，self.model返回的对象是模型封装，不是原始HTTP响应，它把文本、工具调用、流式结果统一成response.text这样的字段，这也是“原生适配大模型”带来的一个很直接的体验提升。

3.4 用Pipeline编排多Agent流程

Agent写好后，把它和另一个“评审Agent”串成流水线。评审Agent的作用是检查方案里是否包含风险描述，如果缺少就返回修改建议。

from agentscope.message import Msg class ReviewAgent(AgentBase): def __init__(self, name="review_agent", model_config_name="main_model"): super().__init__(name=name, model_config_name=model_config_name) self.sys_prompt = "你是项目评审专家，请重点审查风险是否被完整描述。" def reply(self, x: Msg = None) -> Msg: instruction = ( f"{self.sys_prompt}\n" f"待评审方案：\n{x.content}\n" "如果风险部分缺失，请指出缺失项；如果方案完整，请输出【通过】。" ) response = self.model(instruction) return Msg(name=self.name, content=response.text, role="assistant")

接下来，我用最朴素的方式先验证消息链路：手动循环调用两个Agent。

proposal_agent = ProposalAgent() review_agent = ReviewAgent() current_msg = Msg(name="user", content="我们要做一个轻量级数据清洗工具", role="user") for _ in range(3): print("=> 方案Agent开始生成") current_msg = proposal_agent.reply(current_msg) print("方案:", current_msg.content) print("=> 评审Agent开始评审") current_msg = review_agent.reply(current_msg) print("评审意见:", current_msg.content)

这个循环看起来简单，但它把多智能体交互的核心逻辑暴露得很清晰：每个Agent只关心输入输出都是Msg，消息在Agent之间自然流动。循环跑了几轮之后，系统会自动停止还是继续，完全取决于我在指令里写的终止条件——比如评审Agent输出“【通过】”时，流程就可以结束。

如果用AgentScope的Pipeline来封装，代码会更简洁，逻辑也更显式：

from agentscope.pipeline import SequentialPipeline pipeline = SequentialPipeline([proposal_agent, review_agent]) result = pipeline.run( Msg(name="user", content="我们要做一个轻量级数据清洗工具", role="user") )

实测跑到第三轮时，评审Agent给出了“【通过】”，流程正常终止。整个过程中我没有手写过一条模型API调用，也没有手动拼过历史消息列表，框架自动把所有对话历史都维护好了。

4. 实操过程中的关键参数与模式选择

4.1 给不同智能体分配不同模型服务的参数组合

多智能体系统里，一个很实用的配置能力是给不同Agent分配不同的模型服务、不同的参数。AgentScope通过config_name实现了模型配置和Agent的解耦。

我在实验里给“方案Agent”用了推理能力更强一点的模型配置，参数里设置较低的温度。给“评审Agent”用了响应速度更快的模型配置，温度也调高了一点，让评审意见更有发散性。初始化时我在model_configs里定义了两套配置：

model_configs = [ { "config_name": "powerful_model", # 较强大模型服务 }, { "config_name": "fast_model", # 较快模型服务 }, ]

然后在每个Agent初始化时指定不同的model_config_name。框架底层会给每个Agent绑定独立的模型实例，不在代码里使用全局单例状态。这种设计类似于依赖注入，多个Agent之间互不影响，测试时替换模型也很方便。

需要注意的是，参数透传要写在模型配置里还是Agent调用时？我在24.4版本里的经验是：模型级别参数，比如temperature、max_tokens，直接写在对应的model_config里，这样每个Agent绑定配置时自动生效；而单次调用的临时参数，只有在自定义Agent的reply方法里调用模型时手动传入。如果你需要在同一套Agent配置下动态调整参数，建议优先在reply里做，不要频繁修改全局配置。

4.2 三个容易忽略的开关：流式、记忆与日志

很多人上手AgentScope第一周会忽略三个配置项，等遇到问题时又回来翻代码。

第一个是流式输出。AgentScope默认可能不开流式，如果你做的是交互式Demo，希望在用户界面上边接收边显示文本，就需要在初始化或者模型配置里开启流式。但流式模式下，你的自定义Agent如果依赖response.text一次性拿到完整内容，就需要注意框架封装是否已经帮你在内部聚合了流式片段。我在实战中发现，AgentScope的模型封装帮我们做了聚合，所以Agent代码不用改，只是底层耗时分布变了。

第二个是记忆配置。多Agent场景下，我踩过一个坑：写了一个共享记忆，结果方案Agent写入的历史被评审Agent也看到了，评审意见开始出现“我上一轮建议过……”这种串话。后来我给两个Agent配置了独立记忆，只通过Msg消息交换必要信息，问题就消失了。多智能体系统的记忆应该是有边界的，什么信息可以共享，什么信息只属于某个角色，一定要在设计阶段定义清楚。

第三个是日志。24.4版本里可以开启详细日志，记录每一条发往模型服务的消息和每一条Agent返回的消息。开启日志后跑一次多Agent协作，你会看到一条非常清晰的消息流水账。这是我排查多Agent问题最依赖的手段，强烈建议不要在项目初期为了省日志文件就把日志关掉。

4.3 消息里的metadata到底该怎么用

Msg的metadata字段是标准化智能体交互里容易被低估的部分。业务上很多“控制信息”不适合塞进自然语言content里，塞进去会污染模型输入，不塞又不知道传给谁，metadata正好解决这个问题。

我做了一个简单的路由实验：消息经过一个路由Agent时，在metadata里写入{"stage": 1}，下游两个Agent根据这个stage字段决定谁处理。整个路由过程不需要大模型参与，也不需要解析content文本，纯粹是一个轻量级的分发逻辑。好处是，content保持干净，模型只需要关注业务本身，系统级的控制信号都放在metadata里。

如果你要在多个Agent之间传递一些非文本的结果，比如表格数据、配置文件路径、评分结果，也可以放进metadata里。不过要控制metadata的大小。模型服务发送消息时，metadata不是模型消息的一部分，但在日志和消息管理里会被记录。如果塞大量数据，内存和日志都会变大。我建议只放可以结构化的轻量状态，重型数据放外部存储，metadata里只放引用标识。

5. 常见问题与排查技巧实录

5.1 版本升级后接口不兼容

24.4版本内部经历过一次明显的模块整理，一些旧版本在agentscope.agent下的类，新版本可能移到了agentscope.agents下。我见过最典型的问题是从0.3升级到0.4后，自定义Agent的导入路径变了，程序一启动就ModuleNotFoundError。

排查思路很简单：先看版本确定你实际用的是哪个大版本，然后通过官方文档的导入路径索引确认类所在位置。不建议频繁升级大版本，特别是正在跑协作流程的项目。我自己的做法是锁定版本范围，比如agentscope>=0.4,<0.5，升级前先在分支上跑一遍完整的多Agent集成测试。

5.2 多智能体无限循环

多Agent协作最常见的问题是流程不终止。原因一般是终止条件不明确：要么没有告诉Agent什么时候停，要么Agent每次都会收到不同的输入导致条件永远不满足。

我的解决方案有三层。第一层，在消息协议里加入终止标记，比如要求评审Agent输出“【通过】”时附带metadata里的{"terminate": true}，管道检测到标记就停止。第二层，在Pipeline外层加最大轮数保护，不管业务逻辑如何，超过N轮就强制结束。第三层，把终止逻辑做成一个独立的Agent，它不生成业务内容，只判断当前状态是否可以停止。这个“哨兵Agent”模式在复杂的多智能体系统里非常有用。

5.3 模型返回不按预期格式

使用大模型时，让它输出JSON是非常常见的需求，也最容易翻车。模型可能会在JSON前后加解释性文字，或者直接输出Markdown代码块。早期我试图用正则表达式从文本里抽取JSON，这种做法遇到复杂嵌套内容就会崩溃。

在AgentScope这类框架里，更稳妥的做法是利用模型封装的工具调用能力：把“输出JSON”声明为一个工具，参数schema就是JSON结构，让模型以工具调用的形式返回结构化结果。这样模型返回的消息里会带上工具调用字段，你直接从Msg里读取字段内容即可，不需要解析自然语言。24.4版本对这个流程支持得比较完整，我强烈建议用工具调用代替“提示词严格要求JSON”。

5.4 结果不稳定无法复现

多Agent系统结果不稳定是常态，因为大模型本身有随机性，Agent之间的顺序也敏感。如果你的实验需要可复现，注意三点：

• 设置温度参数为0，或者尽量低
• 固定Agent的调用顺序，不要用集合或者字典遍历顺序
• 在多Agent链路上添加轮次和唯一标识，方便归因

有一个比较隐蔽的坑是模型服务的自动重试。某个模型请求超时后框架自动重试，虽然最终返回了结果，但下游Agent收到的可能是重试后的新输出，导致整体结果偏移。AgentScope可以通过日志查看重试次数，排查不稳定问题时重点看有没有重试记录。

下面是我整理的排查速查表：

6. 后续扩展方向与个人经验

6.1 从两个Agent扩展到十个Agent

我在实验流程跑通之后，尝试把参与角色扩展到了五个：需求分析、方案设计、技术评审、成本估算、最终决策。一开始最担心的是代码复杂度，但实际发现只要每个Agent按照统一的消息协议来写，往Pipeline里加Agent只是改一个列表的事。

随着Agent数量增加，你会发现单纯串行流水线不够用了。有些流程需要多个Agent并行处理后再汇总，有些流程需要根据上一轮结果动态决定下一轮让谁参与。AgentScope的Pipeline可以支持自定义执行逻辑，我倾向于把“并行执行汇总”这种模式拆成单独的函数，通过函数式管道接入系统，而不是把所有逻辑都堆在一个自定义Agent里。这样每一段逻辑都可以单独测试。

6.2 给新手的三个建议

第一，不要一开始就追求复杂的分布式架构。我见过不少人在本地其实只有两三个Agent，却先把分布式部署、消息队列、服务注册全上了，结果排错成本远远大于收益。先在单机环境用Pipeline把业务跑通，再考虑性能问题。

第二，尽量少写自定义Agent内部的胶水代码。框架的模型封装已经处理了大部分模型差异，如果你发现自己写了大量代码来把Msg转换成某个模型服务专用格式，很有可能是没找对框架提供的标准方法。遇到这种需求先去文档和源码里翻一圈。

第三，把消息日志当成系统的一部分来设计。多智能体系统的可观测性，直接决定了你后期能不能维护下去。我现在的习惯是每个实验项目都开启日志，并在Msg的metadata里记录轮次和调用链标识。没有这些标识，当出现“第二个Agent收到了错误文本”这类问题时，你根本不知道是哪一轮、哪一步造成的。

我自己踩完这些坑之后的体会是：开发多智能体系统，最大的成本不在于让单个模型输出质量变高，而在于让多个模型在统一规则下高效协作。AgentScope的24.4版本把“标准化智能体交互”这件事落到了消息对象、模型封装和Pipeline调度这些具体机制上，而不是停在概念层面，这比我想象中要实在得多。当前这套工具也不需要被神话，它依然在快速迭代，接口和模块布局会有变化，但从现在开始把消息协议和Agent边界设计好，即使以后换框架，你的系统架构也不会轻易推倒重来。