Appearance
版本与生态
AgentScope 2.x 与 1.x 是两套不兼容的 API 世代。本教程所有代码与概念都以 2.x 为准，这一页用来 锁定版本基线、辨别官方文档站、并划清生态边界，避免在错误的版本或错误的站点上耗费时间。
版本基线：本教程以 Python
agentscope 2.0.4（PyPI，2026-07-07 发布）为准，要求 Python>=3.11。官方文档站默认版本2.0.5dev跟随 main 分支，可能领先 PyPI，使用前需对照源码。
版本基线表
下表汇总四个权威来源的版本信号。教程锚定第一行（PyPI 2.0.4）。
| 来源 | 入口 | 版本 | Python | API 世代 | 本教程主线 |
|---|---|---|---|---|---|
| PyPI | https://pypi.org/project/agentscope/ | 2.0.4（2026-07-07） | >=3.11 | 2.x | 是 |
| GitHub | https://github.com/agentscope-ai/agentscope/releases | v2.0.4 | >=3.11 | 2.x | 是 |
| 2.x 文档站 | https://docs.agentscope.io | 2.0.4（默认 2.0.5dev，跟随 main） | >=3.11 | 2.x | 是 |
| 1.x 文档站 | https://doc.agentscope.io | 1.0.21 | >=3.10 | 1.x | 否（已终结） |
来源依据：PyPI 项目页（pypi.org/project/agentscope）标注 作者为 "SysML team of Alibaba Tongyi Lab"，最新版本 2.0.4，发布于 2026-07-07，requires-python 为 >=3.11；GitHub 仓库已迁移至 agentscope-ai/agentscope，Releases 列表包含 v2.0.4 至 v2.0.0 以及终结版 v1.0.21。
1.x 与 2.x 分界
- 2.0.0 于 2026-05-25 发布，1.0.21 同日发布并作为 1.x 终版。
- 1.x 与 2.x API 不兼容，官方不提供自动迁移工具，需要按 1.x 到 2.x 变更日志逐项改写。
- 完整变更对照见官方 1.x 到 2.x 变更日志 （页面标题为 "Core differences between AgentScope 2.0 and 1.0"）。
分界信号
下面两组导入与调用形态可以快速判断一段代码属于哪个世代。1.x 写法仅作为对照文本出现，本教程 不使用 1.x API。
| 世代 | 导入 | 调用入口 |
|---|---|---|
| 2.x | from agentscope.agent import Agent | agent.reply() |
| 1.x | from agentscope.agents import ReActAgent（1.x，仅对照） | agent()（1.x，仅对照） |
2.x 的统一入口是 Agent 类的 reply()（同步返回最终 Msg）与 reply_stream()（异步产出 结构化事件）；1.x 直接可调用对象 agent() 的用法在 2.x 已不再适用。
文档站双站警示
AgentScope 存在两个外观相近但内容世代完全不同的官方文档站，这是最常踩的坑：
| 站点 | URL | 引擎 | 版本 | 是否使用 |
|---|---|---|---|---|
| 2.x 文档站（复数） | docs.agentscope.io | Mintlify | 2.0.4 / 2.0.5dev | 本教程唯一来源 |
| 1.x 文档站（单数） | doc.agentscope.io | Sphinx | 1.0.21 | 不要使用 |
记忆要点：复数 docs. 对应 2.x，单数 doc. 对应 1.x。
PyPI Documentation 链接错误
PyPI 项目页的 "Documentation" 字段指向的是单数站 doc.agentscope.io（1.0.21），不是 2.x 文档。这是已确认的 错误指向：PyPI 抓取结果显示 documentation_link 为 https://doc.agentscope.io/。GitHub README 则正确指向复数站 docs.agentscope.io。遇到版本相关内容时，始终 以 docs.agentscope.io 为准。
dev 默认版本领先 PyPI
docs.agentscope.io 的默认版本是 2.0.5dev，路径形如 /versions/2.0.5dev/en/...，它跟随 main 分支，领先于 PyPI 已发布的 2.0.4。这意味着文档站默认版本中出现的 API 可能尚未发布到 PyPI。锁定到 2.0.4 版本视图（路径 /versions/2.0.4/en/...）可以与本教程基线对齐；若使用默认 dev 版本，遇到新 API 时需对照 GitHub 源码确认是否已随 2.0.4 发布。
Python 要求
- 2.x 要求 Python
>=3.11（PyPIrequires-python字段确认）。 - 1.x 要求 Python
>=3.10。 - 部分第三方博客与旧教程仍写 "Python 3.10"，那是 1.x 的要求，不适用于 2.x。在 3.10 环境下
pip install agentscope==2.0.4会因版本约束失败。
安装方式概览
基础安装：
bash
# 推荐：使用 uv
uv pip install agentscope
# 或使用 pip
pip install agentscope关键可选 extras（完整列表与各 extra 的精确依赖以 PyPI 项目页为准）：
| extras | 用途 |
|---|---|
full | 全部运行时依赖合集 |
dev | 开发与测试工具链 |
gemini | Google Gemini 模型集成 |
ollama | Ollama 本地模型集成 |
xai | xAI（Grok）模型集成 |
models | 额外模型后端依赖 |
service | Agent Service（FastAPI 服务化） |
storage | 持久化存储后端 |
s3 | S3 对象存储后端 |
workspace | Workspace 沙箱后端 |
tools | 额外工具依赖 |
rag | RAG 检索增强 |
milvuslite | Milvus Lite 向量库 |
mem0 | Mem0 长期记忆集成 |
reme | ReMe 长期记忆集成 |
在 macOS / Linux 的 zsh、bash 等 shell 下，方括号会被解释为通配符，需要转义：
bash
uv pip install agentscope\[full\]
# 或加引号
uv pip install 'agentscope[full]'详细安装步骤、虚拟环境搭建与模型配置见 安装与环境。
生态边界
AgentScope 的生态不止 Python 主线，但本教程只覆盖 Python 2.x。其他语言 SDK 的定位如下， 不在本教程范围内：
| 生态 | 包名 / 仓库 | 定位 |
|---|---|---|
| TypeScript SDK | @agentscope-ai/agentscope（npm） | 消费 Agent Service 的 SSE 流，面向前端集成 |
| Java 版 | agentscope-ai/agentscope-java | JVM 侧实现，v2.0.0 GA 于 2026-07-10 |
与其他 Agent 框架的定位差异
一句话区分：LangChain / LangGraph 提供模型抽象与可编排的图运行时，CrewAI 侧重角色化 多 Agent 协作约定，Deep Agents 是建立在 LangChain/LangGraph 之上的长任务 Harness； AgentScope 则以事件驱动 reply / reply_stream、统一 Toolkit、Permission 三态决策与 Workspace 沙箱为差异化支点，并自带 FastAPI 多租户 Agent Service 与 Leader-Worker Agent Team。它们并非互斥，但在"安全拦截、沙箱执行、服务化多租户"这一组合上，AgentScope 的 默认开箱程度更高。
迁移提示
如果你有 1.x 项目需要迁移到 2.x，不要试图原地升级。两套 API 的 Agent 基类、工具管理、消息与 事件模型都已重写，且无自动迁移工具。请前往 1.x 到 2.x 迁移 章节按对照表逐项改写。
过时信息警示：部分 Changelog / FAQ 页面仍写着 "RAG & long-term memory migration in progress"，但 RAG 能力已于 2.0.3 落地、长期记忆（LTM）于 2.0.4 落地。遇到这类描述时，以 Release Notes 与 源码 为准，不要被 "in progress" 文案误导。