Appearance
核心概念
AgentScope 2.x 不把能力堆进一个巨大的基类，而是由一组可组合的 building block 构成。 每个块职责单一、有明确的导入路径与替换点。本页给出 2.x 的全景心智模型，让你在深入各 分组前先知道每个块的位置，以及一次 reply() 调用如何把这些块串起来。
版本基线：本文以 Python
agentscope 2.0.4（PyPI，2026-07-07）为准，要求 Python>=3.11。1.x 的ReActAgent、__call__、agentscope.memory、agentscope.pipeline、MsgHub、hooks、state_dict等在 2.x 中已移除或重构， 不再出现。
核心构建块全景
下表按"消息与执行 → 工具与计划 → 上下文与安全 → 知识与记忆 → 部署"的顺序列出 2.x 的 核心构建块。前端类比只用来建立直觉，实现细节以"原生语义"段落为准。
| 构建块 | 职责 | 关键类 | 前端类比 | 对应章节 |
|---|---|---|---|---|
| Msg / Event | 消息载体与流式事件 | Msg、UserMsg、AssistantMsg、SystemMsg；TextBlock/DataBlock/ThinkingBlock/ToolCallBlock/ToolResultBlock/HintBlock；ReplyStartEvent、TextBlockDeltaEvent 等 | SSE chunk | 核心构建块 |
| Agent | 无状态 ReAct 循环引擎 | Agent、ContextConfig（reply/reply_stream/observe/compress_context） | React Component | 核心构建块 |
| Model | 模型调用抽象与多提供商适配 | DashScopeChatModel、OpenAIChatModel；DashScopeCredential 等 | fetch adapter / provider | 核心构建块 |
| Formatter | 把多 Agent 对话序列化为模型输入 | FormatterBase、OpenAIChatFormatter、OpenAIMultiAgentFormatter | 请求序列化层 | 核心构建块 |
| Tool | 函数工具与内置工具的统一装配 | Toolkit、FunctionTool、ToolGroup、Bash、Read、Write、Edit | npm 聚合 | 核心构建块 |
| MCP | 接入外部 MCP 服务作为工具来源 | MCPClient、StdioMCPConfig、HttpMCPConfig | 外部 API client | 核心构建块 |
| State / Plan | Agent 状态容器与任务计划管理 | AgentState、Task、TaskContext、TaskCreate/TaskGet/TaskList/TaskUpdate | Redux Store | 核心构建块 |
| Context | 上下文压缩与卸载，管理 token 预算 | ContextConfig、Offloader（通常即 Workspace） | 虚拟列表 / 分页 | 上下文与安全 |
| Middleware | 洋葱模型横切关注点 | MiddlewareBase、TracingMiddleware、RAGMiddleware、AgenticMemoryMiddleware | Koa 洋葱 | 上下文与安全 |
| Permission | 工具执行前三态决策（允许 / 拒绝 / 询问） | PermissionContext、PermissionMode | Express auth middleware | 上下文与安全 |
| Workspace | 工具执行的沙箱后端 | LocalWorkspace、DockerWorkspace、E2BWorkspace | Docker 容器 | 上下文与安全 |
| RAG | 检索增强生成，以 Middleware 注入知识 | RAGMiddleware | 搜索结果注入 | 知识与记忆 |
| Long-Term Memory | 跨会话长期记忆 | AgenticMemoryMiddleware（支持 Mem0 / ReMe 后端） | IndexedDB | 知识与记忆 |
| Agent Service | FastAPI 多租户部署与 SSE 对外暴露 | Agent Service | BFF / 后端服务 | 工程化 |
| Agent Team | Leader-Worker 多智能体协作 | Agent Team | Web Worker 协调 | 工程化 |
一次 reply() 的数据流
Agent.reply() 是 2.x 的核心入口。下表给出一轮 ReAct 循环中各步骤的发生顺序与涉及的 构建块。Middleware 以洋葱模型包裹整个流程，可在任意步骤前后插入追踪、RAG、记忆等逻辑。
| 步骤 | 发生什么 | 涉及构建块 |
|---|---|---|
| 1 | Agent.observe 把输入 Msg 与历史注入上下文 | Msg、Agent、Context |
| 2 | Formatter 把上下文序列化为模型输入，调用 Model 生成回复或工具调用 | Model、Formatter、Middleware（前置） |
| 3 | 若模型返回工具调用，Toolkit 装配的工具经 Permission 三态决策 | Tool、MCP、Permission |
| 4 | 被允许的工具在 Workspace 沙箱中执行，结果以 ToolResultBlock 回灌 | Workspace、Msg |
| 5 | 接近 token 上限时 ContextConfig 触发压缩，或把大结果卸载到 Offloader | Context、Workspace |
| 6 | 循环结束，reply() 返回最终 Msg；reply_stream() 产出结构化事件 | Msg、Event |
reply() 与 reply_stream() 共享同一条 ReAct 管线，区别只在输出形式：前者同步聚合为 一条 Msg，后者以 ReplyStartEvent、TextBlockDeltaEvent 等事件流式产出，适合接 SSE 或前端逐 token 渲染。
前端类比与原生语义
把上面的类比收拢来看：
Agent像带生命周期的 React Component，但 2.x 的Agent是无状态的 ReAct 引擎， 状态由AgentState持有，跨会话记忆以Middleware形式挂载，而不是写在实例上。Toolkit像按需聚合的 npm 包，但 2.x 统一管理函数工具、MCP 工具与 Skills，且每次 调用都经过Permission拦截，不是直接执行。Middleware像 Koa 洋葱，但 2.x 用它替代了 1.x 的 hooks，可观测性、RAG、长期记忆 都是MiddlewareBase的子类。Event流像 SSE chunk，但 2.x 的事件是结构化的（TextBlockDeltaEvent、ToolCallBlock等），不是裸文本。Permission像 Express auth middleware，但 2.x 的三态决策（允许 / 拒绝 / 询问） 作用于工具执行前，是 Agent 安全的闸门。Workspace像 Docker 容器，但 2.x 的 Local / Docker / E2B 三后端同时承担工具执行 沙箱与上下文卸载落点两个角色。AgentState像 Redux Store，但 2.x 的状态与 Agent 实例解耦，可通过offloader持久化到Workspace。
AgentScope 原生语义：类比只用来建立直觉。2.x 的 Agent 是无状态 ReAct 循环引擎， 通过 reply() 同步返回最终 Msg，或 reply_stream() 异步产出结构化事件；工具、MCP、 Skills 统一由 Toolkit 装配并受 Permission 拦截；上下文压缩与卸载由 ContextConfig 与 Offloader（通常即 Workspace）承担；可观测性、RAG、长期记忆都以 Middleware 形式挂载。不要用 1.x 的 ReActAgent、__call__、MsgHub、hooks、state_dict 等 概念套 2.x。
去哪学
- 想看
Msg、Event、Agent、Model、Tool、MCP、Plan的 API 形状：见 核心构建块。 - 想理解上下文压缩、Middleware 洋葱、Permission 三态、Workspace 沙箱：见 上下文与安全。
- 想给 Agent 注入知识或长期记忆：见 知识与记忆。
- 想把 Agent 部署成服务或组装多智能体：见 工程化。
- 从 1.x 迁移过来：见 1.x 到 2.x 迁移。