AgentScope 源码架构分析报告

AgentScope 是阿里巴巴通义实验室开源的生产级 AI Agent 框架，截至 2026 年 7 月 GitHub 已获约 22.6k Stars、2.3k Forks。本文基于 AgentScope 2.0 实际源码（main 分支）进行深度架构分析。

一、项目总览

1.1 基本信息

1.2 设计哲学

AgentScope 2.0 的官方定位是 "production-ready, easy-to-use agent framework with essential abstractions"。其核心设计原则：

• 先建模后扩展：Msg（消息）、State（状态）、Event（事件）、Toolkit（工具）作为基础抽象
• 非入侵式架构：不约束模型调用方式，让框架适配模型能力的增长
• 生产级安全：沙箱隔离、权限控制、上下文压缩、会话恢复

1.3 核心源码行数统计

二、Agent 架构：从继承体系到配置驱动

AgentScope 2.0 的智能体架构与 1.0 版本完全不同。2.0 移除了 AgentBase/ReActAgent/RealtimeAgent 的继承体系，改用单一 Agent 类 + 配置驱动模式。

from agentscope.agent import Agent           # 统一 Agent 类
from agentscope.agent import ContextConfig    # 上下文配置
from agentscope.agent import ModelConfig      # 模型配置（含 Fallback）
from agentscope.agent import ReActConfig      # ReAct 循环配置

Agent 构造函数

class Agent:
    def __init__(
        self,
        name: str,                                      # Agent 标识
        system_prompt: str,                              # 系统提示词
        model: ChatModelBase,                            # 模型实例
        toolkit: Toolkit | None = None,                  # 工具注册中心
        middlewares: list[MiddlewareBase] | None = None, # 中间件链
        state: AgentState | None = None,                 # Agent 状态
        offloader: Offloader | None = None,              # 上下文卸载器
        model_config: ModelConfig | None = None,         # 模型配置
        context_config: ContextConfig | None = None,     # 上下文压缩配置
        react_config: ReActConfig | None = None,         # ReAct 循环配置
    )

核心方法

_reply_impl 核心流程（源码 575-725 行）

_reply_impl 入口
  │
  ├─ Step 1: 检查输入类型
  │    ├─ UserConfirmResultEvent / ExternalExecutionResultEvent → 继续
  │    └─ Msg / None → 新回复
  │
  ├─ Step 2: 处理事件或更新上下文
  │
  ├─ Step 3: ReAct 循环（while cur_iter < max_iters）
  │    ├─ _check_next_action() → exit / reasoning
  │    ├─ reasoning → 上下文压缩 → _reasoning()
  │    │    ├─ 输出 Msg（无工具调用）→ 完成
  │    │    └─ 输出工具调用事件 → 继续
  │    ├─ _batch_tool_calls() → 分批执行
  │    │    ├─ sequential：顺序执行
  │    │    ├─ concurrent：并发执行
  │    │    ├─ 需确认 → RequireUserConfirmEvent
  │    │    └─ 需外部执行 → RequireExternalExecutionEvent
  │    └─ cur_iter += 1
  │
  ├─ Step 4: 达到 max_iters → ExceedMaxItersEvent
  └─ 正常退出 → ReplyEndEvent + Msg

三、事件流系统（30+ 事件类型）

2.0 版本最关键的新模块。所有事件继承自 EventBase(Pydantic BaseModel)，使用 EventType(StrEnum) 枚举。

设计特点：所有事件类型化，文本/数据/思考/工具均支持 Start-Delta-End 三段式流式输出，权限确认和执行分离为独立事件类型。

四、Workspace：不只是沙箱，是整个运行时抽象

Workspace 是 AgentScope 2.0 中最大（3,143 行/9 个文件）也是最关键的模块之一。

class WorkspaceBase:
    async def initialize(self) -> None      # 初始化
    async def close(self) -> None           # 关闭
    async def reset(self) -> None           # 重置

    # MCP 管理
    async def list_mcps(self) -> list[MCPClient]
    async def add_mcp(self, mcp_client) -> None
    async def remove_mcp(self, name) -> None

    # Skill 管理
    async def list_skills(self) -> list[Skill]
    async def add_skill(self, skill_path) -> None

    # 上下文卸载
    async def offload_context(self, session_id, msgs) -> str
    async def offload_tool_result(self, tool_call_id, result) -> str

支持三种后端：LocalWorkspace（本地）、DockerWorkspace（Docker 容器）、E2BWorkspace（云端沙箱）。代码无需修改即可切换运行环境。

五、权限引擎：规则驱动的 6 种检查模式

规则系统支持三类规则：deny（拒绝）、ask（询问）、allow（允许）。用户确认时可以选择记住该决策，自动添加为规则。

六、中间件系统：6 个钩子点

class MiddlewareBase:
    async def on_reply(self, agent, input_kwargs, next_handler)
    async def on_reasoning(self, agent, messages, next_handler)
    async def on_acting(self, agent, tool_calls, next_handler)
    async def on_model_call(self, agent, model, messages, next_handler)
    async def on_system_prompt(self, agent, system_prompt, next_handler)
    async def on_compress_context(self, agent, input_kwargs, next_handler)

内置中间件：RAGMiddleware（自动检索注入）、BudgetMiddleware（Token 预算控制）、TTSMiddleware（语音合成注入）。

七、多 Agent 协作

AgentScope 支持多种多 Agent 协作模式：

• MsgHub 消息中心：支持 broadcast / send_to / round_robin 三种分发模式
• Agent Team：Leader-Worker 模式，内置 Team Tool 协调 Worker 通信
• Pipeline 工作流：sequential_pipeline（顺序）/ fanout_pipeline（扇出）
• Supervisor 调度：Supervisor Agent 调度多个 Worker Agent

八、与主流框架对比

总结

AgentScope 2.0 的核心竞争力：

• 先抽象后扩展 — 22 个核心模块各司其职，消息、状态、事件、工具等抽象层清晰
• 事件驱动架构 — 从黑盒调用到实时事件流，Agent 执行过程完全可观测、可交互
• 生产级安全 — Workspace 隔离、权限引擎、中间件链、会话恢复
• 开放协议 — 原生 MCP + A2A，与其他框架和工具互通
• 完整生态 — Studio → Runtime → QwenPaw → OpenJudge → ReMe 全链路覆盖

与 LangChain 生态的区别：AgentScope 选择的是"建造一个连贯的框架"，而非"搭建一系列可拼装的库"。架构一致性带来的理解和维护成本更低。

AgentScope 2.0 适合的场景：长期稳定运行的 AI Agent 服务、多 Agent 协作与复杂任务编排、企业级安全隔离要求、对可观测性要求高的生产系统、需要 MCP + A2A 多协议互通的场景。

参考来源：GitHub 源码分析、官方文档、社区博客。本文内容基于 Apache 2.0 许可协议的开源项目。