[Breaking Change] Migrate backend from AgentScope 1.x to AgentScope 2.0

[rayrayraykk]

Summary

AgentScope 2.0 has been officially released. We plan to upgrade QwenPaw's backend dependency from AgentScope 1.x (currently agentscope==1.0.20 + agentscope-runtime==1.1.6) to AgentScope 2.0, adopting its new architecture, APIs, and runtime model. This migration is expected to ship as QwenPaw v1.2.0.

Component(s) Affected

• Core / Backend (app, agents, config, providers, utils, local_models)
• Console (frontend web UI)
• Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
• Skills
• CLI
• Documentation (website)
• Tests
• CI/CD
• Scripts / Deploy

Problem / Motivation

1. AgentScope 1.x is entering maintenance mode — new features and optimizations will only land in 2.0.
2. AgentScope 2.0 introduces breaking API changes — staying on 1.x means accumulating tech debt and missing upstream improvements (better message protocol, new agent lifecycle, improved MCP integration, sandbox for secure execution, etc.).
3. Sandbox mechanism — 2.0 provides built-in sandbox support for secure code execution and tool isolation, which is critical for QwenPaw's Coding Mode and plugin system.
4. Community alignment — downstream users and plugin authors will expect 2.0 compatibility.

Proposed Solution

Migration Scope

Area	Files Affected (est.)	Key Changes
Agent lifecycle & message protocol	app/runner/, agents/	Adapt to new AgentBase / message class API
Model factory / provider integration	app/routers/providers.py, agents/	New model wrapper interface
MCP client	app/mcp/	Align with 2.0 MCP protocol changes
Runtime & multi-agent orchestration	app/multi_agent_manager.py, app/runner/	New runtime/orchestration primitives
Channels	app/channels/	Message format adaptation
Plugins	plugins/	Update tool base class imports
Tests	tests/	Rewrite mocks & fixtures for new API

Migration Strategy

1. Phase 1 — Dependency upgrade & core migration: Bump agentscope to 2.0 in pyproject.toml, migrate app/runner/, agents/, and multi_agent_manager.py to native 2.0 APIs. All work happens on the feat/agentscope-2.0 feature branch.
2. Phase 2 — Peripheral migration: Migrate channels, plugins, and MCP client.
3. Phase 3 — Sandbox & new features: Integrate AgentScope 2.0's sandbox mechanism for secure code execution and tool isolation.
4. Phase 4 — Tests & stabilization: Rewrite test mocks/fixtures, ensure full CI green.
5. Phase 5 — Documentation & release: Update docs, merge feature branch to main.

Branching & PR Strategy

• A long-lived feature branch feat/agentscope-2.0 will be created from main.
• Large changes will be broken into sub-PRs merged into the feature branch before final merge to main.
• Each sub-PR must pass CI (tests may be temporarily skipped for files in active migration with explicit TODO markers).

Current State & Open PRs

• Current dependency: agentscope==1.0.20, agentscope-runtime==1.1.6
• ~30+ core source files directly import agentscope
• ~20+ test files depend on agentscope APIs
• No existing PRs targeting this migration yet

Alternatives Considered

1. Pin to AgentScope 1.x indefinitely — rejected because 1.x will stop receiving fixes and new features.
2. Incremental in-place migration without feature branch — rejected due to high risk of breaking main during a multi-week effort.

Acceptance Criteria

• All import agentscope statements reference 2.0-compatible APIs
• pyproject.toml declares agentscope>=2.0.0
• All existing unit tests pass (or are updated to reflect intentional behavior changes)
• Channels (DingTalk, Feishu, etc.) function correctly end-to-end
• Plugin base class (ToolBase) works with 2.0 runtime

Additional Context

• AgentScope 2.0 release announcement: https://mp.weixin.qq.com/s/AcBTESODnZqpADRELcK5MQ
• AgentScope 2.0 official documentation: https://docs.agentscope.io/v2
• Migration owner: @qbc2026

Willing to Contribute

• I am willing to open a PR for this feature (after discussion).

---

中文版

概述

AgentScope 2.0 已正式发布。我们计划将 QwenPaw 后端依赖从 AgentScope 1.x（当前为 agentscope==1.0.20 + agentscope-runtime==1.1.6）升级至 AgentScope 2.0，全面采用其新架构、新 API 和新运行时模型。本次迁移预计以 QwenPaw v1.2.0 版本发布。

影响组件

• Core / Backend (app, agents, config, providers, utils, local_models)
• Console (前端 Web UI)
• Channels (钉钉、飞书、QQ、Discord、iMessage 等)
• Skills
• CLI
• Documentation (网站文档)
• Tests
• CI/CD
• Scripts / Deploy

问题 / 动机

1. AgentScope 1.x 即将进入维护模式 —— 新特性和优化将仅在 2.0 上发布。
2. AgentScope 2.0 包含破坏性 API 变更 —— 继续停留在 1.x 会累积技术债务，错失上游改进（新消息协议、新 Agent 生命周期、更好的 MCP 集成、安全沙箱等）。
3. 沙箱机制 —— 2.0 内置沙箱支持，可实现代码执行与工具调用的安全隔离，对 QwenPaw 的 Coding Mode 和插件系统至关重要。
4. 社区对齐 —— 下游用户和插件开发者将期望 2.0 兼容性。

拟定方案

迁移范围

模块	预估涉及文件数	主要变更
Agent 生命周期 & 消息协议	app/runner/, agents/	适配新 AgentBase / 消息类 API
Model factory / Provider 集成	app/routers/providers.py, agents/	新模型包装器接口
MCP 客户端	app/mcp/	对齐 2.0 MCP 协议变更
运行时 & 多 Agent 编排	app/multi_agent_manager.py, app/runner/	新运行时/编排原语
Channels	app/channels/	消息格式适配
插件	plugins/	更新工具基类 import
测试	tests/	重写 mock 和 fixture 以适配新 API

迁移策略

1. 阶段一 — 依赖升级 & 核心迁移：在 pyproject.toml 中将 agentscope 升级至 2.0，将 app/runner/、agents/、multi_agent_manager.py 迁移至原生 2.0 API。所有工作在 feat/agentscope-2.0 特性分支上进行。
2. 阶段二 — 外围迁移：迁移 channels、plugins 和 MCP 客户端。
3. 阶段三 — 沙箱 & 新特性引入：集成 AgentScope 2.0 的沙箱机制，实现代码执行和工具调用的安全隔离。
4. 阶段四 — 测试 & 稳定化：重写测试 mock/fixture，确保 CI 全部通过。
5. 阶段五 — 文档 & 发布：更新文档，将特性分支合入 main。

分支 & PR 策略

• 从 main 创建长期特性分支 feat/agentscope-2.0。
• 大变更拆分为子 PR，先合入特性分支，最终统一合入 main。
• 每个子 PR 必须通过 CI（处于活跃迁移中的文件可暂时跳过测试，但必须添加显式 TODO 标记）。

当前状态 & 已有 PR

• 当前依赖：agentscope==1.0.20、agentscope-runtime==1.1.6
• 核心源码中 ~30+ 个文件直接 import agentscope
• ~20+ 个测试文件依赖 agentscope API
• 目前尚无针对本迁移的已有 PR

曾考虑的替代方案

1. 永久锁定 AgentScope 1.x —— 否决，因为 1.x 将停止接收修复和新功能。
2. 在 main 上逐步原地迁移（不使用特性分支） —— 否决，多周迁移期间有较高概率破坏 main 分支稳定性。

验收标准

• 所有 import agentscope 语句引用 2.0 兼容 API
• pyproject.toml 声明 agentscope>=2.0.0
• 所有现有单元测试通过（或根据预期行为变更进行更新）
• Channels（钉钉、飞书等）端到端功能正常
• 插件基类（ToolBase）在 2.0 运行时下正常工作

补充说明

• AgentScope 2.0 发布公告：https://mp.weixin.qq.com/s/AcBTESODnZqpADRELcK5MQ
• AgentScope 2.0 官方文档：https://docs.agentscope.io/v2
• 本次改造负责人：@qbc2026

是否愿意贡献

• 我愿意在讨论后提交 PR 来实现此功能。

[rayrayraykk]

Any feedback or suggestions are highly welcome :)

Current dev branch: dev/agentscope2.0

[One-sixth]

希望对插件有一个新的 skill 或 比较详细的1.x到2.0 API迁移文档，可以让AI 帮助插件迁移。🤗

[rayrayraykk]

希望对插件有一个新的 skill 或 比较详细的1.x到2.0 API迁移文档，可以让AI 帮助插件迁移。🤗

Thanks for suggestion! We will provide a migration guidance for all plugins.

[xlg1024]

Any updates on the AgentScope 2.0 migration plan?
Thanks!
请问一下，关于升级到 AgentScope 2.0 是否有新的进展？目前还在规划中吗？
感谢

[qbc2016]

Any updates on the AgentScope 2.0 migration plan? Thanks! 请问一下，关于升级到 AgentScope 2.0 是否有新的进展？目前还在规划中吗？ 感谢

In progress. Please refer to #4846.

[xlg1024]

Any updates on the AgentScope 2.0 migration plan? Thanks! 请问一下，关于升级到 AgentScope 2.0 是否有新的进展？目前还在规划中吗？ 感谢

In progress. Please refer to #4846.

Could I ask whether the AgentScope 2.0 branch is planned to be merged into the main branch, and whether there is an approximate timeline for that?
Thanks !