AgentScope 2.0 深度解析：从架构到实战

本文基于 AgentScope 2.0.9 源码与官方文档，结合实际代码探索，带你从顶层到底层理解这款生产级智能体框架。

一、AgentScope 2.0 是什么？

AgentScope 2.0 是阿里巴巴通义实验室开发的生产级智能体框架，将多租户、多会话管理和分布式部署作为一等公民原生支持。

四个关键词概括其设计理念：

安全：工具审计 + 人机协同（Human-in-the-Loop）权限系统 + 沙箱隔离，三位一体
高效：工具并发/顺序智能调度，保证正确性前提下大幅提升执行效率
灵活：智能体与工具双重中间件，无需修改核心逻辑即可定制运行时行为
完备：从轻量级 UI、SDK 到多租户后端及分布式部署的完整工具链

⚠️ AgentScope 2.0 是一次全面重构，官方提供了更新日志供参考。

二、全景架构

graph TB
    subgraph "应用层"
        APP[Agent Service<br/>FastAPI 后端]
        TUI[Terminal UI<br/>终端交互]
        CONSOLE[Console<br/>富文本渲染]
        CHANNEL["消息渠道<br/>飞书 / 钉钉 / Discord"]
    end

    subgraph "编排层 (Pipeline EXP)"
        TEAM[TeamPipeline<br/>队长→成员委派]
        GOAL[GoalPipeline<br/>执行者↔验证者迭代]
        SOP[SOP Engine<br/>标准作业流程]
    end

    subgraph "智能体层"
        AGENT["Agent<br/>统一 ReAct 引擎"]
        RT[RealtimeAgent<br/>实时语音]
        A2A[A2AAgent<br/>跨 Agent 通信]
    end

    subgraph "中间件层"
        MW["6 个 Hook 位置<br/>on_reply / on_reasoning / on_acting<br/>on_model_call / on_compress_context<br/>on_system_prompt + list_tools"]
        MW_IMPL["TracingMiddleware / BudgetControl<br/>TTSMiddleware / ModelRouter<br/>AgenticMemory / RAGMiddleware<br/>ReMeMiddleware / Mem0Middleware"]
    end

    subgraph "工具层"
        TK[Toolkit]
        FT[FunctionTool]
        MCP_T[MCPTool]
        SKILL[Skill]
        GROUP[ToolGroup]
        BUILTIN["Bash / Read / Write / Edit<br/>Grep / Glob / Task*"]
    end

    subgraph "模型层"
        MODEL[ChatModelBase]
        PROVIDERS["DashScope / OpenAI / Anthropic<br/>Gemini / DeepSeek / Ollama ..."]
        CRED[Credential 凭证管理]
        FMT[Formatter 格式化]
    end

    subgraph "消息与事件"
        MSG["Msg 消息<br/>content = ContentBlock 列表"]
        BLOCKS["TextBlock / ThinkingBlock<br/>ToolCallBlock / ToolResultBlock<br/>DataBlock / HintBlock"]
        EVENT["Event 事件流<br/>27 种事件类型<br/>Start → Delta → End"]
    end

    subgraph "基础设施"
        STATE[AgentState 状态管理]
        PERM[Permission 权限引擎]
        WS[Workspace 工作空间<br/>Local / Docker / E2B / K8s]
        RAG[KnowledgeBase 知识库]
        EMBED[Embedding 向量嵌入]
    end

    APP --> AGENT
    TUI --> AGENT
    CONSOLE --> AGENT
    CHANNEL --> APP

    TEAM --> AGENT
    GOAL --> AGENT
    SOP --> AGENT

    AGENT --> MW
    MW --> MW_IMPL
    AGENT --> TK
    TK --> FT
    TK --> MCP_T
    TK --> SKILL
    TK --> GROUP
    TK --> BUILTIN

    AGENT --> MODEL
    MODEL --> PROVIDERS
    MODEL --> CRED
    MODEL --> FMT

    AGENT --> MSG
    MSG --> BLOCKS
    AGENT --> EVENT

    AGENT --> STATE
    AGENT --> PERM
    AGENT --> WS
    MW_IMPL --> RAG
    RAG --> EMBED

官方文档导航结构：快速开始 → 核心模块 → 智能体即服务

三、核心模块详解

3.1 消息与事件 — 两种基础数据结构

官方文档：消息与事件

消息（Msg） 是智能体间通信与上下文持久化的基本单元。事件（Event） 是前后端交互与流式传输的基本单元。

消息：内容块列表

v2 的核心变化之一：Msg.content 从字符串变成了有序内容块列表，原生支持多模态。

from agentscope.message import UserMsg, AssistantMsg, SystemMsg

# 字符串自动包装为 TextBlock
user_msg = UserMsg(name="user", content="这张图片里有什么？")

# 消息角色约束：
# - user 消息只能包含 TextBlock 和 DataBlock
# - system 消息只能包含 TextBlock
# - assistant 消息可包含所有块类型

6 种内容块：

块类型	说明
`TextBlock`	纯文本
`DataBlock`	多模态数据（图片/音频/视频），base64 或 URL
`ThinkingBlock`	模型推理过程（思维链）
`ToolCallBlock`	工具调用，含名称、输入和状态
`ToolResultBlock`	工具执行结果
`HintBlock`	提示信息（调度任务、团队消息、后台工具结果）

事件：Start → Delta → End

一次 reply_stream 产出一系列事件，遵循 start → delta → end 模式：

ReplyStartEvent
  → ModelCallStartEvent
    → TextBlockStartEvent
    → TextBlockDeltaEvent (×N)    ← 流式文本片段
    → TextBlockEndEvent
  → ModelCallEndEvent
  → ToolCallStartEvent            ← 如有工具调用
  → ToolCallEndEvent
  → ToolResultStartEvent
  → ToolResultEndEvent
ReplyEndEvent

关键设计：事件与消息是同一数据的两种视图。通过 msg.append_event(event) 可以从事件流增量重建完整消息，即使连接中断也能从检查点重放恢复。

from agentscope.event import ReplyStartEvent, TextBlockDeltaEvent, ReplyEndEvent

msg = None
async for event in agent.reply_stream(user_msg):
    if isinstance(event, ReplyStartEvent):
        msg = AssistantMsg(name=event.name, content=[], id=event.reply_id)
    elif isinstance(event, TextBlockDeltaEvent):
        print(event.delta, end="", flush=True)  # 流式打印
    elif isinstance(event, ReplyEndEvent):
        print("\n[完成]")

    if msg is not None:
        msg.append_event(event)  # 增量重建消息

AgentScope 还提供 TypeScript 版本的消息和事件元语，前端可用相同的 appendEvent API 重建消息。

3.2 智能体 — 统一的 ReAct 引擎

官方文档：智能体概述 · 配置智能体 · 运行智能体

v2 不再有 ReActAgent、DialogAgent 等多个类，统一为 Agent，内置完整的 ReAct 推理-行动循环。

核心接口

方法	说明
`reply(inputs, structured_schema)`	运行 ReAct 循环，返回最终`Msg`
`reply_stream(inputs, structured_schema)`	同上，但流式产出`AgentEvent`
`observe(msgs)`	将消息添加到上下文，不触发推理
`compress_context()`	超阈值时压缩上下文

主循环

1
2
3

输入消息/事件 → 检查下一步动作 → 推理(LLM调用) → 需要工具?
                                                  ├─ 是 → 权限检查 → 执行工具 → 回到推理
                                                  └─ 否 → 返回最终消息

创建智能体

from agentscope.agent import Agent
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential
from agentscope.tool import Toolkit, Bash, Read, Write, Edit

agent = Agent(
    name="Friday",
    system_prompt="You are a helpful assistant named Friday.",
    model=DashScopeChatModel(
        credential=DashScopeCredential(
            api_key=os.getenv("DASHSCOPE_API_KEY"),
        ),
        model="qwen-plus",
    ),
    toolkit=Toolkit(tools=[Bash(), Read(), Write(), Edit()]),
)

# 方式一：等待最终消息
reply_msg = await agent.reply(UserMsg(name="user", content="Hello!"))

# 方式二：流式获取事件
async for event in agent.reply_stream(user_msg):
    match event.type:
        case EventType.TEXT_BLOCK_DELTA:
            print(event.delta, end="", flush=True)
        case EventType.TOOL_CALL_START:
            print(f"\n[正在调用 {event.tool_call_name}...]")

配置体系

配置类	作用
`ReActConfig`	推理-行动循环控制（max_iters、中断行为等）
`ContextConfig`	上下文管理（压缩触发比、保留比等）
`ModelConfig`	模型调用参数（重试次数等）
`InjectionConfig`	信息注入控制

三种 Agent 类型

类型	用途
`Agent`	通用智能体，内置 ReAct 循环
`RealtimeAgent`	实时语音智能体，支持 VAD + TTS
`A2AAgent`	跨 Agent 通信，通过 AgentCard 协议交互

3.3 工具 — 智能体的双手

官方文档：工具概述 · Python 函数工具 · MCP · Skill

Toolkit 统一管理四种工具来源：

from agentscope.tool import Toolkit, Bash, Read, Write, FunctionTool
from agentscope.mcp import MCPClient, StdioMCPConfig

# 1. 内置工具
toolkit = Toolkit(tools=[Bash(), Read(), Write(), Edit()])

# 2. Python 函数工具
@FunctionTool
def search_web(query: str) -> str:
    """搜索网页"""
    return "搜索结果..."

# 3. MCP 工具
mcp_client = MCPClient(
    config=StdioMCPConfig(command="npx", args=["-y", "@some/mcp-server"])
)
toolkit = Toolkit(mcps=[mcp_client])

# 4. Skill 技能包
toolkit = Toolkit(skills_or_loaders=["path/to/skill"])

工具组（ToolGroup） 是 v2 的新概念：一组工具可以作为整体被激活或停用，智能体在运行时通过内置元工具 ResetTools 自主控制。

MCP 集成

MCP（Model Context Protocol）是 v2 的重要新增能力。两种通信配置：

from agentscope.mcp import MCPClient, StdioMCPConfig, HttpMCPConfig

# Stdio：子进程标准 IO 通信（本地）
MCPClient(config=StdioMCPConfig(command="npx", args=["-y", "some-server"]))

# HTTP：远程服务通信（分布式）
MCPClient(config=HttpMCPConfig(url="http://localhost:8000/mcp"))

MCPClient 连接后，远程工具自动包装为 MCPTool，对 Agent 透明——Agent 调用本地函数和远程工具的方式完全一致。

3.4 中间件 — 无侵入式扩展

官方文档：中间件

中间件是 v2 的重要新增能力，在不修改智能体核心逻辑的前提下注入横切逻辑。

6 个 Hook 位置

Hook	类型	说明
`on_reply`	洋葱式	包裹完整 reply 流程
`on_reasoning`	洋葱式	包裹推理步骤
`on_acting`	洋葱式	包裹工具调用执行
`on_model_call`	洋葱式	包裹底层 LLM API 调用
`on_compress_context`	洋葱式	包裹上下文压缩
`on_system_prompt`	变换式	串行修改系统提示词
`list_tools`	工具来源	贡献工具给 Toolkit

嵌套关系：

on_reply
  └─ ReAct 循环（每一轮）
       └─ on_compress_context（上下文压缩判定）
            └─ on_reasoning
                 └─ on_system_prompt（组装 system prompt）
                      └─ on_model_call（LLM 调用）
                 └─ on_acting（每个工具调用一次）

内置中间件

中间件	场景	文档
`TracingMiddleware`	OpenTelemetry 链路追踪	—
`ReplyBudgetControlMiddleware`	Token 预算控制	—
`TTSMiddleware`	语音合成	—
`ModelRouterMiddleware`	按输入复杂度自动选择模型	—
`AgenticMemoryMiddleware`	原生长期记忆（Markdown 文件）	长期记忆
`RAGMiddleware`	检索增强生成	RAG
`ReMeMiddleware`	ReMe 驱动的文件型记忆	长期记忆
`Mem0Middleware`	Mem0 驱动的记忆后端	长期记忆

from agentscope.middleware import TracingMiddleware, ReplyBudgetControlMiddleware

agent = Agent(
    name="assistant",
    system_prompt="...",
    model=model,
    middlewares=[
        TracingMiddleware(),
        ReplyBudgetControlMiddleware(token_budget=10000),
    ],
)

3.5 流水线 — 多智能体编排

官方文档：流水线概述 · 目标流水线 · 团队流水线

⚠️ 流水线模块处于实验阶段，接口可能调整。

流水线的核心设计：固化运行逻辑，对外收敛为与单个智能体相同的形态。PipelineProtocol 要求实现 reply_stream()，与 Agent 接口一致——凡是接受 Agent 的地方都可以传入 Pipeline。

两种实现

GoalPipeline — 执行者 ↔ 验证者迭代优化：

from agentscope.pipeline import GoalPipeline

pipeline = GoalPipeline(
    executor=coder_agent,      # 执行者：写代码
    verifier=reviewer_agent,   # 验证者：审查代码
    max_iters=5,               # 最多迭代5轮
)
# coder 产出 → reviewer 审查 → 不通过则带理由退回 → coder 修改 → 再审查 → 通过

TeamPipeline — 队长 → 成员委派协作：

from agentscope.pipeline import TeamPipeline, TeamMember

team = TeamPipeline(
    leader=manager_agent,
    members=[
        TeamMember(agent=coder_agent, description="负责编写代码"),
        TeamMember(agent=tester_agent, description="负责测试"),
    ],
)
# manager 收到需求 → 调用 TeamAssign 工具分派给 coder → 结果回给 manager
# manager 再分派给 tester → 结果回给 manager → manager 汇总

关键区别：TeamPipeline 中成员之间互不可见，结果只回给队长。如果需要多对多广播等自定义消息路由模式，可以用 observe() + reply() + asyncio.gather() 手动实现。

3.6 长期记忆 — 跨会话记忆

官方文档：长期记忆

v2 通过中间件实现长期记忆，三种实现：

实现	原理	特点
`AgenticMemoryMiddleware`	Markdown 文件 + 智能体自主管理	原生实现，”渐进暴露”
`ReMeMiddleware`	ReMe 嵌入进程，自动提取记忆	自动写回，无需手动操作
`Mem0Middleware`	mem0 驱动	开箱即用

Agentic Memory 的工作方式很独特：智能体通过内置的 Read/Write/Edit 工具自主创建和维护 Markdown 记忆文件，MEMORY.md 作为索引自动注入系统提示。这是一种”渐进暴露”的实现——智能体先看到索引，再按需读取具体记忆文件。

ReMe 的集成有两条路径：

进程内嵌入（ReMeMiddleware）：无需启动服务，中间件自动监听对话并写回记忆
服务化集成（MCP）：ReMe 作为独立服务运行，Agent 通过 MCP 协议远程调用

ReMe 的三种检索模式：

模式	行为
`static_control`	后台自动检索，以 HintBlock 注入上下文
`agent_control`	暴露`memory_search` 工具，智能体按需搜索
`both`	同时启用自动检索和搜索工具

3.7 权限系统 — 三位一体的安全防线

官方文档：权限系统概述 · 权限模式 · 权限规则

v2 新增完整的权限系统，控制工具执行的细粒度门控：

权限模式	说明
`DEFAULT`	默认模式，按规则判断
`ACCEPT_EDITS`	自动允许编辑类操作
`EXPLORE`	探索模式，只读
`BYPASS`	跳过所有权限检查
`DONT_ASK`	不询问用户，直接拒绝

3.8 工作空间 — 安全沙箱隔离

官方文档：工作空间概述

v2 新增 Workspace 抽象，支持在物理隔离的安全环境中执行代码：

实现	环境
`LocalWorkspace`	本地文件系统
`DockerWorkspace`	Docker 容器
`E2BWorkspace`	E2B 云沙箱
`K8sWorkspace`	Kubernetes 集群
`DaytonaWorkspace`	Daytona 平台
`BubblewrapWorkspace`	Bubblewrap 沙箱
`AppleContainerWorkspace`	Apple 容器

支持用户、智能体、会话三级隔离，适合多租户生产环境。

3.9 智能体即服务 — 生产级部署

官方文档：架构 · 智能体团队 · 消息渠道

v2 新增基于 FastAPI 的智能体服务后端：

多租户多会话并发管理
SessionManager / SchedulerManager / BackgroundTaskManager 生命周期管理
Redis 存储后端
可视化前端 + 开发 SDK
消息渠道集成：飞书 / 钉钉 / Discord
MCP 与技能中心：集中管理 MCP 服务和技能
资源共享：多租户间共享资源

四、学习路径建议

graph LR
    A["1. 安装<br/>pip install agentscope"] --> B["2. 第一个 Agent<br/>reply + reply_stream"]
    B --> C["3. 添加工具<br/>FunctionTool / 内置工具"]
    C --> D["4. 理解事件<br/>EventType + 流式渲染"]
    D --> E["5. 中间件<br/>Tracing / Budget / RAG"]
    E --> F["6. Pipeline<br/>TeamPipeline / GoalPipeline"]
    F --> G["7. 高级特性<br/>权限 / 工作空间 / MCP"]
    G --> H["8. 部署<br/>Agent Service / 消息渠道"]

步骤	目标	参考文档
1	安装并验证	快速开始
2	创建最简 Agent 并对话	智能体概述
3	添加自定义工具和内置工具	工具概述
4	监听事件流实现流式输出	消息与事件
5	使用中间件扩展能力	中间件
6	构建多智能体协作	流水线
7	权限控制和安全沙箱	权限系统·工作空间
8	生产级部署	智能体即服务

五、核心思想总结

AgentScope 2.0 的核心是：一个统一的 Agent + 两套数据结构 + 三个扩展点。

一个 Agent：Agent 类内置 ReAct 循环，不再有多个 Agent 类
两套数据结构：Msg（通信单元）+ Event（流式传输单元），同一数据的两种视图
三个扩展点：
- Tool — 让 Agent 能行动
- Middleware — 让 Agent 更智能
- Pipeline — 让多个 Agent 协作

把这三件事玩明白，AgentScope 2.0 就学通了 80%。其余的（权限、工作空间、A2A、实时语音、消息渠道）都是锦上添花。

参考链接

资源	链接
官方文档（中文）	https://docs.agentscope.io/zh/versions/2.0.9
GitHub 仓库	https://github.com/agentscope-ai/agentscope
ReMe 记忆工具箱	https://github.com/agentscope-ai/ReMe
快速开始	https://docs.agentscope.io/zh/versions/2.0.9/quickstart
更新日志	https://docs.agentscope.io/zh/versions/2.0.9/others/change-log
智能体概述	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/agent/overview
消息与事件	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/message-and-event
中间件	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/middleware
流水线	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/pipeline/overview
工具概述	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/tool/overview
MCP 集成	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/tool/mcp
长期记忆	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/long-term-memory
权限系统	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/permission-system/overview
工作空间	https://docs.agentscope.io/zh/versions/2.0.9/building-blocks/workspace/overview
智能体即服务	https://docs.agentscope.io/zh/versions/2.0.9/deploy/agent-service
消息渠道	https://docs.agentscope.io/zh/versions/2.0.9/deploy/channel/overview