hello-agents学习笔记--AgentScope框架

AgentScope

如果说 AutoGen 更强调"对话驱动协作"，那么 AgentScope 更强调"工程化的多智能体平台"。它不是单纯让几个智能体轮流聊天，而是把多智能体应用看作一个需要长期运行、可监控、可扩展、可容错的系统来设计。

AgentScope 的核心特点可以概括为：消息驱动、工程化、分布式、多智能体协作 。它适合构建规模更大、交互更复杂、对稳定性要求更高的智能体应用。

AgentScope 的设计

AgentScope 的核心设计思想是 消息驱动架构。在这个框架中，智能体之间的交互不是直接调用函数，而是通过统一的消息对象进行传递。

这和普通程序里的函数调用有明显区别。函数调用通常是"我调用你，然后等你返回结果"；而消息驱动更像是"我发送一条消息，系统负责把消息交给对应智能体"。这种方式让智能体之间更加解耦，也更适合异步、并发和分布式场景。

AgentScope 中的消息通常由 Msg 表示：

python 复制代码

from agentscope.message import Msg

message = Msg(
    name="Alice",
    content="Hello, Bob!",
    role="user",
    metadata={
        "timestamp": "2024-01-15T10:30:00Z",
        "message_type": "text",
        "priority": "normal"
    }
)

这条消息不仅包含文本内容，还包含发送者、角色和元信息。也就是说，AgentScope 把智能体交互过程中的"谁说的、说了什么、以什么身份说、附带什么信息"都标准化了。

这种消息驱动方式带来几个好处：

智能体之间不需要强绑定，降低耦合；
消息可以被记录，方便调试和追踪；
消息可以被路由到本地或远程智能体；
系统天然适合异步执行和并发处理；
复杂任务可以被拆成多个消息流来组织。

AgentScope 的架构也比较工程化。底层有 Message、Memory、Model API、Tool 等基础组件；中间层提供智能体基础设施，比如 ReAct 范式、工具调用、状态管理和异步控制；再往上是多智能体协作层，核心组件包括 MsgHub 和 Pipeline；最上层则是开发和部署相关能力，比如 Runtime 和 Studio。

其中最关键的是 MsgHub。它可以理解为智能体之间的"消息中心"，负责消息路由、广播、组播、持久化和分布式通信。智能体不需要关心对方是在同一个进程里，还是部署在另一台机器上，消息中心会负责处理通信细节。

AgentScope 中的智能体一般基于 AgentBase 实现。开发者主要关注 reply 方法，也就是智能体收到消息后如何回应。

python 复制代码

from agentscope.agents import AgentBase
from agentscope.message import Msg

class CustomAgent(AgentBase):
    def reply(self, x: Msg) -> Msg:
        response = self.model(x.content)
        return Msg(
            name=self.name,
            content=response,
            role="assistant"
        )

    def observe(self, x: Msg) -> None:
        self.memory.add(x)

这里的重点是：reply 负责生成回应，observe 负责观察和记录消息。这样可以把智能体的"思考逻辑"和"通信机制"分开，代码结构更清晰。

三国狼人杀游戏

文档中用"三国狼人杀"来展示 AgentScope 的多智能体能力。这个案例比 AutoGen 的软件开发团队更复杂，因为狼人杀不是简单的顺序流程，而是包含多个玩家、多个阶段、隐藏身份、并发讨论和规则约束的复杂交互场景。

这个案例的价值在于，它展示了 AgentScope 如何处理 复杂角色协作 + 游戏流程控制 + 并发消息交互。

系统大致分成三层：

第一层是游戏控制层，由 ThreeKingdomsWerewolfGame 这类主控制器维护全局状态，例如当前轮次、存活玩家、游戏阶段、胜负判断等。

第二层是智能体交互层，主要由 MsgHub 驱动。狼人私聊、白天公开讨论、预言家查验、女巫行动等，都可以看成不同范围的消息通信。

第三层是角色建模层。每个玩家都是一个智能体，不仅有狼人杀里的游戏身份，比如狼人、预言家、女巫、村民，还叠加了三国人物身份，比如刘备、曹操、张飞、周瑜等。

也就是说，每个智能体同时扮演两种角色：

text 复制代码

游戏身份：狼人 / 预言家 / 女巫 / 村民
人物身份：刘备 / 曹操 / 张飞 / 周瑜 / 司马懿 ...

这让智能体既要遵守游戏规则，又要表现出人物性格。例如，同样是狼人，曹操可能更擅长伪装和谋略，张飞可能更直接冲动。

狼人阶段是 AgentScope 消息驱动设计的典型体现。狼人之间需要秘密讨论击杀目标，这时可以通过 MsgHub 临时建立一个只包含狼人玩家的通信频道。

python 复制代码

async with MsgHub(
    self.werewolves,
    enable_auto_broadcast=True,
    announcement=await self.moderator.announce(
        "狼人们，请讨论今晚的击杀目标。"
    ),
) as werewolves_hub:
    for wolf in self.werewolves:
        await wolf(structured_model=DiscussionModelCN)

这段逻辑不是简单地调用某个"狼人决策函数"，而是创建一个消息环境，让狼人智能体在这个环境中进行讨论。等讨论完成后，再进入投票或决策阶段。

在投票阶段，AgentScope 可以使用 fanout_pipeline 并行向多个智能体发送消息，并收集它们的回复。

python 复制代码

vote_msgs = await fanout_pipeline(
    self.alive_players,
    await self.moderator.announce("请投票选择要淘汰的玩家"),
    structured_model=get_vote_model_cn(self.alive_players),
    enable_gather=False,
)

这比一个个顺序询问玩家更符合真实游戏场景，也体现了 AgentScope 在并发处理上的优势。

另一个重要点是结构化输出。狼人杀这种游戏很依赖规则，如果智能体随意输出自然语言，就很难稳定解析它到底要投谁、是否使用技能、是否达成一致。因此文档中通过 Pydantic 模型约束智能体输出格式。

python 复制代码

class DiscussionModelCN(BaseModel):
    reach_agreement: bool
    confidence_level: int
    key_evidence: Optional[str] = None

这样做的好处是，智能体输出不只是"说了一段话"，而是被约束成可解析、可验证的数据结构。比如投票必须给出目标，女巫行动必须明确是否使用解药或毒药，预言家每晚只能查验一个人。

在复杂多智能体系统中，结构化输出非常重要。它相当于把自然语言行为转化成程序可以稳定处理的对象，降低了 LLM 输出不确定性带来的风险。

输出案例：

text 复制代码

🎮 欢迎来到三国狼人杀！
🎮 开始设置三国狼人杀游戏...

游戏主持人: 📢 【赵云】身份：狼人，夜晚可以击杀一名玩家
游戏主持人: 📢 【诸葛亮】身份：狼人，夜晚可以击杀一名玩家
游戏主持人: 📢 【孙权】身份：预言家，每晚可以查验一名玩家身份
游戏主持人: 📢 【关羽】身份：女巫，拥有解药和毒药各一瓶
游戏主持人: 📢 【刘备】身份：村民，依靠推理和投票
游戏主持人: 📢 【司马懿】身份：村民，依靠推理和投票

游戏主持人: 📢 三国狼人杀游戏开始！
参与者：赵云、诸葛亮、孙权、关羽、刘备、司马懿
✅ 游戏设置完成，共 6 名玩家

🌙 === 第 1 轮游戏开始 ===

游戏主持人: 📢 🌙 第 1 夜降临，天黑请闭眼...
游戏主持人: 📢 🐺 狼人请睁眼，选择今晚要击杀的目标...
游戏主持人: 📢 狼人们，请讨论今晚的击杀目标。

赵云: 吾乃常山赵子龙！依我之见，诸葛亮智谋超群，若不早日除去，恐成心腹大患。今夜不如先取诸葛亮首级，诸位意下如何？

诸葛亮: 哈哈，子龙将军此言差矣。亮虽不才，然若真是狼人，岂会在首夜便引人注目？倒是将军如此急切要除我，莫非另有所图？

赵云: 孔明兄果然能言善辩。不过孙权坐拥江东，势力不可小觑；关云长勇冠三军，也值得考虑。不知诸位有何高见？

诸葛亮: 子龙将军先言诸葛亮，后言孙权、关羽，如此朝三暮四，倒令人疑心。亮以为，今夜若要动手，当选真正威胁全局之人。

游戏主持人: 📢 请选择击杀目标

赵云: 若问子龙本心，仍是那句话：杀人当杀最善辩之人。孔明兄若留到白天，恐怕会牵动全局。

诸葛亮: 关羽关云长，武圣之名威震天下，若在好人阵营，必是核心战力。不如先除此人，以绝后患。

游戏主持人: 📢 🔮 预言家请睁眼，选择要查验的玩家...

孙权: 我乃江东孙权，今晚先查验一人，以辨忠奸。

游戏主持人: 📢 查验结果：诸葛亮是狼人

游戏主持人: 📢 🧙‍♀️ 女巫请睁眼...
游戏主持人: 📢 今晚诸葛亮被狼人击杀

关羽: 作为女巫，我需要判断是否使用解药救下诸葛亮。

AgentScope 的优势与局限性分析

AgentScope 最大的优势是工程化能力强。它不是只解决"几个智能体怎么聊天"的问题，而是更关注多智能体系统在真实应用中的运行方式：消息如何传递，状态如何保存，异常如何处理，多个智能体如何并发执行，系统如何监控和部署。

它特别适合以下场景：

多智能体数量较多；
智能体之间交互关系复杂；
需要异步或并发处理；
需要消息记录和可观测性；
需要分布式部署；
需要较强容错能力；
任务不是简单线性流程，而是复杂状态变化。

"三国狼人杀"案例很好地体现了这一点。游戏中有公开讨论、私密通信、投票、查验、救人、击杀等多个交互模式。用传统状态机写会比较复杂，而 AgentScope 可以把这些流程转化为不同范围、不同规则的消息传递。

不过，AgentScope 的缺点也比较明显：它的工程化能力越强，学习成本也越高。开发者需要理解消息驱动、异步编程、结构化输出、分布式通信等概念。对于一个简单的双智能体对话任务，使用 AgentScope 可能会显得有些"重"。

因此，AgentScope 更适合构建偏生产级、复杂度较高的多智能体系统。如果只是快速做一个小 Demo，或者只是让几个智能体轮流讨论，可能 AutoGen 这种更轻量的对话式框架会更直接。

总结来说，AgentScope 的关键词不是"聊天"，而是"系统"。它把多智能体应用看成一个工程系统来搭建：消息是交互基础，MsgHub 是通信中枢，Pipeline 负责编排流程，结构化输出保证规则稳定，异步和分布式能力支撑复杂应用运行。

一句话概括：

AgentScope 适合把多智能体应用从 Demo 推向更复杂、更稳定、更工程化的系统。