AgentScope 2.0 架构报告

版本: 2.0.2 · 组织: 阿里通义实验室 SysML 团队 · 许可: Apache 2.0
定位: 面向生产环境的多智能体框架，提供灵活而健壮的多智能体编排能力。

一、整体架构总览

AgentScope 2.0 采用分层 + 插件化架构，由上至下分为四层：

层次	职责	核心模块
服务层 (Service)	生产部署入口，REST API，任务调度，会话管理	`app/` (FastAPI), `app/_router/`, `app/_service/`
编排层 (Orchestration)	Agent 主循环 (ReAct)，消息事件流，中间件管线	`agent/_agent.py`, `event/`, `middleware/`, `state/`
能力层 (Capabilities)	模型接入、工具执行、沙箱、记忆、权限	`model/`, `tool/`, `workspace/`, `permission/`, `skill/`
基础设施 (Infrastructure)	持久化、实时通信、凭据管理	`app/storage/`, `app/message_bus/`, `credential/`

graph TB
    subgraph 用户入口
        UI["Web UI (React 19 + Vite)"]
        CLI["Python SDK"]
    end

    subgraph 服务层 Service
        APP["FastAPI App Factory<br/>create_app()"]
        R1["/agent<br/>智能体模板"]
        R2["/chat<br/>对话推理"]
        R3["/session<br/>会话管理"]
        R4["/schedule<br/>定时调度"]
        R5["/credential<br/>凭据管理"]
        R6["/model<br/>模型探查"]
        R7["/workspace<br/>工作区管理"]
        R8["/tts_model<br/>语音模型"]
    end

    subgraph 编排层 Orchestration
        AGENT["Agent 主循环<br/>ReAct Think→Act→Observe"]
        EVT["事件系统<br/>EventBase → 30+ 事件类型"]
        MID["中间件管线<br/>Budget / Mem0 / Tracing / TTS"]
    end

    subgraph 能力层 Capabilities
        MODEL["ChatModelBase<br/>8+ 模型提供商"]
        TOOL["ToolBase<br/>内置工具 / MCP / Function"]
        WORK["WorkspaceBase<br/>Local / Docker / E2B"]
        PERM["PermissionEngine<br/>安全门控"]
        SKILL["Skill<br/>可复用技能"]
    end

    subgraph 基础设施 Infrastructure
        STORAGE["Storage<br/>RedisStorage"]
        BUS["MessageBus<br/>RedisMessageBus"]
        CRED["CredentialFactory<br/>8+ 凭据实现"]
        MCPCLI["MCPClient<br/>Stdio / HTTP"]
    end

    UI --> APP
    CLI --> APP
    APP --> R1 & R2 & R3 & R4 & R5 & R6 & R7 & R8
    R1 --> AGENT
    R2 --> AGENT
    R4 --> AGENT
    AGENT --> MID
    MID --> MODEL
    MID --> TOOL
    MID --> PERM
    AGENT --> EVT
    AGENT --> WORK
    AGENT --> SKILL
    TOOL --> WORK
    TOOL --> MCPCLI
    R3 --> STORAGE
    R5 --> CRED
    STORAGE --> REDIS[(Redis)]
    BUS --> REDIS

二、核心模块详解

2.1 Agent 主循环 (`agent/_agent.py`)

Agent 是框架的核心。它实现了一个异步 ReAct (Think → Act → Observe) 循环：

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant M as ChatModel
    participant T as Toolkit
    participant W as Workspace
    participant E as EventBus

    U->>A: reply(msg)
    A->>E: ReplyStartEvent
    loop ReAct Loop (max_iters)
        A->>+M: model_call(msgs)
        M-->>-A: streamed tokens
        A->>E: TextBlockDeltaEvent / ThinkingBlockDeltaEvent
        A->>+T: parse & execute tool calls
        T->>+W: sandbox execute
        W-->>-T: result
        T-->>-A: ToolResponses
        A->>E: ToolResultEndEvent
        alt 需要用户确认
            A->>E: RequireUserConfirmEvent
            U-->>A: ConfirmResult
        end
    end
    A->>E: ReplyEndEvent
    A-->>U: AssistantMsg

核心设计要点：

流式事件驱动 — Agent 的每一步（模型调用、工具开始/结束、文本增量、思考过程）都发出事件，前端可通过 Server-Sent Events (SSE) 实时订阅。
工具批处理 — _ToolCallBatch 并行执行一批工具调用，并在 ReAct 循环的下一轮将结果一并喂回模型。
确认门控 — 可配置在执行特定工具前暂停，等待用户确认或外部审批。
可定制 Agent 类 — create_app() 接受 custom_agent_cls 参数，允许替换为自定义 Agent 实现。

2.2 事件系统 (`event/`)

事件是 AgentScope 2.0 的神经中枢，所有组件的交互都通过事件进行：

EventBase
├── ReplyStartEvent / ReplyEndEvent         ← Agent 回复生命周期
├── ModelCallStartEvent / ModelCallEndEvent ← 模型调用
├── TextBlockStart/Delta/End                ← 文本流式输出
├── ThinkingBlockStart/Delta/End             ← 模型思维链
├── ToolCallStart/Delta/End                  ← 工具调用
├── ToolResultStart/TextDelta/DataDelta/End ← 工具结果
├── RequireUserConfirmEvent                 ← 用户确认请求
├── CustomEvent                             ← 自定义事件
└── ExceedMaxItersEvent                     ← 超限终止

2.3 中间件管线 (`middleware/`)

中间件采用洋葱模型，在 Agent 的 reply() 前后执行横切逻辑：

中间件	功能
`ReplyBudgetControlMiddleware`	控制 token 预算，防止 Agent 无限运行
`Mem0Middleware`	长期记忆 (mem0 驱动)，自动提取和注入上下文
`TracingMiddleware`	OpenTelemetry 分布式追踪
`TTSMiddleware`	文本转语音后处理

graph LR
    subgraph Middleware Pipeline
        direction LR
        A["入口 reply()"] --> B["ReplyBudgetControl"]
        B --> C["Mem0 (记忆注入)"]
        C --> D["Agent ReAct Loop"]
        D --> E["Mem0 (记忆提取)"]
        E --> F["TTSMiddleware"]
        F --> G["TracingMiddleware"]
        G --> H["出口 reply()"]
    end

2.4 模型层 (`model/`)

统一抽象 ChatModelBase，为每个提供商提供独立实现：

graph BT
    subgraph Model Providers
        OAI["OpenAIChatModel"]
        ANTH["AnthropicChatModel"]
        DAS["DashScopeChatModel"]
        DPK["DeepSeekChatModel"]
        GEM["GeminiChatModel"]
        OLL["OllamaChatModel"]
        XAI["XAIChatModel"]
        MOO["MoonshotChatModel"]
        RES["OpenAIResponseModel<br/>(Structured Output)"]
    end
    subgraph Formatters
        FMT_OAI["ChatFormatter (OpenAI)"]
        FMT_ANTH["ChatFormatter (Anthropic)"]
        FMT_GEM["ChatFormatter (Gemini)"]
    end
    subgraph Core
        BASE["ChatModelBase"]
        CARD["ModelCard<br/>(YAML 模型卡片)"]
        USAGE["ChatUsage"]
        RESP["ChatResponse / StructuredResponse"]
    end

    BASE --> OAI & ANTH & DAS & DPK & GEM & OLL & XAI & MOO & RES
    OAI --> FMT_OAI
    ANTH --> FMT_ANTH
    GEM --> FMT_GEM
    CARD --> BASE
    BASE --> USAGE
    BASE --> RESP

每个模型提供商都有 YAML 格式的模型卡片（_models/*.yaml），定义了模型名称、上下文窗口、API 端点等元数据。

2.5 工具系统 (`tool/`)

graph TD
    subgraph ToolBox
        TOOLBASE["ToolBase (抽象基类)"]
        TOOLBASE -->|内置| BUILTIN["Bash / Edit / Read / Write / Glob / Grep"]
        TOOLBASE -->|任务管理| TASK["TaskCreate / TaskGet / TaskUpdate / TaskList"]
        TOOLBASE -->|适配器| MCP["MCPTool (任何 MCP 服务器)"]
        TOOLBASE -->|适配器| FUNC["FunctionTool (Python 函数)"]
    end
    subgraph 组合
        TG["ToolGroup<br/>逻辑分组"]
        TK["Toolkit<br/>Agent 挂载的工具集"]
    end
    TOOLBASE --> TG
    TG --> TK

MCPTool 是 MCP (Model Context Protocol) 适配器，可挂载任意 MCP 服务器作为工具。
FunctionTool 将任意 Python 函数一键包装为 Agent 工具。
内置工具 直接在实例中绑定到 workspace，在沙箱中执行。

2.6 工作区（沙箱）(`workspace/`)

实现	说明
`LocalWorkspace`	本地子进程执行，适用于开发调试
`DockerWorkspace`	Docker 容器隔离，适用于安全执行
`E2BWorkspace`	E2B 云沙箱，适用于云端部署
`Offloader`	MCP 网关卸载协议，将工具执行转发到外部服务

2.7 权限引擎 (`permission/`)

细粒度的工具调用安全门控：

PermissionMode (白名单/黑名单)
    → PermissionRule (匹配条件)
        → PermissionBehavior (允许/拒绝/需确认)
            → PermissionDecision (最终裁决)

支持 Bash 命令解析器 (permission_bash_parser)，可自动提取和匹配 shell 命令参数。

2.8 服务层 (`app/`)

FastAPI 应用工厂，是生产部署入口：

graph TB
    subgraph create_app()
        APP["FastAPI App"]
        LS["lifespan()<br/>AsyncExitStack 管理生命周期"]

        subgraph 8个路由
            R_A["/api/agent"]
            R_C["/api/chat"]
            R_S["/api/session"]
            R_SC["/api/schedule"]
            R_CR["/api/credential"]
            R_M["/api/model"]
            R_T["/api/tts_model"]
            R_W["/api/workspace"]
        end

        subgraph 服务组件
            S_CHAT["ChatService<br/>编排 Agent 回复"]
            S_SES["SessionService<br/>会话 CRUD"]
            S_REG["ChatRunRegistry<br/>运行追踪"]
            S_SCH["SchedulerManager<br/>定时任务"]
            S_RM["WakeupDispatcher<br/>CancelDispatcher"]
        end

        subgraph 基础设施
            ST["Storage<br/>RedisStorage + ORM"]
            MB["MessageBus<br/>RedisMessageBus"]
            WM["WorkspaceManager<br/>Local/Docker/E2B"]
        end

        subgraph 扩展点
            EX_A["自定义 Agent 类"]
            EX_M["自定义中间件"]
            EX_T["自定义工具工厂"]
            EX_S["自定义子 Agent 模板"]
            EX_C["自定义凭据"]
        end
    end

    APP --> LS
    APP --> R_A & R_C & R_S & R_SC & R_CR & R_M & R_T & R_W
    R_A --> S_REG
    R_C --> S_CHAT
    R_S --> S_SES
    R_SC --> S_SCH
    S_CHAT --> ST & MB & WM
    S_SES --> ST
    LS --> ST & MB & WM & S_SCH
    APP --> EX_A & EX_M & EX_T & EX_S & EX_C

存储层 (app/storage/) 采用 ORM 模式，模型包括：

模型	用途
`AgentRecord`	智能体配置持久化
`SessionRecord`	会话及其消息
`UserRecord`	用户信息
`TeamRecord`	团队/多智能体组织
`ScheduleRecord`	定时任务编排

2.9 实时通信 (`app/message_bus/`)

MessageBus 抽象 + RedisMessageBus 实现，提供：

收件箱投递 — 跨会话向 Agent 发消息
空闲唤醒 — 检测闲置会话并触发调度
取消调度 — 安全终止正在运行的 Agent 回复

三、完整运行时架构图

graph TB
    subgraph "外部用户"
        DEV["开发者 SDK"]
        WEB["Web UI (React)"]
    end

    subgraph "FastAPI Server"
        APP["create_app()"]
        APP --> ROUTERS["Routers"]

        subgraph "核心 Agent 运行时"
            AGT["Agent<br/>ReAct Loop"]
            EVT["Event Bus"]
            MID["Middleware Pipeline"]
            AGT --> MID
            MID --> AGT
            AGT --> EVT
        end

        ROUTERS --> AGT

        subgraph "基础设施"
            STO["RedisStorage"]
            MB["RedisMessageBus"]
            WM["WorkspaceManager"]
            CRED["CredentialFactory"]
        end

        subgraph "管理器"
            S_CHAT["ChatService"]
            S_SES["SessionService"]
            REG["ChatRunRegistry"]
            SCH["SchedulerManager"]
            DISP["Wakeup/Cancel Dispatchers"]
        end

        AGT --> S_CHAT
        S_CHAT --> STO & MB
        S_SES --> STO
        SCH --> STO & MB
    end

    subgraph "模型提供商"
        OPENAI["OpenAI / Azure"]
        ANTHROPIC["Anthropic"]
        DASHSCOPE["DashScope (通义)"]
        DEEPSEEK["DeepSeek"]
        GEMINI["Google Gemini"]
        OLLAMA["Ollama (本地)"]
        XAI["xAI"]
    end

    subgraph "工具执行"
        LOCAL["LocalWorkspace"]
        DOCKER["Docker Sandbox"]
        E2B["E2B Cloud Sandbox"]
        MCP_SRV["MCP Servers"]
    end

    subgraph "外部服务"
        REDIS[(Redis)]
        OTEL["OpenTelemetry<br/>Collector"]
        MEM0["mem0 Long-term<br/>Memory"]
    end

    AGT --> OPENAI & ANTHROPIC & DASHSCOPE & DEEPSEEK & GEMINI & OLLAMA & XAI
    AGT --> LOCAL & DOCKER & E2B
    AGT --> MCP_SRV
    AGT --> OTEL
    AGT --> MEM0
    STO --> REDIS
    MB --> REDIS

    WEB --> APP
    DEV --> APP

四、关键设计理念

统一 Agent 模型 — 不区分单智能体和多智能体。Agent 只是一个可被其他 Agent 调用的工具（通过 AgentCreate/TeamCreate 等团队工具），天然支持任意拓扑结构。
流式第一 — 从 Agent 循环到前端 SSE，全链路 streaming。EventBase 事件体系使前端可以获得毫秒级实时更新。
可插拔性第一 — create_app() 的所有依赖（存储、消息总线、工作区管理器、中间件、工具工厂、凭据提供者）都是可置换的抽象接口。
安全优先 — PermissionEngine 提供白名单/黑名单/需确认三级门控；WorkspaceBase 提供沙箱隔离；Bash 命令解析器可逐参数匹配。
OpenTelemetry 原生支持 — TracingMiddleware 开箱即用，支持通过 OTLP 导出追踪数据。

五、目录结构地图

src/agentscope/
├── __init__.py           # 包入口，logger + version
├── _version.py           # 版本号
├── _logging.py           # 结构化日志
├── _utils/               # 内部工具 (JSON修复, 音频, mixin)
├── agent/                # Agent 核心 (_agent.py ~96KB)
│   └── _config.py        # ContextConfig, ModelConfig, ReActConfig
├── model/                # ChatModelBase + 8+ 模型提供商
│   ├── _base.py          # 抽象基类
│   ├── _anthropic/       # Anthropic 实现 + 模型卡片
│   ├── _dashscope/       # 通义千问实现 + 模型卡片
│   ├── _gemini/          # Google Gemini
│   ├── ...               # 每个提供商一个子目录
│   └── formatter/        # 每个提供商的 Msg→API 格式化器
├── message/              # Msg, UserMsg, AssistantMsg, ContentBlock...
├── event/                # 30+ 事件类型
├── tool/                 # Toolkit, ToolBase, MCPTool, FunctionTool, 内置工具
├── middleware/            # 中间件管线 (Budget, Mem0, Tracing, TTS)
├── permission/           # PermissionEngine, Rule, Mode, Behavior
├── workspace/            # Local/Docker/E2BWorkspace, Offloader
├── app/                  # FastAPI 服务层
│   ├── _app.py           # create_app() 工厂函数
│   ├── _lifespan.py      # 异步生命周期管理
│   ├── _router/          # 8个 REST 路由
│   │   ├── _agent.py     # 智能体模板管理
│   │   ├── _chat.py      # 对话 API
│   │   ├── _session.py   # 会话 CRUD
│   │   ├── _schedule.py  # 定时任务
│   │   ├── _credential.py
│   │   ├── _model.py     # 模型探测
│   │   ├── _workspace.py
│   │   ├── _tts_model.py
│   │   └── _schema/      # Pydantic 请求/响应模型
│   ├── storage/          # StorageBase + RedisStorage + ORM
│   ├── message_bus/      # MessageBus + RedisMessageBus
│   ├── workspace_manager/ # 每个用户隔离的工作区管理
│   ├── _service/         # ChatService, SessionService
│   ├── _manager/         # ChatRunRegistry, BackgroundTask, Scheduler
│   ├── middleware/       # App 层中间件 (收件箱, 状态变更, 工具卸载)
│   ├── _tools/           # 团队工具 (AgentCreate, TeamCreate...)
│   └── deps.py           # FastAPI 依赖注入
├── credential/           # 8+ 凭据提供者 (Factory 模式)
├── embedding/            # 嵌入模型 (DashScope, OpenAI, Gemini, Ollama)
├── tts/                  # 文本转语音 (DashScope TTS, CosyVoice)
├── mcp/                  # MCP 客户端管理 (StdioMCPConfig, HttpMCPConfig)
├── state/                # AgentState, TaskContext, Task
├── skill/                # Skill 系统 (可复用的提示词模板)
├── exception/            # 自定义异常
└── types/                # 共享类型定义

六、总结

AgentScope 2.0 是一个面向生产的多智能体框架，其架构特点可归纳为：

Agent 中心化 — 统一 Agent 模型兼具思考、行动、观察能力，通过事件驱动与外部交互
沙箱安全 — Workspace 层隔离工具执行，权限引擎实现精细门控
生产就绪 — FastAPI 服务层 + Redis 持久化/消息总线 + 定时调度 + OpenTelemetry 可观测性
模型无关 — 统一 ChatModelBase 抽象，8+ 提供商，可插拔格式化器
工具生态 — 内置工具 + MCP 协议 + Function 适配器，三层工具能力
全链路流式 — 从模型 token 到前端 SSE，事件体系覆盖 Agent 每一步

一	二	三	四	五	六	日
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30	31

AgentScope 2.0 架构报告

一、整体架构总览

二、核心模块详解

2.1 Agent 主循环 (agent/_agent.py)

2.2 事件系统 (event/)

2.3 中间件管线 (middleware/)

2.4 模型层 (model/)

2.5 工具系统 (tool/)

2.6 工作区（沙箱）(workspace/)

2.7 权限引擎 (permission/)

2.8 服务层 (app/)

2.9 实时通信 (app/message_bus/)