AgentScope：用标准化消息与执行图搞定多智能体协作

如果你最近在折腾多智能体（Multi-Agent）应用，大概和我一样被同一个问题反复折磨：单个大模型Agent很好写，三五个Agent放在一起，消息一多、状态一乱，整个应用就像一团毛线球。我上个月做一个“资料调研助手”的Demo时，就经历过这种痛苦——搜资料的Agent、清洗数据的Agent、负责写报告的Agent，各自调用模型，互相传字符串，结果上下文越拼越乱，模型经常“忘记”前面的人说了什么，更别提把其中一个Agent换成另一种模型时，所有调用代码都得改一遍。

后来我换成了AgentScope这个开源框架，才真正感受到“原生适配大模型”和“标准化智能体交互”这两个词的分量。它给我的感觉是：别的工具是让你把Agent组织起来，而AgentScope是先把Agent之间的“语言”和“交通规则”定好，再让你组织。这篇内容，我就想把它解决的核心问题、执行模型、消息交互机制、以及我从搭Demo到踩坑调优的完整过程，一次性讲清楚。适合正在选型多智能体框架、或者因为手写编排代码而头疼的开发者参考。

1. 多智能体开发为什么这么别扭：从我的踩坑现场说起

1.1 一个“调研助手”需求背后的多智能体难题

我的需求其实很简单：给一个主题，让几个Agent协作完成调研报告。最朴素的拆分是一个搜索Agent负责收集素材，一个筛选Agent负责去掉重复和无关内容，一个总结Agent负责写报告。听起来没什么难度，但用基础API硬写时，问题一个接一个冒出来。

第一是上下文失控。三个Agent如果共享同一个聊天历史列表，A的输出会变成B的输入，B的输出又回到A的历史里，模型分不清哪些话是“指令”、哪些是“中间结果”。第二是工具调用不统一。搜索Agent要调搜索接口，筛选Agent要调去重函数，每个Agent的调用参数、返回格式都是我临时定义的，今天想给其中一个加个处理步骤，连带其他Agent的代码一起改。第三是无法复用。换一个场景做客服助手时，发现搜索Agent没法直接挪过去，因为消息格式、触发方式全被写死在上一个Demo里了。

这些问题的根源不是模型不够强，而是多智能体协作的“基础设施”没人管。语言模型擅长的是生成文字，但多个Agent之间怎么传递信息、谁先执行谁后执行、某个Agent挂了怎么处理、如何把同一个Agent部署到不同机器上，这些问题模型自己解决不了，需要框架来兜底。

1.2 AgentScope到底想解决什么

AgentScope的核心思路，是把你熟知的Actor模型搬到多智能体场景里。每个Agent是一个独立的执行单元，可以有自己的状态、自己的模型配置、自己的工具列表；Agent之间不直接互相调用函数，而是通过消息传递来完成交互。这和我之前“函数套函数”的写法有本质区别：函数调用是同步的、强耦合的，消息传递则是异步的、松耦合的。

在此基础上，AgentScope提供了一套消息标准、一个执行编辑器（Pipeline），以及一套分布式支持。换句话说，它想让你像写流程图画一样编排智能体，而不是像写意大利面条代码一样把Agent粘在一起。标题里说的“原生适配大模型”，我的理解是：它从一开始就是为大模型应用设计的，消息里能天然承载角色、内容、工具调用结果这些概念，不需要自己再包一层适配器。

2. 执行模型：把“Agent怎么协作”变成一张有向无环图

2.1 节点是Agent，边是消息：让流程不再写死在代码里

我第一次看到AgentScope的执行图设计时，有种“早该这样”的感觉。它把整个应用建模成一张图：每个节点是一个Agent或一个操作，每条边是节点之间传递的消息。调度器负责按照图的结构依次执行节点、转发消息，并收集最终结果。

这与硬编码调用链的区别在哪里？硬编码是result = agent_c(result_b)，顺序固定、逻辑固定，想加一个并发分支就要自己开线程。而执行图是声明式的，你只需要交代“A完成后消息给B和C，B和C都完成后消息汇总给D”，具体怎么并发、怎么等待，由框架处理。我后来在Demo里加了并行搜索分支，改的只是图定义，不是Agent内部逻辑。

2.2 单个Agent内部的四段式工作

不要以为AgentScope里的Agent是个黑盒，它把每个Agent内部的工作流程也拆成了标准步骤：

1. 接收消息：从上游拿到一条Msg对象，解析出内容、来源、角色等元数据。
2. 指令解析：把消息内容按照Agent的配置，变成模型可以理解的提示词。
3. 推理生成：调用配置好的大模型API，这一步可以挂工具调用、也可以做输出格式约束。
4. 输出消息：把模型输出包装成标准消息格式，发给下游。

一个最简单的Agent定义大概是这样的：

import agentscope from agentscope.agent import DialogAgent # 初始化框架，配置模型 agentscope.init( model_configs={ "config_name": "my-gpt", "model_type": "openai", "model_name": "gpt-4o-mini", "api_key": "你的API_KEY", } ) # 创建两个角色 searcher = DialogAgent( name="searcher", sys_prompt="你是一个专注收集资料的助手。", model_config_name="my-gpt", ) writer = DialogAgent( name="writer", sys_prompt="你是一个严谨的报告撰写者。", model_config_name="my-gpt", )

注意这里我把api_key写成占位符，实际使用时建议用环境变量注入。DialogAgent是最基础的对话Agent，需要更复杂的推理可以换成ReActAgent或者自定义Agent类。每个Agent的sys_prompt是独立的，模型上下文也是分开维护的，这点非常重要——它天然避免了多Agent共享聊天历史导致的“串台”问题。

2.3 为什么说“原生适配大模型”对开发效率影响很大

早年间做对话机器人，处理消息就是处理字符串；但大模型场景下，消息天然应该带上角色（system/user/assistant）、工具调用ID、多模态内容等结构化信息。AgentScope的Msg对象把这些都做成了内置概念，我不用自己设计“哪段是系统提示、哪段是搜索结果”这类传参协议，框架内部和Agent之间都认同一套消息格式。这感觉就像：你不需要为每个Agent发明一种方言，大家都说普通话。

3. 标准化智能体交互：消息协议与服务化的设计细节

3.1 统一消息模型：多Agent协作的第一块地基

我把AgentScope的消息模型理解成一套“信封规范”。信封上有寄件人（name）、收件人（可指定或广播）、正文（content）、用途说明（role），还可以附上额外元数据。信的内容可以是纯文本，也可以是结构化字典。这一层标准化带来的最大收益是：Agent与Agent之间不依赖具体实现，只依赖消息格式。

举个例子，搜索Agent返回的内容可以统一包装成：

msg = Msg( name="searcher", content={"type": "search_result", "items": [...]}, role="assistant", )

下游筛选Agent不必知道searcher内部是怎么调用搜索接口的，它只要按content["items"]处理即可。将来把searcher从某搜索服务换成另一个搜索服务，下游Agent完全不用动。这种“面向协议编程”的方式，多Agent应用才能做大，否则智能体数量一多，靠人肉记住每个Agent的输入输出格式是不现实的。

3.2 基于服务的交互方式：让Agent不只在进程内存在

标准化消息还有一个容易被忽视的好处：Agent的服务化。AgentScope的交互协议不限于进程内对象调用，一个Agent也可以被封装成一个标准的后端服务，其他应用通过API调用它。这意味着同一个Agent可以被多个前端复用，也可以拆到不同的进程、不同的机器上部署。

我在做Demo时就把“搜索Agent”单独跑成一个服务，主流程在另一个进程里调用它，这样搜索逻辑的改动和主流程的迭代互不干扰。如果所有Agent都在同一个进程里写死，这个拆法是很难做的。消息标准化之后，跨进程传的内容仍然是同一套消息结构，不需要为了网络传输设计第二套协议。

3.3 组内复用的正确姿势：一套消息协议跑通所有场景

我自己摸索出来的一条经验是：团队里如果要长期维护多个智能体应用，最好在AgentScope的消息模型之上再固定一层业务字段规范。比如所有业务消息都包含type字段，type决定content的结构；所有失败场景统一约定错误消息格式。这样任何一个新Agent接入，先看协议文档，再看Demo，半天内就能跑通。AgentScope的Msg可以携带任意结构化内容，天然支持这种约定。

4. 手写一个三智能体工作流Demo：从编排到跑通的完整过程

4.1 环境初始化与基础配置

先装依赖，用pip直接装就行：

pip install agentscope

我自己在Python 3.10环境下跑没问题，其他常用版本应该也兼容。安装完成后，初始化部分建议单独写成一个配置文件，不要硬编码在代码里：

# model_configs.yaml model_configs: - config_name: "my-llm" model_type: "openai" model_name: "gpt-4o-mini" api_key: "your_key"

然后代码里这样加载：

import agentscope agentscope.init(model_configs="model_configs.yaml")

这一步会把框架的全局配置初始化好，后面所有Agent默认使用这套模型配置。如果项目里要同时用不同模型，可以在init里传入多个配置，并给不同Agent指定不同的config_name。

4.2 定义三个Agent并串联成Pipeline

我做的Demo是“收集-筛选-总结”三个角色：

from agentscope.agent import DialogAgent from agentscope.pipeline import Pipeline with Pipeline() as pipe: collector = DialogAgent( name="collector", sys_prompt="你是一个资料收集者，根据用户问题列出5条关键素材，只输出列表。", ) filter_agent = DialogAgent( name="filter_agent", sys_prompt="你是一个内容审核者，从列表中删除重复和低质量项，保留3条。", ) summarizer = DialogAgent( name="summarizer", sys_prompt="你是一个报告撰写者，根据筛选后的素材写一段200字总结。", ) # 串联执行 msg = PipeMessage(content="介绍一下某开源框架的核心设计") filtered_msg = filter_agent(collector(msg)) result_msg = summarizer(filtered_msg) result = pipe.run()

这只是一个串行示例，但重点在于：三个Agent的名字、提示词、处理逻辑完全独立，串联关系是在Pipeline里声明的。我把这些定义放到一个模块里，另一个脚本直接导入，整个流程就复用了。

4.3 运行一次的真实输出与日志解读

跑通一次之后，框架会打印每个Agent的消息流转日志。我观察到的关键信息包括：消息从collector发出，到filter_agent接收；filter_agent输出三条，再传给summarizer；summarizer生成最终总结。你可以看到每条消息的name、role和时间戳。

对于刚上手的人来说，建议开一个调试模式，把每个Agent收到的原始消息和最终输出都打印出来。因为大模型输出会带一定随机性，排查问题时必须能确认“哪个Agent在哪一步产生了意外内容”，日志能帮你快速定位。

4.4 调整流程的两个实用技巧

一是给Agent加超时与重试。模型接口偶尔会超时或返回空内容，AgentScope允许你配置重试次数。二是给关键Agent加约束输出。比如要求filter_agent只输出JSON列表，并用tool参数约束格式，这样下游解析稳定很多。我的经验是：越早做格式约束，后面调试越省心。

5. 从单机到分布式：当Agent数量超过单机承载之后

5.1 分布式到底解决了什么问题

如果你的应用只是三五个Agent串行跑，单机足够了。但当Agent数量变多、或者不同Agent需要用不同模型（比如一个用开源小模型跑本地，一个用云端大模型）、再或者某个Agent承载高并发请求时，把所有Agent强行塞进一个进程就会捉襟见肘。

AgentScope的分布式能力解决的核心问题是：把执行图里的不同节点，调度到不同计算资源上执行。这样每个节点可以单独扩容、单独更新，互不影响。我为了体验分布式，把一个Agent放到独立的脚本里跑，主进程通过网络消息与它通信，这种“物理上分离、逻辑上仍是一个图”的开发体验是相当顺滑的。

5.2 我建议的部署切分方式

不要一开始就追求全分布。我的建议是把应用分成两类节点：一类是无状态的计算型Agent，另一类是带业务状态的协调型Agent。计算型Agent做搜索、格式转换、调用外部工具，这类适合拆出去做水平扩容；协调型Agent负责流程决策，拆出去的收益不大。

具体到AgentScope，你先在Pipeline里把图定义好，跑通单机，再按节点属性拆分部署。先把消息协议定好，后续迁移时改动的是连接方式，不是Agent内部逻辑，这是框架给的最大红利。

5.3 分布式要特别注意的同级消息同步问题

跨进程之后，消息的时效性和顺序性就没单机那么简单了。网络抖动会带来消息延迟或重复，乐观地说框架会做很多底层的消息处理，但业务上还是要自己考虑幂等性——同一个Agent如果收到两条内容重复的消息，会不会重复执行？我的做法是给消息加上递增序号，并在Agent里记录已处理序号，重复消息直接忽略。这类问题在demo里不明显，上了生产环境就会变成大问题。

6. 实测中的意外与调优：我在Demo里踩过的坑

6.1 Agent突然“失忆”：上下文长度爆炸的锅

我第一次跑三Agent串行时，发现第二个Agent经常忘记第一个Agent的指令细节。查了半天，原因是我让第一个Agent“把总结也写进历史消息”，导致传给第二个Agent的上下文里塞满了原始素材，超过了模型的上下文窗口，于是模型自动丢弃了最早的信息。这就像一个人记性有限，前面的任务目标被挤出了大脑。解决办法是：明确每个Agent的历史中应该保留什么，把不必要的历史消息裁剪掉。我在每个Agent内部维护精简的任务描述，而不是把所有中间过程都堆进去。

6.2 模型输出不符合预期：格式约束比提示词更可靠

第二坑是模型输出不稳定。我让filter_agent输出“3条筛选结果”，它有时给列表，有时给描述，下游summarizer一解析就崩溃。后来我改用模型API的JSON输出约束，配合一个校验函数，解析失败就重新请求一次。大概流程是：Agent内部先做一次输出校验，合法才发给下游，不合法就让模型重新生成。这样下游Agent永远只处理合法消息，整体稳定性提升很多。

6.3 并行分支触发限流：熔断与排队策略

给Pipeline加了并行搜索分支后，短时间内多个Agent同时调用同一个模型API，然后被限流了。解决思路是先给API调用加一个“令牌桶”式限速，限制每秒请求数；再对失败请求做指数退避重试。不要一开始就把重试次数设很高，否则限流一恢复，所有Agent又同时冲上去，反而再次触发限流。我在实践中把最大重试次数设为3，退避倍率2倍，效果够用。

6.4 本地Agent与云端Agent混合编排时的资源等待

如果你的应用里有一个跑本地小模型的Agent和一个跑云端大模型的Agent，本地节点很慢，云端节点空闲等待。“慢节点”会拖慢整个流程。我的建议是给慢节点单独扔到一个进程中运行，并让它提前并行准备；或者用“流式返回”的思维，把第一个节点的中间结果先送给下游，不必等完全处理完。AgentScope的消息机制对这些场景的友好度很高，它不需要下游Agent关心上游是同步还是异步。

7. 为什么我没有直接选LangChain或AutoGen：横向比较与选型建议

7.1 三个框架的底层思路差异

市面上常见的多智能体框架各有所长。我也不是一开始就选了AgentScope，实际比较了LangChain和AutoGen之后才确定。它们的差异大致如下：

LangChain更像一个万能工具包，什么都有，但多Agent协作还需要自己搭很多架子；AutoGen的“两个Agent互聊”非常灵活，但聊天式的编排在工程上难以控制和观测；AgentScope给的是更结构化的模型，执行图、消息模型、分布式这些都设计好了，适合想要稳定工程化的人。

7.2 什么场景下我推荐AgentScope

我的建议很具体：如果你有明确业务流程，比如调研、客服、数据分析，需要多个Agent配合，而且希望这套系统能够长期维护、上线部署，AgentScope的标准化消息和执行图价值很大。如果只是想快速做个研究Demo，或者你的需求高度开放、需要Agent自由发挥，AutoGen这类对话式框架可能更顺手。

另一个参考维度是团队协作。AgentScope因为消息协议统一，团队成员之间分配任务更清晰——A负责写Agent内部逻辑，B负责定义消息格式，C负责编排流程，边界分明。用其他框架时，边界容易模糊，因为你很难把Agent之间的通信和Agent本身的工作分开。

7.3 还能怎么扩展：从Demo到生产的一些延伸

跑通基础Demo后，我在往两个方向扩展。一个方向是给Agent之间加缓存——相同的请求消息直接复用历史结果，省Token也省时间；另一个方向是加评估环节，让一个独立的评价Agent定期抽查总结质量，把质量不达标的流程标记出来。这两个玩法其实都建立在标准化消息的基础上：因为消息结构统一，缓存键和评价样本的提取都很好做。

我个人的体会是，多智能体开发最怕的不是模型不行，而是工程结构混乱。AgentScope把“标准化智能体交互”这件事作为核心目标来做，恰好补上了这个短板。如果你也在多Agent编排上摔过跟头，不妨从一个小Demo开始试试：定义好三个角色，用Pipeline串联，先跑通再优化，很快你就能感受到“按图施工”和“拼字符串调API”之间的巨大差别。最后分享一个小技巧：项目初期就把消息类型定义成一个枚举，统一放在一个模块里，比散落在各处清爽得多，这个习惯会让后续扩展轻松不少。