AgentScope 概览

AgentScope 是阿里巴巴通义实验室 SysML 团队主导的多 Agent 框架。2.0（2026-05-25 发布）是一次 从底层重建的破坏性重构：消息、工具、工作区、权限、中间件与服务层全部重写，以"安全、高效、灵活、 完备"为目标，把多租户、多会话与分布式部署作为一等公民。它不是一个新模型，也不是 LangGraph 的 替代品，而是一套面向"需要沙箱、权限与服务化"的 Agent 全栈框架。

版本基线：本文以 Python agentscope 2.0.4（PyPI，2026-07-07）为准，要求 Python >=3.11。 该包在 PyPI 的分类仍为 4 - Beta，但官方在 2.x 文档首页明确称为 production-ready。Beta 分类 不等同于长期稳定承诺，生产接入前请固定版本号并跟踪 release notes。

四大支柱与核心能力

官方 2.x 文档首页以"安全 / 高效 / 灵活 / 完备"为四个设计目标，落地为五项核心能力。下表给出每项 能力的职责与直接使用时机。

层级	负责什么	何时直接使用
ReAct Agent	ReAct 推理与工具执行的自主 Agent，内置 HITL 监督与工具编排	需要一个能自主规划并调用工具的 Agent
Toolkit	Agent 自管理的工具系统，统一 Python 函数、MCP 与 Skills	需要混合本地函数、MCP 服务与 Skills
Context	上下文压缩、卸载与 agentic 检索，支持 Mem0 / ReMe 等第三方后端	长任务上下文易超限，需要压缩与长期记忆
Sandbox Isolation	在 Local / Docker / E2B / K8s 等隔离环境执行工具，支持用户 / Agent / 会话级隔离	工具会执行代码或写文件，需要安全边界
Agent as Service	一键启动多租户、多会话后端，含前端 UI 与开发 SDK	需要把 Agent 作为 HTTP 服务对外提供

这五项能力不是独立卖点，而是同一条执行链上的不同环节。

一个可运行 Agent 的组成

下面这张图说明一次 reply / reply_stream 调用如何穿过四大支柱，把"模型 + 工具"组装成一个 受控、可观测、可服务化的执行过程。

关键节点：

• Agent（ReAct 循环） 是核心引擎。它消费 Msg，调用模型生成推理与工具调用，再把工具结果 回灌进上下文，直到产出最终回复。
• Toolkit 把 Python 函数（FunctionTool）、MCP 工具（MCPTool）与 Skills 统一成同一套 注册与选择机制，Agent 不需要关心工具来源。
• Permission 在工具真正执行前做三态决策（allow / deny / ask），是"安全"支柱的拦截点。
• Workspace 是工具的实际执行环境，也是上下文卸载的落地存储；Local / Docker / E2B 共享同一 Agent 面向的 API。
• Context 在上下文逼近上限时压缩历史、把大结果卸载到 Workspace，避免 OOM 与信息全量丢失。
• 输出侧通过 reply() 同步返回最终 Msg，或 reply_stream() 产出结构化事件流。

前端类比

如果你来自前端：

• 把 Agent 类比为一个带生命周期的 React Component——它接收输入（Msg），内部维护状态 （上下文与 ReAct 循环），产出输出（reply / reply_stream）。
• 把 Toolkit 类比为按需聚合的 npm 包：本地函数、MCP 服务、Skills 都是被它"安装"进来的 依赖，Agent 只看到统一的工具接口。
• 把 Middleware 类比为 Koa / Redux 的洋葱模型：Tracing、RAG、长期记忆、预算控制都以 中间件形式包裹 Agent 的执行，非侵入式扩展。
• 把 Event 流类比为 SSE chunk：reply_stream 产出的是结构化事件（文本块、工具调用、 工具结果、思考块），前端可以逐帧渲染。

AgentScope 原生语义：Agent 是无状态的 ReAct 循环引擎，状态显式由 AgentState 管理； reply() 同步返回最终 Msg，reply_stream() 异步产出结构化事件。工具、MCP、Skills 统一由 Toolkit 装配并受 Permission 三态拦截；上下文压缩与卸载由 ContextConfig 与 Offloader （通常即 Workspace）承担；可观测性、RAG、长期记忆都以 Middleware 形式挂载。这套语义和 React 的"组件 = 纯函数 + Hooks"不同：Agent 本身就是运行时，中间件不是副作用钩子，而是包裹 整个执行链的洋葱层。

默认提供什么

安装 agentscope 2.0.4 后，开箱即得：

1. 统一的 Agent 类：通过 reply / reply_stream 暴露同步与流式两种调用，事件流原生支持 HITL 确认与中断恢复。
2. 统一的 Toolkit：Python 函数、MCP 服务、Skills 都是"一等公民"，ToolGroup 支持按需 激活，ResetTools 让 Agent 运行时切换工具集。
3. Permission 三态决策：allow / deny / ask，配合路径规则与 Bash 静态分析，在工具 执行前拦截。
4. 三后端 Workspace：LocalWorkspace / DockerWorkspace / E2BWorkspace 共享同一 Agent 接口，可按安全需求替换。
5. Model + Credential 解耦：凭据集中在 credential 模块，模型层覆盖 DashScope / OpenAI / Anthropic / Gemini / DeepSeek / Moonshot / xAI / Ollama 等，并支持 OpenAIResponseModel。
6. Agent Service 与 Agent Team：create_app 一键启动 FastAPI 多租户后端，Leader-Worker 模式 的 Agent Team 内置于服务层。

以下能力不是无条件默认开启，需要显式装配：

• 沙箱执行需要选择 DockerWorkspace 或 E2BWorkspace，默认 LocalWorkspace 不提供强隔离。
• RAG、长期记忆、Token 预算、Tracing 都以 Middleware 形式按需挂载。
• 多租户分布式部署需要 Redis 后端与消息总线，单进程内嵌消息总线仅适合开发。
• A2A 适配目前为开发期预览（Resource Sharing、Workspace Manager），尚无稳定 shipped 适配器。

不应误解为什么

• 不是自动可靠性开关：更多工具与中间件也会扩大失败面，权限与沙箱只降低事故半径，不保证 成功。
• 不是权限系统的替代：Permission 只在工具执行前做三态决策，真正的访问控制仍由凭据、网络、 沙箱与文件系统共同决定。
• 不是无限上下文：Context 的压缩与卸载是预算管理，不是扩容，细节仍可能丢失。
• 不是单一产品：SDK、WebUI、Agent Service、Workspace Manager 与 Agent Team 有不同职责， 不要把任意一者当成 AgentScope 的全部。

什么时候适合使用

适合 AgentScope 2.x 的场景通常同时具备多个特征：

• 工具会执行代码、读写文件或访问网络，需要沙箱与权限拦截。
• 任务多轮、上下文易超限，需要压缩、卸载与长期记忆。
• 需要把 Agent 作为多租户 HTTP 服务对外提供，或需要 Leader-Worker 多 Agent 协作。
• 希望统一管理 Python 函数、MCP 服务与 Skills，而不是为每种工具写适配。

与其他主流框架的定位差异：

框架	定位	何时更合适
LangChain create_agent	轻量 Agent 循环	单 Agent + 工具，不需要沙箱与服务化
LangGraph	状态图运行时	流程拓扑需精确控制，自定义节点 / 边 / 分支
CrewAI	角色协作框架	多角色任务委派，注重角色描述与协作
Deep Agents	LangGraph 上的长任务 Harness	规划 + 文件 + 子 Agent 的长任务
AgentScope 2.x	事件驱动全栈 Agent 框架	需要沙箱隔离、权限拦截与多租户服务化

反过来，如果只是"调用一个工具后返回结果"，LangChain create_agent 更直接；如果流程拓扑必须由 应用代码完全决定，直接用 LangGraph 更清晰。

学习路径

1. 用本页建立完整心智模型。
2. 在 版本与生态 固定版本基线，避开 1.x / 2.x 双站陷阱。
3. 在 安装与环境 完成环境与模型配置。
4. 用 核心概念 建立 building block 全景心智模型。
5. 跟着 快速上手 创建第一个 Agent，观察 reply_stream。
6. 深入 核心构建块：消息与事件、模型、Agent、工具与 MCP、结构化 输出、计划模式。
7. 进入 上下文与安全：上下文压缩、中间件、权限、Workspace 沙箱。
8. 学习 知识与记忆：RAG、长期记忆、Agent Skills。
9. 走向 工程化：状态与会话、流式事件、可观测性、Agent Service、 Agent Team。
10. 最后在 1.x 到 2.x 迁移 与 研究型 Agent 实战 中组合实战。

先修

• LangChain Agent - 理解模型、工具与 Agent 循环
• LangGraph 概览 - 了解状态与持久化运行基础

下一步

• AgentScope 版本与生态

官方参考

• What's AgentScope 2.0?
• AgentScope GitHub 仓库
• Release Notes
• 1.x 到 2.x Changelog