1.x 到 2.x 迁移

AgentScope 2.0 是一次从底层重建的破坏性大版本。消息、工具、工作区、权限、中间件与服务层全部重写，1.x 的 Agent 基类、Pipeline、Memory、Hooks、Trinity 与 a2a 等模块在 2.x 中要么被移除、要么被替换为完全不同的抽象。本页给 1.x 用户提供一份完整的 1.x -> 2.x 概念与 API 对照，帮助你按维度逐项迁移，而不是试图原地升级。

版本基线：1.x 终版为 agentscope 1.0.21（2026-05-25，与 2.0.0 同日发布）；2.x 本教程锚定 agentscope 2.0.4（PyPI，2026-07-07），要求 Python >=3.11。1.x 与 2.x API 不兼容，官方不提供自动迁移工具，需要按本页对照表逐项改写。1.x 代码仅在本页作为迁移对照出现。

迁移总览：2.0 是底层重建

2.0 不是增量升级，而是把 Agent 运行时从"可调用对象 + Pipeline 编排"重建为"事件驱动 ReAct 引擎 + 中间件 + 服务层"。1.x 里由 ReActAgent、Pipeline、MsgHub、memory 模块、Hooks 分别承担的职责，在 2.x 中被重新分配到 Agent、Plan（Task 工具）、Agent Team、Context + LTM Middleware、Agent Middleware 上。迁移的核心工作不是改函数名，而是重新理解这些职责的新归属。

前端类比

如果你来自前端，可以把 1.x -> 2.x 类比为一次 React class 组件到 hooks + 函数组件 量级的重构：生命周期方法被拆解为独立的 hook，状态管理从实例字段变为显式的状态容器，组合方式从继承 / mixin 变为 hook 嵌套。AgentScope 1.x 的 ReActAgent.__call__ + Pipeline + Hooks 对应"class 组件 + 高阶组件 + 生命周期"，2.x 的 Agent.reply_stream + Middleware 洋葱模型 + Agent Team 对应"函数组件 + 自定义 hook + 组合式服务"。

AgentScope 原生语义：2.x 的 Agent 是无状态的 ReAct 循环引擎，状态显式由 AgentState （Pydantic）管理；reply() 同步返回最终 Msg，reply_stream() 异步产出结构化事件。1.x 的同步可调用对象 agent(msg) 范式已不再适用。工具、MCP、Skills 统一由 Toolkit 装配并受 Permission 三态拦截；可观测性、RAG、长期记忆都以 Middleware 形式挂载，而非 1.x 的 Hooks。 Pipeline 与 MsgHub 被移除，多步骤编排由 Plan（Task 工具）+ Agent Team（服务层）承担。

核心对照大表

下表按维度汇总 1.x -> 2.x 的概念与 API 映射。"迁移动作"列给出每一项最关键的改写方向。

维度	1.x	2.x	迁移动作
Agent 类	`from agentscope.agents import ReActAgent`	`from agentscope.agent import Agent`	把 `ReActAgent` 替换为统一 `Agent`
调用方式	`agent(msg)`（`__call__`，同步）	`await agent.reply(msg)` / `async for event in agent.reply_stream(msg)`	`__call__` 改为 `reply` / `reply_stream`（async）
system prompt	`sys_prompt=`	`system_prompt=`	参数名 `sys_prompt` 改 `system_prompt`
model	`model=` 传字符串	`model=<ChatModel 实例>`（如 `DashScopeChatModel`）	model 字符串改为 ChatModel 实例，凭据从 Credential 注入
状态管理	`state_dict` / `load_state_dict`	`AgentState`（Pydantic，`from agentscope.state import AgentState`）	`state_dict` 改为显式 `AgentState`
编排	`Pipeline`（Sequential/ForLoop/WhileLoop/IfElse/Switch）+ `MsgHub`	移除；用 Plan（Task 工具）+ Middleware + Agent Team	Pipeline/MsgHub 逻辑拆分到 Plan 与 Agent Team
记忆	`agentscope.memory`（InMemoryMemory/PermanentMemory），`ReActAgent(long_term_memory=...)`	移除；短期 = Context（`ContextConfig`），长期 = LTM Middleware（`AgenticMemoryMiddleware`/`Mem0Middleware`/`ReMeMiddleware`）	Memory 模块改为 Context + LTM Middleware
Hooks	1.x hook 机制	移除，替换为 Agent Middleware（`MiddlewareBase`）	Hooks 改写为 Middleware
模型包装器	Trinity model wrapper	移除	Trinity 直接删除，用 ChatModel + Formatter
多 Agent 通信	旧 `a2a` 包	移除；多 Agent = Agent Team（服务层 Leader-Worker）	a2a 改为 Agent Team
评估	`evaluate` 模块	2.0 移除，截至 2.0.4 未回归	自行实现或等待回归
实时语音	旧 `realtime` 模块	2.0 移除，截至 2.0.4 未回归（注意：2.0.4 的 "realtime agent interruption" 指运行时中断/恢复，非旧语音模块）	自行实现或等待回归
Msg	`Msg`（dict-like）	Pydantic `Msg`，统一 ContentBlocks	Msg 改为 Pydantic 模型，使用工厂方法 `UserMsg`/`AssistantMsg`/`SystemMsg`
内容块	`ImageBlock`/`AudioBlock`/`VideoBlock`/`ToolUseBlock`	`DataBlock`（`media_type` 区分）/`ToolCallBlock` + 新增 `HintBlock`	媒体块改 `DataBlock`，`ToolUseBlock` 改 `ToolCallBlock`
凭据	内嵌在 Model 中	解耦到 `credential` 模块	凭据从 Model 抽出，集中到 `Credential`
Formatter	分散	`agentscope.formatter`，per-provider Chat/MultiAgent	Formatter 走 formatter 模块，随 ChatModel 自动选择
事件系统	无	新增：`reply_stream` 产出结构化事件（文本块/工具调用/工具结果/思考块）	利用事件流做流式渲染与 HITL
权限系统	无	新增：`Permission` 三态（allow/deny/ask）	在工具执行前加权限拦截
工作区	无统一抽象	新增：`Workspace`（Local/Docker/E2B）+ `Offloader`	工具执行迁移到 Workspace 沙箱
工具系统	分散	新增：`Toolkit` 统一 tools + MCP + Skills + `ToolGroup`	工具统一注册到 Toolkit
服务化	无	新增：Agent Service（`create_app` FastAPI）+ Agent Team	需要服务化时用 `create_app`
Skills	无	新增：Skill loader + `ToolGroup` 打包	按需加载 Skills

逐项迁移要点

1. ReActAgent -> 统一 Agent

1.x 的 ReActAgent 在 2.x 被重构为统一的 Agent 类。导入路径从复数 agentscope.agents 变为单数 agentscope.agent。Agent 仍然是 ReAct 循环引擎，但调用入口、参数名与状态管理全部改变。迁移时不要只改类名，要同时处理 reply 调用、system_prompt 参数与 AgentState。

2. `call` -> `reply` / `reply_stream`

1.x 的 agent(msg) 直接调用 __call__，同步返回 Msg。2.x 把 __call__ 替换为两个公开方法：

await agent.reply(msg)：同步返回最终 Msg（仍是 async）。
async for event in agent.reply_stream(msg)：异步产出结构化事件流，支持文本块、工具调用、工具结果、思考块，并在事件流中原生支持 HITL 确认与中断恢复。

所有调用点都需要改为 await reply 或 async for ... reply_stream。

3. `sys_prompt` -> `system_prompt`，`model` 字符串 -> ChatModel 实例

1.x 用 sys_prompt= 传系统提示词，model= 传模型名字符串。2.x 参数名改为 system_prompt= （全称），且 model= 需要传入一个 ChatModel 实例（如 DashScopeChatModel），凭据从独立的 Credential 模块注入，不再内嵌在模型字符串里。这是"凭据解耦"的体现：1.x 把 API Key 绑在模型配置里，2.x 把凭据抽到 credential 模块统一管理。

4. `state_dict` / `load_state_dict` -> `AgentState`

1.x 用 agent.state_dict 与 agent.load_state_dict() 管理状态，耦合在 Agent 实例上。2.x 废弃这两个方法，改为显式的 AgentState（Pydantic 模型，from agentscope.state import AgentState）。状态不再挂在 Agent 实例上，而是作为独立对象传递与持久化。

5. Pipeline / MsgHub -> Plan + Middleware + Agent Team

1.x 的 Pipeline（SequentialPipeline/ForLoopPipeline/WhileLoopPipeline/IfElsePipeline/ SwitchPipeline）和 MsgHub 提供声明式流程编排与消息广播。2.x 移除了全部 Pipeline 与 MsgHub，原因是它们与 Agent 内部逻辑耦合过深。迁移方向：

顺序 / 条件 / 循环：交给 Agent 自身的 ReAct 循环 + Plan（Task 工具：TaskCreate/TaskGet/ TaskList/TaskUpdate），让 Agent 自主规划。
跨 Agent 通信：交给 Agent Team（服务层 Leader-Worker 模式），而非 MsgHub 广播。
横切关注点：交给 Middleware 洋葱模型。

不要试图在 2.x SDK 层复刻 1.x 的 Pipeline 习惯。

6. Memory 模块 -> Context + LTM Middleware

1.x 的 agentscope.memory 模块（InMemoryMemory/PermanentMemory）以及 ReActAgent(long_term_memory=...) 在 2.x 被整体移除，原因是与 Agent 逻辑耦合过紧。2.x 把记忆拆成两层：

短期记忆：Context（ContextConfig），负责上下文压缩、卸载与 agentic 检索。
长期记忆：LTM Middleware（AgenticMemoryMiddleware/Mem0Middleware/ReMeMiddleware），以中间件形式挂载。

迁移时 from agentscope.memory import ... 会直接 ImportError，需要改为 Context 配置 + LTM Middleware 装配。

7. Hooks -> Agent Middleware

1.x 的 hook 机制在 2.x 被替换为更通用的 Agent Middleware 系统（MiddlewareBase）。所有原 hook 承担的横切逻辑--Tracing、RAG、长期记忆、预算控制--都以中间件形式包裹 Agent 的执行。例如 1.x 内嵌在 Agent 里的 OpenTelemetry 集成，2.x 改由 TracingMiddleware 承担。

8. Msg 与 ContentBlocks 重命名

1.x 的 Msg 是 dict-like 结构。2.x 把 Msg 重构为 Pydantic BaseModel，强制内容校验，并新增 created_at/finished_at/usage 字段。内容块的重命名：

ImageBlock/AudioBlock/VideoBlock -> 统一 DataBlock，用 media_type 区分类型。
ToolUseBlock -> ToolCallBlock，并新增 state/suggested_rules 字段。
新增 HintBlock 用于 Agent 引导与中间推理。

创建消息时优先用工厂方法 UserMsg/AssistantMsg/SystemMsg，而非手工构造。

已移除且未回归的能力

以下能力在 2.0 中被移除，截至 2.0.4 尚未回归，迁移时需要自行实现或等待后续版本：

能力	1.x 位置	2.x 状态	应对
`evaluate` 模块	`agentscope.evaluate`	2.0 移除，2.0.4 未回归	自行实现评估逻辑，或跟踪 release notes 等待回归
旧 `realtime` 模块	`agentscope.realtime`（语音实时）	2.0 移除，2.0.4 未回归	自行实现语音管道，或等待后续版本

注意区分：2.0.4 Release Notes 中提到的 "realtime agent interruption" 指的是运行时的中断 / 恢复能力（通过事件流暂停 Agent 执行），不是 1.x 的语音 realtime 模块。两者名称相似但完全不同。

RAG 与长期记忆的过时文案警示

官方 1.x -> 2.x Changelog 的 "RAG & Long-Term Memory" 小节仍写着 "Migration from 1.0 to 2.0 is in progress; the module will return in upcoming releases"。这段文案已过时：RAG 能力已于 2.0.3 落地，长期记忆（LTM）于 2.0.4 落地。遇到这段 "in progress" 描述时，以 Release Notes 与源码为准，不要被误导以为 RAG/LTM 尚不可用。

代码对照示例

下面是一个最小 Agent 的 1.x 与 2.x 写法对照。左侧 1.x 代码仅作迁移对照，本教程其余页面不再使用 1.x API。

1.x 写法（仅对照）：

python

# 1.x - 仅作迁移对照，2.x 不可运行
from agentscope.agents import ReActAgent
from agentscope.message import Msg

agent = ReActAgent(
    name="assistant",
    sys_prompt="你是一个 helpful 助手。",  # 1.x: sys_prompt
    model="qwen-plus",                     # 1.x: model 传字符串
)

# 1.x: 直接 __call__，同步返回 Msg
reply_msg = agent(Msg(name="user", content="你好", role="user"))
print(reply_msg.content)

2.x 写法：

python

# 2.x
import asyncio
from agentscope.agent import Agent
from agentscope.message import Msg, UserMsg
from agentscope.model import DashScopeChatModel
from agentscope.credential import Credential

# 2.x: 凭据从 Credential 注入，model 传 ChatModel 实例
credential = Credential.from_env()
model = DashScopeChatModel(
    credential=credential,
    model_name="qwen-plus",
)

agent = Agent(
    name="assistant",
    system_prompt="你是一个 helpful 助手。",  # 2.x: system_prompt
    model=model,                              # 2.x: ChatModel 实例
)


async def main() -> None:
    # 2.x: await reply，返回最终 Msg
    reply_msg = await agent.reply(
        UserMsg(content="你好", name="user"),
    )
    print(reply_msg.content)

    # 2.x: 或用 reply_stream 逐事件消费
    async for event in agent.reply_stream(
        UserMsg(content="再问一次", name="user"),
    ):
        print(event)


asyncio.run(main())

关键差异：sys_prompt -> system_prompt，model="qwen-plus" -> DashScopeChatModel 实例 + Credential，agent(msg) -> await agent.reply(msg)，Msg(...) -> UserMsg(...) 工厂方法。

迁移检查清单

逐项确认你的 1.x 项目已完成以下改写：

[ ] 把 ReActAgent 改为统一 Agent（from agentscope.agent import Agent）
[ ] 把 agent(msg) 的 __call__ 改为 await agent.reply(msg) 或 async for event in agent.reply_stream(msg)
[ ] 把 sys_prompt= 改为 system_prompt=
[ ] 把 model= 字符串改为 ChatModel 实例（如 DashScopeChatModel），凭据从 Credential 注入
[ ] 把 state_dict / load_state_dict 改为显式 AgentState
[ ] 把 Pipeline / MsgHub 逻辑拆分到 Plan（Task 工具）+ Agent Team + Middleware
[ ] 把 agentscope.memory 改为 Context（ContextConfig）+ LTM Middleware
[ ] 把 Hooks 改写为 Agent Middleware（MiddlewareBase）
[ ] 把 ImageBlock/AudioBlock/VideoBlock 改为 DataBlock，ToolUseBlock 改为 ToolCallBlock
[ ] 确认 evaluate 与旧 realtime 模块的使用点已自行替代（截至 2.0.4 未回归）
[ ] 确认 Trinity model wrapper 与旧 a2a 包的使用点已迁移到 ChatModel + Agent Team

常见迁移坑

误以为有自动迁移工具：1.x 与 2.x API 不兼容，官方不提供任何自动迁移脚本或 codemod。所有改写必须手动进行，按本页对照表逐项处理。
把 Pipeline 习惯套到 SDK 层：2.x SDK 层没有 Pipeline，试图在 Agent 外部手动拼装 SequentialPipeline 等价物会偏离 2.x 设计。顺序 / 条件 / 循环应交给 Agent 的 ReAct 循环 + Plan，多 Agent 协作交给 Agent Team。
Memory 模块 ImportError：from agentscope.memory import InMemoryMemory 在 2.x 会直接报 ModuleNotFoundError。这不是安装问题，而是模块已被移除。短期记忆用 Context，长期记忆用 LTM Middleware。
混淆两个 realtime：2.0.4 文档里的 "realtime agent interruption" 是运行时中断 / 恢复，不是 1.x 的语音 realtime 模块。不要因为看到 "realtime" 就以为旧语音模块回归了。
被 Changelog 过时文案误导：Changelog 的 "RAG & Long-Term Memory" 小节写 "in progress"，但 RAG 已在 2.0.3、LTM 已在 2.0.4 落地。以 Release Notes 与源码为准。
在 Python 3.10 环境安装 2.x：2.x 要求 >=3.11，1.x 要求 >=3.10。在 3.10 下 pip install agentscope==2.0.4 会因版本约束失败，这不是镜像问题。

1.x 到 2.x 迁移

迁移总览：2.0 是底层重建

前端类比

核心对照大表

逐项迁移要点

1. ReActAgent -> 统一 Agent

2. `call` -> `reply` / `reply_stream`

3. `sys_prompt` -> `system_prompt`，`model` 字符串 -> ChatModel 实例

4. `state_dict` / `load_state_dict` -> `AgentState`

5. Pipeline / MsgHub -> Plan + Middleware + Agent Team

6. Memory 模块 -> Context + LTM Middleware

7. Hooks -> Agent Middleware

8. Msg 与 ContentBlocks 重命名

已移除且未回归的能力

RAG 与长期记忆的过时文案警示

代码对照示例

迁移检查清单

常见迁移坑

先修

下一步

官方参考

1.x 到 2.x 迁移 ​

迁移总览：2.0 是底层重建 ​

前端类比 ​

核心对照大表 ​

逐项迁移要点 ​

1. ReActAgent -> 统一 Agent ​

2. __call__ -> reply / reply_stream ​

3. sys_prompt -> system_prompt，model 字符串 -> ChatModel 实例 ​

4. state_dict / load_state_dict -> AgentState ​

5. Pipeline / MsgHub -> Plan + Middleware + Agent Team ​

6. Memory 模块 -> Context + LTM Middleware ​

7. Hooks -> Agent Middleware ​

8. Msg 与 ContentBlocks 重命名 ​

已移除且未回归的能力 ​

RAG 与长期记忆的过时文案警示 ​

代码对照示例 ​

迁移检查清单 ​

常见迁移坑 ​

先修 ​

下一步 ​

官方参考 ​

1.x 到 2.x 迁移

迁移总览：2.0 是底层重建

前端类比

核心对照大表

逐项迁移要点

1. ReActAgent -> 统一 Agent

2. `call` -> `reply` / `reply_stream`

3. `sys_prompt` -> `system_prompt`，`model` 字符串 -> ChatModel 实例

4. `state_dict` / `load_state_dict` -> `AgentState`

5. Pipeline / MsgHub -> Plan + Middleware + Agent Team

6. Memory 模块 -> Context + LTM Middleware

7. Hooks -> Agent Middleware

8. Msg 与 ContentBlocks 重命名

已移除且未回归的能力

RAG 与长期记忆的过时文案警示

代码对照示例

迁移检查清单

常见迁移坑

先修

下一步

官方参考