把 AgentScope 当作"另一个 LangChain"或者"AutoGen 的中国版"是非常常见的误解——这两种类比都会让你错过它真正的设计取向。AgentScope 是阿里通义实验室 SysML 团队的项目，2024 年 2 月发了 arXiv 论文 AgentScope: A Flexible yet Robust Multi-Agent Platform（2402.14034）以"Multi-Agent first"立项，2025 年 8 月做了一次实质上不向后兼容的 API 重构——官方 release notes 没有用 “rewrite” 这种措辞，只称为 major update / developer-centric，但事实层面：包名空间从 modelscope/agentscope 迁到 agentscope-ai/agentscope、删除 RPC / distributed / RpcAgent 整条路径、ReActAgent 构造签名换掉（旧 service_toolkit / model_config_name → 新 toolkit / model / formatter），代码不动迁移到新版几乎无可能。新框架的核心是 v1.0 论文 AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications（arXiv 2508.16279）所表述的：

we ground agent behaviors in the ReAct paradigm and offer advanced agent-level infrastructure based on a systematic asynchronous design.

这种"愿意删掉自己最大差异化卖点"的取向，在开源框架里非常少见，背后对应的外部条件是 A2A 协议的标准化、AutoGen v0.4 把 actor 推上了 runtime 层、MAF 把 actor 内嵌到 .NET 与 Python 的运行时里——自研 RPC 在 2025 年下半年已经不再是优势。理解这个转向，才能理解 AgentScope 今天的设计：单 agent 是一个 async ReAct 循环、多 agent 是显式 MsgHub 广播、记忆显式分两层、追踪与评测被提到与 agent 同级、训练（Trinity-RFT）也被纳入框架视野。

本文以 AgentScope 1.x 为主轴，覆盖 Python 智能体框架在 design space 里的定位、AgentScope v0 → v1 的范式翻转、核心抽象 ReActAgent / MsgHub 的实际形态，以及它与 LangGraph / CrewAI / MAF / AG2 的对位关系。Java 阵营（Spring AI / LangChain4j）不在本文范围，单独成文 《Spring AI 深度：把 LLM 抽象成新一代 JDBC》；具体上手实战见 《AgentScope 上手教程：从空仓库到 Multi-Agent 工单系统》。

AgentScope ReAct 与 MsgHub 架构图

一、命名先去重：四个被混为一谈的实体

智能体框架领域名字混乱程度仅次于"Hermes"（参见本博 《谁在记住你：Hermes、OpenClaw、Claude Code 等主流智能体的记忆架构深度横评》）。讨论之前先把以下四个易混实体的所指锁死：

名字 是什么 与本文的关系
AgentScope agentscope-ai/agentscope（旧地址 modelscope/agentscope，仍有重定向），阿里通义实验室 SysML 团队 本文研究对象
AgentScope v0.x 原仓库 modelscope/agentscope 的早期版本，主打 actor-based distributed framework 已被 v1.0 整体重写替代
AgentScope Studio AgentScope 配套的可视化追踪 UI，内置 OTel exporter 本文 § 九 讨论
Trinity-RFT AgentScope 维护的 agentic RL 调优框架，与主框架同源 本文 § 七 讨论

[PATTERN] 处理 agent 框架命名漂移：写作和阅读时凡是涉及"AgentScope"、“AutoGen”、"Spring AI"这类高歧义名词，第一件事是声明本文采用的具体仓库 URL 与版本号。半年前"AgentScope"指 v0.x 的 actor-based 框架，今天指 v1.x 的 ReAct + MsgHub——同一个名字背后是完全不同的代码。

本文用到的版本（2026-05 截至日）：

  • AgentScope 1.0.20（PyPI 2026-05-15），v1.0 论文 arXiv 2508.16279
  • 配套生态版本：LangGraph 1.2.0 / CrewAI 1.14.4 / Microsoft Agent Framework .NET 1.0.0（2026-04-02 GA）/ AG2 0.12.3，作为本文 § 六 对位

二、Python agent 框架的两轴 design space

讨论 Python 智能体框架最容易陷入"逐项打勾"的对比表——支持哪些 provider、有没有 RAG、能不能 streaming——这种比法在 2024 年还有意义，今天所有主流项目在这些维度都打勾，差异只剩两个轴。

第一轴：抽象密度。框架对 agent 行为做了多少预设？

  • 低密度（SDK 路线）：只提供 model client、tool calling、memory、RAG 这些"积木"，不规定 agent 的行为模式。开发者自己拼。这一档在 Python 里以 openai-agents、anthropic SDK 直接使用为代表。
  • 中密度（pattern 路线）：给出几种典型 workflow 模板（Sequential / Parallel / Routing / Orchestrator-Workers），开发者按模板填空。CrewAI 的 Crew 模式属于这一档。
  • 高密度（runtime 路线）：直接定义 agent 之间的通信范式与状态机——actor 模型、graph 模型、role-task 模型。AgentScope、AutoGen v0.4 / MAF、LangGraph 都在这一档。

第二轴：运行模型。agent 怎么执行？

  • 同步阻塞 + 显式编排：开发者在主循环里调 agent.run(...)，每一步等返回。Python 圈很少见，因为生态本身就是 async 友好的。
  • 协程异步 + 消息驱动：所有 agent 是 async def，靠消息传递触发行动。AgentScope v1.x、AutoGen v0.4 / MAF 是典范。
  • 状态图 + checkpoint 持久化：agent 行为被建模为 graph node，每一步落 checkpoint，可以中断、回溯、time-travel。LangGraph 是这条路上的标杆。

把这两个轴交叉，得到的二维空间能解释 Python 智能体框架的真实分裂：

1
2
3
4
5
6
7
8
9
10
抽象密度 ↑
高 │  AgentScope v1.x        LangGraph
   │  AutoGen v0.4 / MAF     CrewAI
   │
中 │  CrewAI Flows
   │
低 │  openai-agents SDK
   │  anthropic SDK
   └─────────────────────────────────────────→ 运行模型
        同步阻塞              协程异步         状态图

AgentScope 与 LangGraph 都在右上区，但它们解决同一道题的方式截然不同——AgentScope 把 agent 行为建模为"agent 之间发消息"，消息是一等公民；LangGraph 把 agent 行为建模为"状态在节点间流动"，状态是一等公民。前者天然适合开放式协作和长程异步任务，后者天然适合需要 audit / replay / time-travel 的可审计场景。这是 § 六会展开的对位。

[PATTERN] 选择 agent 框架的两个先验问题：在比较任何具体功能之前先回答两件事——（1）你想让框架替你决定 agent 行为模式吗？（2）你的 agent 跑在长程任务还是单次会话里？两个答案合起来基本就唯一确定了你应该选哪一档。

三、AgentScope：从 actor 到 ReAct 的范式翻转

AgentScope 在 2025 年最重要的事件不是新版本发布，是 v1.0 实质性 API 重构——一次官方未称为 “rewrite”、但代码层面无法平滑迁移的架构哲学翻转。理解这个翻转才能理解它今天的设计。

v0.x 的卖点：actor-based 多机分布式

最初的 AgentScope（arXiv 2402.14034，2024-02）以 Multi-Agent first 为核心论调。最显眼的差异化贡献是 actor-based distributed framework——自研 gRPC 的 RpcAgent、placeholder/future 模式让"本地代码自动转分布式"，多个 agent 可以分布在不同进程或不同机器上协作。原 README 强调：“Native Distribution / Parallelization: Centralized programming for distributed application.”

这条路线在 2024 年的多智能体研究里很有市场——LLM agent 的协作需要并发，actor 模型理论上完美匹配。

v1.x 的转向：删掉自研 actor，全面 async-ReAct

打开 agentscope-ai/agentscope 当前 main 分支的 src/agentscope/，子模块是这样：

1
2
3
_utils, a2a, agent, embedding, evaluate, exception, formatter, hooks,
mcp, memory, message, model, module, pipeline, plan, rag, realtime,
session, token, tool, tracing, tts, tune, tuner, types

rpc 模块没了，distributed 没了，RpcAgent 类没了。旧仓库 modelscope/agentscope v0.x 下的 pip install -e .[distribute] extras 与 agent.to_dist() 整套机制（底层是 RpcAgent + gRPC，把 Agent 转成独立进程/远端执行）在新 main 分支整体不存在。这条路径被 a2a + Nacos 注册中心承担的标准协议化跨进程协作替代。

新 README 的开篇第一句也不再是"多 agent 优先"，而是：

We design for increasingly agentic LLMs. Our approach leverages the models’ reasoning and tool use abilities rather than constraining them with strict prompts and opinionated orchestrations.

v1.0 论文（arXiv 2508.16279）摘要写得更直接：

we ground agent behaviors in the ReAct paradigm and offer advanced agent-level infrastructure based on a systematic asynchronous design

这是官方承认的范式转移。新核心是 ReActAgentBase → ReActAgent，全 async。多 agent 协作降级到工作流层（MsgHub + sequential_pipeline + fanout_pipeline），分布式从"自研 actor"换成"标准化协议"——A2AAgent 类继承自 AgentBase，本质是用 httpx 调远端 agent card 的客户端。

[PATTERN] 当一个研究型框架愿意删掉自己最大的差异化卖点：通常是因为这个差异化卖点在生态里失去了独占性。AgentScope 砍掉自研 actor 这件事，对应的外部条件是 A2A 协议的标准化、AutoGen v0.4 把 actor 推上了 runtime 层、MAF 把 actor 内嵌到了 .NET 与 Python 的运行时里——自研 RPC 在 2025 年下半年已经不再是优势。

四、模块鸟瞰图：v1.x 的实际形态

把 v1.x 的顶层模块按依赖方向画一遍，能看到 v1.0 论文那句"agent-level infrastructure based on a systematic asynchronous design"在代码上落到了什么位置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
┌─────────────────────────────────────────────────────────────┐
│  应用层（Python async 代码）                                 │
│  asyncio.run(main()) / FastAPI 端点 / Studio 调试            │
└──────────────────────────┬──────────────────────────────────┘
                           │ await agent(msg) / async with MsgHub
┌──────────────────────────▼──────────────────────────────────┐
│  多 Agent 工作流（pipeline + a2a 模块）                      │
│  MsgHub                                                      │
│   ├─ sequential_pipeline（串行 turn-taking）                 │
│   ├─ fanout_pipeline（同消息广播给多 agent，再聚合）         │
│   ├─ broadcast / add / delete（动态调整成员）                │
│   └─ A2AAgent（httpx 调远端 agent card，标准协议替代旧 RPC） │
└──────────────────────────┬──────────────────────────────────┘
                           │ Msg 显式消息对象
┌──────────────────────────▼──────────────────────────────────┐
│  单 Agent 抽象（agent 模块）                                 │
│  AgentBase → ReActAgentBase → ReActAgent                     │
│  ┌──────────────────────────────────────────────┐           │
│  │ async ReAct loop:                            │           │
│  │   reasoning → tool_call → observation → ... │           │
│  │ 提供 pre_reply / post_reply hook 扩展点      │           │
│  └─────┬───────────────┬──────────┬─────────────┘           │
└────────┼───────────────┼──────────┼─────────────────────────┘
         │               │          │
         ▼               ▼          ▼
   ┌──────────┐    ┌──────────┐  ┌─────────────────────────┐
   │ Memory   │    │ Tool     │  │ Model                   │
   │ 双层     │    │ Toolkit  │  │ ChatModel /             │
   │          │    │ + 函数式 │  │ TrinityChatModel（RL）  │
   │ working: │    │ 注册     │  └────────────┬────────────┘
   │  InMem / │    └──────────┘               │
   │  Redis / │                               ▼
   │  AsyncSQL│              ┌──────────────────────────────┐
   │  /Tablestr│              │ DashScope / OpenAI /        │
   │          │              │ Anthropic / 本地 vLLM       │
   │ longterm:│              └──────────────────────────────┘
   │  Mem0 /  │
   │  ReMe-Personal/Task/Tool
   └──────────┘

横切模块（贯穿全栈，被任意层调用）：
  formatter（输入/输出格式化）· token（tokenizer + 计数）
  embedding（向量化） · session（会话上下文）
  evaluate（任务评测） · realtime（实时多模态）
  tracing（OTel → AgentScope Studio UI）

这张图重点看四个变化：

  1. rpc / distributed 模块整体不见了，被替换成应用层调用的 a2a 标准协议——多机分布式的认知负担从框架内收回到协议侧
  2. ReActAgent 是单 agent 唯一推荐基类，所有"自主行为"都是这个 ReAct 循环的实例化
  3. 工作记忆与长期记忆是两个独立顶层模块，不是同一个接口的不同实现，与 Spring AI 把 ChatMemory 当一等公民、把长期记忆留给 VectorStore 自拼的做法形成对照
  4. tracing 和 evaluate 被提到与 agent 同级的位置，体现了 SysML 团队"研究到生产之间要可观测可评测"的取向

不止一个仓库：核心框架 + Runtime + Studio 三层架构

AgentScope 1.0 论文摘要里有一句话经常被忽略：we offer … a runtime sandbox, a scalable evaluation module paired with a visual studio interface。落到生态层面，AgentScope 实际由三个独立仓库 + 一个评估模块构成：

层 仓库 角色
核心框架 agentscope-ai/agentscope ReActAgent / MsgHub / Toolkit / Memory，本文主体讨论对象
Runtime agentscope-ai/agentscope-runtime Agent 的沙盒部署运行时，支持 Docker / K8s 部署，提供资源隔离
Studio agentscope-ai/agentscope-studio OpenTelemetry 追踪 / 调试 UI
评估 agentscope.evaluate（包内） 可扩展的任务评测，与 agent 同级模块

关键事实是 Runtime 与 Studio 可以独立使用，并兼容 LangGraph / AutoGen 的 agent。这是 AgentScope 与 LangChain Inc. 的 LangSmith 最直接对位的卖点——LangSmith 是 LangGraph 配套的私有 SaaS 追踪平台，AgentScope Studio 是开源的、协议化的（OTel）、与框架解耦的。

[PATTERN] 框架与配套工具的耦合度决定了生态开放性：LangSmith 与 LangGraph 是事实绑定（核心特性需要 LangSmith API key），生态是封闭的；AgentScope Studio 与核心框架是松耦合（OTel 协议），生态是开放的。这种取向差异不是技术决定，是产品策略决定。

五、核心抽象：ReActAgent + MsgHub

AgentScope v1.x 的核心是单 agent 的 ReAct 循环加多 agent 的"群组对话"工作流，而不是状态机或 role-task 模板。

单 agent：ReActAgent 的 async 循环

ReActAgent 的最小实例化非常直接：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from agentscope.agent import ReActAgent
from agentscope.formatter import OpenAIChatFormatter
from agentscope.message import Msg
from agentscope.model import OpenAIChatModel
from agentscope.tool import Toolkit

agent = ReActAgent(
    name="assistant",
    sys_prompt="你是一个有用的助手。",
    model=OpenAIChatModel(...),
    formatter=OpenAIChatFormatter(),
    toolkit=Toolkit(),  # 已注册若干工具
    max_iters=8,        # ReAct 循环最大迭代
)

reply = await agent(Msg(name="user", role="user", content="今天天气怎么样？"))

但 1.x 的 ReActAgent 真实构造签名远不止六参数——v1.0 论文里"agent-level infrastructure"那句话落到 API 上是16 个可选参数。完整签名（来自 src/agentscope/agent/_react_agent.py）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
ReActAgent(
    name: str,
    sys_prompt: str,
    model: ChatModelBase,
    formatter: FormatterBase,
    toolkit: Toolkit | None = None,
    memory: MemoryBase | None = None,           # 工作记忆（默认 InMemoryMemory）
    long_term_memory: LongTermMemoryBase | None = None,
    long_term_memory_mode: Literal["both", "agent_control", "static_control"] = "both",
    enable_meta_tool: bool = False,             # 让 agent 自己 reset_equipped_tools
    parallel_tool_calls: bool = False,          # 一次返回多 tool_call 时并行执行
    knowledge: list[KnowledgeBase] | None = None,  # RAG 接入点
    enable_rewrite_query: bool = True,          # 调用前先让模型重写 query 提升召回
    plan_notebook: PlanNotebook | None = None,  # 让 ReAct 进入"先规划后执行"
    print_hint_msg: bool = False,
    max_iters: int = 10,
    tts_model: TTSModelBase | None = None,      # 语音输出
    compression_config: CompressionConfig | None = None,  # 上下文超长压缩
)

读这张签名表的关键不是"参数都有什么"，而是看清每个参数对应一个独立的设计取向：

  • long_term_memory_mode：三档语义。both 是 agent 与系统都可读写；agent_control 是只有 agent 主动调读写工具；static_control 是系统帮忙写、agent 不知情。这三档把"agent 是否意识到自己有长期记忆"做成了显式可调
  • enable_meta_tool=True：启用 reset_equipped_tools 这个 meta-tool，让 agent 在运行时自己决定"我下一步要换一组工具"。这是 AgentScope 对"工具集太大装不进 prompt"的非检索路线回答
  • parallel_tool_calls=True：模型一次返回多个 tool_call 时并行执行而不是串行——对 GPT-4o / Claude Sonnet 这种支持 parallel function calling 的模型有意义
  • enable_rewrite_query=True + knowledge：把 RAG 整合进 ReAct 循环。每次推理前先让模型重写 query 提升 retrieval 召回——与 Spring AI 的 RewriteQueryTransformer 是同一种思路
  • plan_notebook=PlanNotebook(...)：把 ReActAgent 升格为 Meta-Planner Agent。先 plan 出多步任务清单，再 execute；plan_notebook 维护 plan 状态
  • compression_config：上下文超长时自动压缩（典型策略是滚动总结历史轮次）。这个参数让 agent 能跑长程任务而不爆 context

[PATTERN] 16 个可选参数的设计含义：每个参数都对应一种"先验决定" vs “运行时决定"的切分。enable_meta_tool 把工具集决定权交给 agent，enable_rewrite_query 把 query 改写交给 agent，parallel_tool_calls 把执行顺序交给 agent。一个框架愿意把多少决定让给 agent，等同于它对模型能力的信任程度——AgentScope v1.x 的取向是"信任度尽可能高”，与 v1.0 论文 “leverages the models’ reasoning and tool use abilities rather than constraining them” 完全对齐。

关键是全 async——agent() 是 awaitable。ReAct 循环内部展开是：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
循环开始：
  pre_reply hook（可在此读 long-term memory / 调 RAG）
   ↓
  reasoning（LLM 推理）
   ↓
  如果 LLM 决定调工具：
    tool_call → toolkit dispatch → observation
    回到 reasoning
  如果 LLM 决定结束：
    跳出循环
   ↓
  post_reply hook（可在此写 long-term memory / 落 trace）
   ↓
  emit Msg

pre_reply / post_reply 是 AgentScope 把"非循环本身的工程关切"挂进系统的扩展点——长期记忆的读写、自蒸馏 skill、外部 RAG 查询，都通过 hook 加挂而不是修改 ReActAgent 本身。这也是 § 八 会讨论"在 AgentScope 上长出 Hermes 等价物"的关键——hook 就是为这种扩展设计的。

多 agent：MsgHub + pipeline 的群组对话

一段实际可运行的多 agent 群聊代码：

1
2
3
4
5
6
7
8
9
10
11
12
from agentscope.agent import ReActAgent
from agentscope.pipeline import MsgHub, sequential_pipeline
from agentscope.message import Msg

async with MsgHub(
    participants=[agent1, agent2, agent3],
    announcement=Msg("Host", "Introduce yourselves.", "assistant"),
) as hub:
    await sequential_pipeline([agent1, agent2, agent3])
    hub.add(agent4)
    hub.delete(agent3)
    await hub.broadcast(Msg("Host", "Goodbye!", "assistant"))

这段代码的特点是全 async、显式消息对象 Msg、显式订阅广播、无隐式状态机。和 LangGraph 的 StateGraph、CrewAI 的 Crew(role, goal, task)、AutoGen 的 GroupChatManager 是三种完全不同的多 agent 心智模型。

消息流：MsgHub 内部的运行时行为

上面那段 8 行的 MsgHub demo 看起来很简单，但每一句都对应 runtime 一组具体的消息广播动作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
   agent1                  agent2                  agent3            (动态加入) agent4
     │                       │                       │                              
     ├── async with MsgHub(participants=[1,2,3], announcement) ─┐                  
     │                       │                       │          │                  
     │ ◀── broadcast announcement to all participants ─────────┤                   
     │                       │                       │          │                  
     ├── await sequential_pipeline([agent1, agent2, agent3]) ───┤                  
     │                       │                       │          │                  
     │  reply ──▶ │                                              │                  
     │            │  reply ──▶ │                                 │                  
     │            │            │  reply ──▶ (累积消息广播给全员)  │                  
     │            │            │                                 │                  
     ├── hub.add(agent4)   ── 后续广播会包含 agent4 ─────────────│                  
     │            │            │                                 │                  
     ├── hub.delete(agent3) ── agent3 退出 hub，不再收到广播      │                  
     │            │            ◇                                 │                  
     │            │                                              │                  
     ├── await hub.broadcast(Msg("Host","Goodbye!")) ────────────┤                  
     │            │                                              │                  
     │ ◀── ── ── ── ── ── ── 同步广播到剩余成员 ── ── ── ── ── ──▶│                  

每个 agent 内部展开（每次 reply 触发一次完整 ReAct 循环）：
   ┌────────────────────────────────────────────────────────┐
   │  pre_reply hook（可在此读 long-term memory / 调 RAG）  │
   │   ↓                                                    │
   │  ReAct loop（async）:                                  │
   │    reasoning（LLM）                                    │
   │     → tool_call（Toolkit dispatch）                    │
   │     → observation                                      │
   │     → reasoning ...                                    │
   │    （直到模型输出 finish 或 max_iters）                │
   │   ↓                                                    │
   │  post_reply hook（可在此写 long-term memory / 落 trace）│
   │   ↓                                                    │
   │  emit Msg → MsgHub                                     │
   └────────────────────────────────────────────────────────┘

这张图想说明的是 AgentScope 的多 agent 行为有两层时间尺度：外层是 MsgHub 调度的 turn-taking（粗粒度，事件驱动），内层是单个 agent 的 ReAct 循环（细粒度，async 协程）。两层耦合的关键点是 pre_reply / post_reply 两个 hook，它们正是把记忆 / 追踪 / 自蒸馏这类跨循环的副作用挂进系统的位置。

Hooks 系统：跨循环副作用的挂载点

AgentScope 的 hooks 是 agentscope.hooks 模块提供的横切扩展机制。pre_reply 与 post_reply 只是其中最常用的两个；完整的 hook 切入点覆盖了 ReAct 循环的多个时刻：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
ReAct 循环时序，从外到内五层 hook 切入点：

  pre_reply hook          ← 进入 reply() 之前。读 long-term memory、
   ↓                        从外部 RAG 拉相关上下文、注入 user model
  ┌─────────────────────────────────────────┐
  │ ReAct loop iteration:                   │
  │                                          │
  │  pre_reasoning hook   ← 推理前。可在此    │
  │   ↓                     注入提示词修饰    │
  │   reasoning (LLM call)                  │
  │  post_reasoning hook  ← 推理后。看到        │
  │   ↓                     reasoning content │
  │                                          │
  │   if tool_call:                         │
  │     pre_tool hook     ← 调工具前。审计、  │
  │      ↓                  rate limit、缓存 │
  │      Toolkit.dispatch                   │
  │     post_tool hook    ← 调工具后。脱敏、  │
  │      ↓                  trace metric    │
  │     observation                         │
  │   else: break                           │
  └─────────────────────────────────────────┘
   ↓
  post_reply hook         ← 退出 reply()。写 long-term memory、
                            自蒸馏 skill 文档、落 trace、统计 token

每个 hook 的实际签名是一个 async def 协程，接收 agent 实例与当前消息/状态，可以修改可以观察。一个典型的"自动写长期记忆"扩展：

1
2
3
4
5
6
7
8
9
10
from agentscope.hooks import register_post_reply_hook
from agentscope.memory import ReMePersonalLongTermMemory

ltm = ReMePersonalLongTermMemory(user_id="alice")

@register_post_reply_hook
async def remember_facts(agent, reply_msg, *, context):
    # context 含有 user input / tool calls / iterations 等元数据
    if context.iteration_count > 1 and "user_preference" in reply_msg.content:
        await ltm.add(reply_msg.content, metadata={"agent": agent.name})

这种 hook 注册不修改 ReActAgent 源代码、不继承新类、不破坏单元测试——它是 AgentScope 区别于 LangGraph 的另一处工程取向：LangGraph 的扩展靠"在 graph 里加 node"，AgentScope 的扩展靠"在 ReAct 循环里加 hook"。前者把扩展当作流程节点（侵入主流程），后者把扩展当作横切关注（不污染主流程）。两种模型各有取舍——graph 模型让扩展可视化、可 replay，hook 模型让扩展不影响 agent 的"看起来在做什么"。

[PATTERN] hooks 不是 Python 装饰器糖：很多框架的 “hooks” 只是装饰器语法糖，本质是同步回调。AgentScope 的 hooks 是 async-first 的——这意味着 hook 内部可以 await ltm.add(...)、await rag.query(...) 而不阻塞 ReAct 循环主线程。这种 async 一等公民的设计让 hooks 可以在 hook 里做远程 IO 而不必担心回调地狱，与 v1.0 论文 “systematic asynchronous design” 完全对齐。

Realtime 模块：多模态实时交互的并行路径

AgentScope 1.x 顶层模块除了上面讨论的 agent / pipeline / a2a / memory / tool 之外，还有一个常被忽略的 realtime 模块——agentscope-ai/agentscope/src/agentscope/realtime/ 提供 RealtimeAgent，与 ReActAgent 是平级的两条路径：

维度 ReActAgent RealtimeAgent
模态 文本（含工具调用） 语音 / 视频流
交互模型 turn-taking（一来一回） streaming（持续双向）
底层模型 通用 ChatModel OpenAI Realtime API / Qwen-Omni 等支持流式多模态的模型
主要场景 应用场景的多 agent 协作 实时语音助手、客服坐席、播报式 agent
是否进 ReAct 循环 是 否——是连续 streaming 上的事件流

RealtimeAgent 的存在意义是：当 LLM 本身从 turn-based 升级到 streaming-based 时，agent 抽象不再适合用 ReAct 循环建模。ReAct 循环的时间粒度是"一次完整推理"，而 streaming 模型的时间粒度是"每个 audio chunk"——两者差了三个数量级。AgentScope 把它们建模为两条并列路径而不是同一条，避免了把 streaming 强行塞进 ReAct 循环的设计扭曲。

这种"为不同时间尺度建立独立抽象"的取向与 LangGraph 的取向不同——LangGraph 把所有 agent 行为都建模为 StateGraph 节点，streaming 与 turn-taking 共用同一个 checkpointer 接口。AgentScope 的拆分更工程化，LangGraph 的统一更概念化。哪种更好取决于你的产品形态——做实时语音 agent 的团队会感谢 AgentScope 的拆分。

Memory 的两层设计

工作记忆与长期记忆显式分层：

  • 工作记忆：MemoryBase, InMemoryMemory, RedisMemory, AsyncSQLAlchemyMemory, TablestoreMemory
  • 长期记忆：LongTermMemoryBase, ReMePersonalLongTermMemory, ReMeTaskLongTermMemory, ReMeToolLongTermMemory, Mem0LongTermMemory

这是把"对话短期上下文"和"agent 跨会话经验"两件事彻底拆开。Spring AI 的 ChatMemory 只解决前者，长期记忆要自己拼 VectorStore。AgentScope 长期记忆主推 ReMe（仓库 agentscope-ai/ReMe，原 modelscope/MemoryScope，2026-04 已加入 OceanBase / seekdb 向量后端），分成 Personal（用户偏好）/ Task（任务历史）/ Tool（工具使用经验）三个独立子系统；Mem0LongTermMemory 是对外部项目 mem0.ai 的集成，并列存在但不是 first-party 路线。

这种"按用途切分而不是按存储介质切分"的拆法，是 AgentScope 与 LangGraph 在记忆设计上的根本差异——LangGraph 的 checkpointer 是"按存储介质切分"（InMemory / Sqlite / Postgres），所有状态走同一个接口；AgentScope 是"按语义切分"，工作记忆与长期记忆是两个 API surface。

[PATTERN] 记忆按语义切分 vs 按介质切分：哪种好取决于你的 agent 形态。如果你的 agent 是单次会话型（编程助手、客服 bot），按介质切分更简洁；如果是长程自主型（个人 AI 助理、研究助手），按语义切分更符合记忆的本性——工作记忆需要被频繁刷写，长期记忆需要被去重和泛化，两件事的访问模式完全不一样，强行用一个接口反而是阻力。

三个内置高级 agent：ReAct 之上的具体化

虽然 AgentScope 不提供多 agent 协作模板，但它在单 agent 层提供了三个内置高级 agent——这是 v1.x 区别于 v0.x 的另一处明显投资：

  • Browser-Use Agent：内置浏览器操作工具集，支持网页导航、表单填写、内容抓取
  • DeepResearch Agent：内置研究循环（搜索 → 阅读 → 总结 → 追问），与 OpenAI Deep Research / Anthropic Research 模式同源
  • Meta-Planner Agent：把"规划 + 执行"做成单 agent 内的两阶段循环，先 plan 再 execute，内置 plan_notebook 抽象

阿里在 AgentScope 之外还开源了两个相关 agent：Alias-Agent（任务规划，可在 ReAct / Planner-Executor / DeepResearch / Browser-Use 四模式动态切换）、Data-JuicerAgent（多智能体 + 数据处理算子）。这些 agent 都是 ReActAgent 的继承或装配产物，验证了"ReAct + toolkit + sys_prompt 三件套"足以承担相当复杂的 agent 行为。

Toolkit 的两个高级特性：preset_kwargs 与 meta_tool

Toolkit 的两个常被忽略的特性显著影响生产可用性：

register_tool_function(fn, preset_kwargs={...}) 预置参数：把 API key、DB 连接串这类敏感参数预先绑定到工具上，agent 看到的是 fn(query)，框架在调用时自动补 api_key="sk-..."。这避免了把敏感参数暴露在 prompt 里，也避免了让 agent 学会"我应该传哪个 key"。

1
2
3
4
5
6
toolkit.register_tool_function(
    query_database,
    preset_kwargs={"connection_string": os.environ["DB_URL"]},
)
# agent 看到的工具签名是 query_database(sql: str)，
# connection_string 在 schema 里被隐藏，框架运行时自动注入

enable_meta_tool=True + group-wise tools management：把 toolkit 内的工具按 group 组织，reset_equipped_tools() 这个 meta-tool 让 agent 可以在运行时自己决定启用哪些工具组。对应的 ReActAgent 构造参数 enable_meta_tool=True 启用此能力。

这是 AgentScope 对"工具集太大装不进 prompt"问题的回答——不是更激进的工具检索（LangChain 的 Tool retriever），而是让 agent 学会自己管理工具集。前者是机器学习路线，后者是软件工程路线，两条路都有效但出发点不同。

设计哲学：别和 LLM 顶牛

v1.0 论文里的 developer-centric 加了一层意思：别用强 prompt 和强 orchestration 把模型框死。这是对 AutoGen 的 GroupChatManager、LangGraph 的 StateGraph 那种"框架强加流程"的隐性批评。AgentScope 的多 agent 是 ad-hoc 工作流（MsgHub + sequential_pipeline + fanout_pipeline），不是状态机也不是 role hierarchy。

代价是：AgentScope 几乎没有提供"开箱即用的多 agent 协作模板"，需要开发者自己组装协作逻辑。这与 CrewAI 给你 role / goal / backstory 三元组就能起项目的体验完全相反。

六、AgentScope 在 design space 的位置：与 LangGraph / CrewAI / MAF 对位

把 AgentScope 与 Python 圈其他三个高密度 runtime 派框架对位，差异更清晰：

vs LangGraph：消息驱动 vs 状态图

LangGraph 是 LangChain Inc. 自家的 agent runtime，README 直接点名灵感来源是 Pregel 与 Apache Beam，公开 API 模仿 NetworkX。核心抽象是 StateGraph(State)：State 是 TypedDict / dataclass / pydantic.BaseModel，每个 key 可以单独配 reducer；add_node / add_edge / add_conditional_edges 加节点和边；.compile(checkpointer=...) 后得到带 checkpointing 的可执行图。

LangGraph 的杀手锏是持久化层：BaseCheckpointSaver 接口 + InMemorySaver / SqliteSaver / PostgresSaver / CosmosDBSaver 多种实现；thread_id 唯一标识一个会话的全部状态；time-travel 让你传特定 checkpoint_id 调用，前面的步骤跳过、后续节点重跑；update_state(...) 写新 checkpoint 而不是原地修改；interrupt() + HumanInterrupt / HumanResponse 实现 human-in-the-loop。

把 StateGraph 的核心运行时画出来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 class State(TypedDict):
     messages: Annotated[list[Msg], operator.add]   # reducer 自动 append
     counter: int                                    # 默认 last-write-wins

                        ┌──── START ────┐
                        ▼                │
                ┌───────────────┐        │
                │ node: classify│        │  super-step：
                └───────┬───────┘        │  add_conditional_edges
              ┌─────────┼─────────┐      │  自动并行分支
              ▼         ▼         ▼      │
          ┌───────┐ ┌───────┐ ┌───────┐  │
          │route_a│ │route_b│ │route_c│  │  三条路径在 Pregel
          └───┬───┘ └───┬───┘ └───┬───┘  │  super-step 内并发，
              └────┬────┴─────────┘       │  下一 step 收敛
                   ▼                      │
               ┌─────────┐                │
               │aggregate│ ◀── update_state(as_node="aggregate")
               └────┬────┘                │   写新 checkpoint，
                    │                      │   不原地修改
                    ▼                      │
              ┌──────────────┐ interrupt() ─▶ HumanInterrupt
              │ human_review │ ◀── HumanResponse
              └────┬─────────┘
                   ▼
                  END

每经过一个节点：
  └─ checkpointer.put(thread_id, checkpoint_id, state)
     ├─ InMemorySaver / SqliteSaver
     ├─ PostgresSaver
     └─ CosmosDBSaver
time-travel：传特定 checkpoint_id 调用，前置节点跳过、后续节点重跑

[PATTERN] 状态图 vs 消息驱动：LangGraph 与 AgentScope v1.x 的根本差异在心智模型——LangGraph 把 agent 行为建模为"状态在节点间流动"，状态是一等公民；AgentScope 把 agent 行为建模为"agent 之间发消息"，消息是一等公民。前者天然适合需要 audit / replay / time-travel 的场景，后者天然适合开放式协作。这种差异不是哪种"更好"——是问题决定路线。

LangChain 1.x 也做了平行的范式翻转

值得在这里记一笔的是：LangChain 在 2026 年也做了一次与 AgentScope v0→v1 同等量级的范式翻转——LangChain 1.x 把 Chain → Agent 作为核心抽象，Agent 默认基于 LangGraph 构建，不再独立提供 chain runtime。langchain.chains 路径下的核心抽象进维护态，langchain.agents 直接转交给 LangGraph。生态层 deepagents 0.6.x 进一步在 LangGraph 之上叠了 plan-tool + sub-agents + mock filesystem，做出类似 Claude Code / Manus 风格的高层 agent。

把 AgentScope 与 LangChain 这两次翻转放在一起看，2025-2026 年 Python agent 框架发生的真实事件是：所有主要框架都在删除自己的旧抽象、向 ReAct + 工具循环靠拢。AgentScope 删的是 actor-based distributed，LangChain 删的是 Chain-based composition，两者删掉的都是"框架预设流程"，留下的都是"agent 自己决定流程 + 框架提供基础设施"。

这种集体翻转的外部条件很简单——LLM 工具调用能力在 2024-2025 期间提升了一个数量级。当模型自己能可靠地决定下一步调什么工具，框架预设流程不再是助力反而是阻力。AgentScope v1.0 论文里那句 “leverages the models’ reasoning and tool use abilities rather than constraining them” 不是 AgentScope 一家的策略转向，是整个 Python agent 框架阵营的共识。

[PATTERN] 框架的最优形态是模型能力的镜像：模型能力强的时候框架应该收回预设、把决定权让给模型；模型能力弱的时候框架应该填补、用流程预设兜底。AgentScope v0→v1 与 LangChain 1.x 的同步翻转标志着 Python agent 框架进入了"信任模型"的新阶段。

vs CrewAI：消息驱动 vs 团队隐喻

CrewAI（crewAIInc/crewAI）的产品定位与 AgentScope 完全不一样：它把多 agent 系统类比成人类团队。基本元素是 Agent(role, goal, backstory) + Task(description, expected_output) + Crew(agents, tasks, process)，Process 可选 sequential 或 hierarchical（自动加 manager）。

这是一个有意思的产品决策：用人类团队的隐喻给非工程师降低多 agent 编排的认知门槛。“高级数据研究员 + 报告分析师"这种设定比"actor A 给 actor B 发消息"对产品经理友好得多。代价是"团队隐喻"在某些技术场景下并不自然——比如你想做的是"用 LLM 做异常检测”，而不是"组建一个团队"。

CrewAI 1.x 的 Flows 是它对"团队隐喻 vs 工程化编排"两难局面的回答：@start() / @listen() / @router() / @persist / @human_feedback 装饰器组成一套事件驱动的工作流原语，与 Crew 互相嵌套——Flow 当外层确定性骨架，Crew 当内层自主子任务。这种"外层骨架 + 内层自主"是 CrewAI 1.x 解开"团队隐喻太松散"批评的关键设计。

vs Microsoft Agent Framework：开源研究 vs 微软栈集成

Microsoft Agent Framework（MAF）是微软在 2026 年 4 月 3 日把 AutoGen 与 Semantic Kernel 合并而成的官方继任者。它继承了 AutoGen v0.4 的 actor model + 异步消息传递 + 跨语言（Python / .NET）runtime 内核，分 Core / AgentChat / Extensions 三层 API；又吸收了 SK 的中间件管线、多 provider chat client、声明式 YAML agent、OTel。Magentic-One 作为 5 种 orchestration pattern 之一被纳入（Orchestrator + WebSurfer + FileSurfer + Coder + ComputerTerminal）。

MAF 与 AgentScope 都在右上区（高密度 runtime + 协程异步），看起来高度重叠，但目标用户完全不同——MAF 是为"已经在微软栈里"的团队准备的（Azure OpenAI / Azure AI Search / Power Platform 集成），AgentScope 是为"研究取向 + DashScope/Qwen 体系"的团队准备的。两者都不是开放式生态平台。

vs AG2：原班 AutoGen 的开源延续

AG2 的位置略尴尬——技术上仍在 v0.12.x 摸索 v1.0 路径（autogen.beta 框架），star 数 4.6k 远小于微软主仓和 CrewAI；但它是唯一一条不被微软商业化路线绑架的"原 AutoGen"延续。这层关系的背景是：MAF 收敛了 SK 团队 + AutoGen 团队的同班人马，AG2 是社区分叉延续，由 Chi Wang 与原班人马通过 ag2ai 组织继续维护。对于在意"项目治理独立性"和"延续 v0.2 编程直觉"的团队仍然有价值——尤其是已有大量 v0.2 代码不想改写到 MAF 的存量项目。

一张对位表

维度 AgentScope v1.x LangGraph CrewAI MAF
核心抽象 ReActAgent + MsgHub StateGraph + node Agent + Task + Crew actor + AgentChat
一等公民 消息（Msg） 状态（State） 角色与任务 actor 消息
多 agent 模板 无（开发者自组） 状态图 + Supervisor / Swarm 子包 sequential / hierarchical / Flows 5 种 orchestration（含 Magentic-One）
Time-travel 无 ✅ checkpoint + thread_id 部分（Flows @persist） ✅ checkpointing
长期记忆 内置 Mem0 / ReMe 多层 不内置（要自己拼） unified Memory（LanceDB） 可插拔 memory
默认 provider DashScope / Qwen 优先 多 provider 平衡 OpenAI 优先 Azure OpenAI 一等
RL 集成 ✅ Trinity-RFT ❌ ❌ ❌
研究取向 强（SysML 团队论文驱动） 弱（产品取向） 弱（产品取向） 弱（企业取向）
跨语言 Python only Python only Python only Python + .NET

[PATTERN] 互补关系而非竞争关系：高密度 runtime 派的四个项目（AgentScope、LangGraph、CrewAI、MAF）目标用户重叠但不相同。研究团队选 AgentScope（论文驱动 + RL 集成）；可审计场景选 LangGraph（time-travel）；非工程师友好场景选 CrewAI（团队隐喻）；微软栈选 MAF。把它们放进同一张评分卡比较没什么意义——它们各自都解了一道真实的题。

七、Trinity-RFT：把训练 agent 纳入框架视野

TrinityChatModel + examples/tuner/model_tuning 提供了 6 个调优范例（Math / Frozen Lake / Learn-to-Ask / Email Search / Werewolves / Data Augment），多以 Qwen 2.5/3 系列为底。这是 AgentScope 区别于 LangGraph / AutoGen 的研究路线痕迹——其他框架做"运行时"，AgentScope 试图把"训练"也纳入框架视野。

需要先把命名厘清：Trinity-RFT 是一个独立项目（仓库 agentscope-ai/Trinity-RFT，前 modelscope/Trinity-RFT，论文 arXiv 2505.17826），不是 AgentScope 的内置子模块。它通过 TrinityChatModel 适配 AgentScope，但本身可以独立使用，也可以集成进其他 agent 框架。Trinity-RFT 自己定位为 Explorer / Trainer / Buffer 三件套——Explorer 跑 agent 收集 trajectory，Trainer 用 trajectory 跑 RL，Buffer 在两者之间做经验回放。

TrinityChatModel 与 OpenAIChatModel 在 AgentScope 里是平级的 model 实现——都是 ChatModelBase 的子类，但 TrinityChatModel 在生成轨迹的同时收集 RL 训练所需的 trajectory 信息（reward signal、log_prob、value estimate），可以直接喂给 RLHF / DPO / GRPO 训练循环。

与同类 RL 框架对比：

项目 维护方 与 agent runtime 的关系
Trinity-RFT AgentScope SysML 团队 与 AgentScope 同源，原生集成；可独立使用
verl 字节跳动 纯训练框架，无 agent runtime；通常配合外部 trace 数据使用
OpenRLHF 社区 纯 RL 训练，agent 集成靠用户自拼
TRL（HuggingFace） HuggingFace 通用 RLHF / DPO / GRPO 库，与 agent 框架完全解耦

在四个项目里只有 Trinity-RFT 与 agent runtime 同源——这是 AgentScope 最容易被低估的差异化资产。研究员可以直接在 ReAct 循环里打 reward signal，不需要先把 trace 导出再喂训练框架，反馈回路比"导出 → 训练 → 再导入"短一个数量级。

6 个调优范例的设计语义

examples/tuner/model_tuning 提供的 6 个范例不是随意选的，每一个对应一个 agentic RL 必须解决的子问题：

范例 任务形态 关键挑战 对应的 RL 设计
Math 数学解题 reward 稀疏（只有最终答案对错） outcome-based reward + GRPO 减方差
Frozen Lake OpenAI Gym 经典强化学习环境 长程探索 vs 利用 step-wise reward + value bootstrapping
Learn-to-Ask 给定不充分信息，agent 主动追问 reward 来自"问对了关键问题" turn-level reward shaping
Email Search 邮件库语义检索 + 多轮过滤 tool 调用次数与 reward 负相关（贪婪召回会扣分） cost-aware reward
Werewolves 多 agent 狼人杀对抗 自博弈 + 不完全信息 self-play + opponent modeling
Data Augment LLM 自己生成训练数据再回喂 reward 来自下游任务表现 bootstrap loop + data filtering

这 6 个范例覆盖了 agentic RL 的主要难题轴：reward 稀疏性（Math）、长程探索（Frozen Lake）、信息不完全（Learn-to-Ask、Werewolves）、动作成本（Email Search）、合成数据闭环（Data Augment）。任何想做 agent 自学习的团队都会撞上这 6 个问题之一——AgentScope + Trinity-RFT 提供的不是通用解，是"6 种 problem class 的 reference impl"。

底层模型多以 Qwen 2.5 / Qwen 3 系列为底——这是 AgentScope 与 DashScope/Qwen 体系绑定的另一处明显痕迹。换 Llama / Mistral 不是不行，但 dataset 与 reward function 的调优可能要重做。

阿里 2026-03 还发布了 AgentScope Java + Trinity-RFT 在线训练方案——这是 verl / OpenRLHF / TRL 都没有的 Java 生态打通点，让 Java agent 也能端到端 RL 微调。这条 Java 路线与 Spring AI Alibaba 的下游叠加路径形成对应（参见 Java 阵营对位）。

[PATTERN] 把训练放进框架视野是研究取向项目的标志：产品取向项目（CrewAI、MAF）几乎不会碰训练——它们的目标用户是应用开发者；研究取向项目（AgentScope、Trinity-RFT）必须碰训练——SysML 团队的论文输出本身就需要快速 prototype RL 实验。这种取向差异决定了项目的演化方向：AgentScope 未来会越来越靠近"agent 的实验平台"，而不是"agent 的应用框架"。

八、A2A 与 MCP：AgentScope 的协议化分布式

AgentScope v1.x 的分布式不再走自研 actor，而是走两个标准协议：

A2A（Agent-to-Agent）：把 agent 作为可发现的服务暴露——每个 agent 服务发布一个 agent card（JSON 元数据，描述 agent 的能力、输入输出 schema、调用端点），其他 agent 通过 A2AAgent 类（继承自 AgentBase）远程调用。本质是用 httpx 调远端 HTTP，但协议层标准化了 capabilities discovery 与 message format。

agent card 是一个 well-known JSON 文档（按 A2A 规范放在 /.well-known/agent.json），结构示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "schema_version": "v1",
  "name": "order-checker",
  "description": "校验订单状态、解析订单号、查询配送进度",
  "url": "https://order-agent.your-internal-host/api/agent",
  "provider": {"organization": "internal-team", "url": "..."},
  "version": "1.2.0",
  "capabilities": {
    "streaming": true,
    "push_notifications": false,
    "state_transition_history": true
  },
  "default_input_modes": ["text/plain"],
  "default_output_modes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "verify_order",
      "name": "verify order status",
      "description": "Given an order id, return current order state and ETA.",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string", "pattern": "^ORD-"}},
        "required": ["order_id"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "state": {"type": "string", "enum": ["CREATED", "PAID", "SHIPPED", "DELIVERED", "CANCELED"]},
          "eta": {"type": "string", "format": "date-time"}
        }
      },
      "examples": ["What is the status of ORD-2026-0001?"]
    }
  ]
}

调用方代码极简：

1
2
3
4
5
6
7
from agentscope.a2a import A2AAgent

remote_agent = A2AAgent(
    name="remote-order-checker",
    agent_card_url="https://order-agent.your-internal-host/.well-known/agent.json",
)
reply = await remote_agent(Msg(name="user", role="user", content="ORD-2026-0001 现在到哪了？"))

A2A 调用对发起方而言与本地 ReActAgent 调用语义完全相同——都是 await agent(msg) 返回 Msg。这种"本地与远端语义对齐"是 A2A 协议的核心工程价值，也是它能在 2025-2026 年快速取代各家自研 RPC 的根本原因——任何一家再自研 actor 都要解决"本地远端语义对齐"这件事，A2A 已经把这个解题路径标准化了。

MCP（Model Context Protocol）：把工具作为可发现的服务暴露——每个 MCP server 发布若干 tool schema（JSON Schema 描述参数与返回），agent 通过 HttpStatelessClient / HttpStatefulClient 远程调用。AgentScope 在 1.x 把 MCP 工具透明注册进 Toolkit，开发者写代码时不区分本地工具与 MCP 工具。

这种"协议化分布式"与 v0.x 的"自研 actor"对比，工程姿态完全不同：

维度 v0.x 自研 actor v1.x 协议化分布式
跨语言 不可能（gRPC schema 自定义） 原生跨语言（A2A / MCP 是 RFC）
跨进程 gRPC 长连接 HTTP（无状态优先）
服务发现 静态配置 agent card / tool schema
安全模型 自研 复用 HTTP 生态（OAuth、TLS、API Gateway）
框架锁定 强 无（任意框架的 agent 都能 A2A 互通）

这种转向的更深含义是：AgentScope 不再试图做"分布式 agent runtime"，而是做"单进程 agent runtime + 协议互通"。这与 MAF 的取向不同——MAF 的 Core 层仍在做 actor runtime，跨进程通信由 actor model 内部解决；AgentScope 直接把跨进程交给 HTTP + 协议。

[PATTERN] 协议化分布式的优势在生态外部：自研 actor 的好处是性能与一致性（gRPC 长连接 + 强类型 schema 可以做更激进的优化）；协议化分布式的好处是生态互通（任意框架的 agent 只要支持 A2A / MCP 就能接进来）。AgentScope 的取向选择反映了 2025-2026 年 agent 生态的真实状态——单一框架统治整个生态已经不可能，互通比性能更值得投资。

协议生态的关键时间点：AAIF 与规范演进

AgentScope 选择押注协议化的判断在 2025 年底得到了印证。2025-12-09 Anthropic 把 MCP 协议本身捐给 Linux 基金会下的 Agentic AI Foundation（AAIF）——同批捐赠还有 OpenAI 的 AGENTS.md 和 Block 的 goose。这次捐赠把 MCP 从"Anthropic 主导的协议"变成"基金会治理的中立标准"，与 K8s 在 CNCF 的角色相同。

到 2025 年底 MCP 的生态规模已经验证了它的标准地位：

  • 公开 MCP servers 数 > 10000
  • Python + TypeScript SDK 月下载量 ~9700 万
  • MCP 当前规范是 2025-06-18 版（不是常被引用的 2025-03-26 版）。后者首次引入 Streamable HTTP，前者移除 JSON-RPC 批处理、强制 lifecycle、新增 Elicitation 与结构化输出
  • **MCP Apps 提案（SEP-1865）**由 OpenAI + Anthropic + MCP-UI 联合提出，2025-11 发布，把 MCP 从纯文本/结构化数据扩到可视化 UI

这些数字与 AgentScope 当前 MCP 集成的具体形态对应：v1.x 的 HttpStatelessClient / HttpStatefulClient 默认走 streamable_http transport，与 2025-06-18 规范对齐；旧的 HTTP+SSE 进入兼容语义、不推荐用于新项目。Spring AI 1.1 / 2.0 也在 MCP Java SDK v0.12.1 起完整跟进同一规范——这是跨 Java / Python / .NET 生态最难得的协议同步点。

九、AgentScope Studio 与 OTel tracing

AgentScope 把 tracing 模块提到与 agent 同级的顶层位置。配套的 AgentScope Studio 是一个独立的 Web UI，接收 OTel 格式的 span 数据并可视化 agent 行为。

Studio 能看的内容包括：

  • 每个 agent 的 sys prompt（包括动态变更）
  • 每次 LLM 调用的完整 input / output（含 tool_calls、reasoning content）
  • 每个工具调用的入参与返回（含失败信息）
  • MsgHub 内部的消息广播图（哪条消息广播给了哪些 agent）
  • 跨 session 的 trace 聚合（按 user_id / agent_name / session_id 过滤）

启动 Studio 一行命令：

1
agentscope studio --host 0.0.0.0 --port 8000

应用代码里只需要：

1
2
from agentscope.tracing import init_tracing
init_tracing(studio_url="http://localhost:8000", project_name="myagent")

之后所有 ReActAgent / MsgHub / tool 调用自动 trace。这种"开箱即用的 tracing"在 Python agent 框架里是 AgentScope 与 LangGraph（LangSmith）的两个最完整方案——CrewAI 的 trace 需要走 OpenTelemetry 通用栈再自己接 backend，MAF 的 OTel 集成是企业方向（Azure Monitor）。

[PATTERN] tracing 是工程纪律不是 debug 工具：把 tracing 留到出问题时再加是反面教材。AgentScope 把 Studio 与 OTel 提到顶层模块的意图，正是把 tracing 从"可选附加"提到"默认装配"——这与 CLI agent 项目（Claude Code、Cursor）默认开 telemetry 是同一种工程姿态。

十、AgentScope 选型一句话

把这九节合起来看，AgentScope 的真实定位是：给研究取向 + Python 优先 + 需要可观测可评测可训练的多 agent 团队，提供一个不强加流程的 ReAct + 消息驱动 runtime。

这句话里每个词都有用：

  • 研究取向：论文驱动的项目演化路径，6 个 RL 调优范例直接内置
  • Python 优先：v1.x 不再做跨语言 runtime，跨语言走 A2A 协议
  • 可观测：tracing 与 Studio 是顶层模块
  • 可评测：evaluate 模块与 agent 同级
  • 可训练：Trinity-RFT 集成
  • 不强加流程：MsgHub + pipeline 是 ad-hoc 工作流，不是状态机
  • ReAct + 消息驱动：单 agent 是 async ReAct 循环，多 agent 是显式消息广播

不在这个范围内的需求都不该选 AgentScope：

  • 你要的是状态机审计与 time-travel → LangGraph
  • 你要的是非工程师友好的团队隐喻 → CrewAI
  • 你要的是微软栈集成 → MAF
  • 你要的是企业 Java 系统 → Spring AI / LangChain4j（参见 Java 阵营对位）
  • 你要的是封闭学习回路的长程自主 agent → 任何框架都不够，跳过框架直接做 harness（参见 Hermes 横评 中的"框架层 vs 产品层"讨论）

[PATTERN] 选框架的最终判据是"和你在解什么问题对齐"：AgentScope 解的是"研究/产品团队怎么实验和部署多 agent 应用"。所有"我应该选 AgentScope 还是 X"的问题，本质上是"我在解哪一道题"的问题。

写在最后：从理解到上手

理解一个框架与上手一个框架是两回事。本文是"为什么 AgentScope 长这样"的设计思想梳理；如果你需要的是"从空仓库到一个跑起来的 multi-agent 系统"的循序渐进的工程指引，请直接读配套教程：

如果你正在评估 Java 阵营的对应项目：

如果你正在判断"我是不是应该跳过框架层直接做产品级 harness"：

主要引用源：

版本快照（2026-05-17 截止日）：AgentScope 1.0.20 / LangGraph 1.2.0 / CrewAI 1.14.4 / Microsoft Agent Framework .NET 1.0.0（2026-04-02 GA）/ AG2 0.12.3 / Trinity-RFT 论文 arXiv 2505.17826 / MCP 协议规范 2025-06-18