您的位置首页 >人工智能 >

AgentScope 2.0 架构师深度指南(基础篇)

AgentScope 2.0 核心升级是新增 Harness 工程底座,把原来 1.0 版本单纯的智能体循环框架升级成面向企业长任务、可生产部署的智能体运行底座,架构师上手先理清分层结构、核心组件之间的依赖关系,再按先跑通本地 ReAct 基础智能体、再接入 Workspace 与中间件、最后部署 Agent Service 分布式服务的顺序落地,这套设计解决了旧版本很难直接上生产、长对话上下文容易溢出、工具执行缺少隔离和权限管控、多智能体协作状态难追踪这些痛点,你在做方案设计的时候,优先区分两套使用模式:轻量模式直接用原生 ReAct 做快速原型,企业生产模式启用完整 Harness 能力,按需开启沙箱、持久会话、记忆、子智能体编排,不用一次性加载全部组件。

一、AgentScope 2.0 整体分层架构

整体架构分成四层,底层是模型与消息基础层,中间是 ReAct 推理内核层,上层是 Harness 工程化层,最外层是 Agent Service 服务托管层,Harness 是 2.0 改动最大的部分,它包裹在 ReAct 内核外面,属于可选增强层,不会强制开发者使用。

分层核心组件主要作用
模型与消息基础层Model 模块、ContentBlock 消息模型、事件总线统一对接各类大模型、多模态消息封装、全链路流式事件输出
ReAct 推理内核层ReAct 循环、工具集、权限校验、HITL推理 + 动作执行循环,支持串行 / 并发调用工具,支持人工介入审批
Harness 工程层Workspace、Session、Memory、SubAgent、Sandbox、Middleware长任务状态管理、执行环境隔离、上下文自动压缩、子智能体编排、扩展钩子
Agent Service 托管层FastAPI 服务、多租户路由、会话持久化、调度能力把智能体包装成 HTTP 服务,支持多会话、断线重连、后台任务、定时任务

二、基础核心组件详解

2.1 ReAct 推理内核

这是整个框架的基础,保留了 1.0 的核心逻辑,同时新增了中断、恢复、批量工具执行能力。

  • 支持结构化输出,工具调用可以并发执行,缩短任务耗时
  • 自带中断恢复能力,运行到一半可以暂停,后续从当前状态继续执行
  • 所有执行步骤都会产生标准化事件,模型思考、工具调用、返回结果都能流式推送前端

2.2 Workspace 执行环境抽象

Workspace 的设计目标是把 “智能体业务逻辑” 和 “代码运行环境” 拆开,环境可以随时替换,不用改 Agent 代码。

  • 支持本地文件、Docker 沙箱、E2B 云沙箱多种后端,一行配置切换
  • 统一管理文件资源、MCP 服务、技能 Skill,支持按会话、用户、智能体隔离资源
  • 超大工具返回结果自动卸载到 Workspace,避免撑爆上下文窗口

2.3 Middleware 中间件机制

替换 1.0 松散的 Hook 机制,提供 5 个固定执行节点,属于架构扩展的核心入口。

  • 五个钩子节点:onAgent、onReasoning、onActing、onModelCall、onSystemPrompt
  • 常见使用场景:日志埋点、权限校验、动态注入提示词、上下文压缩、RAG 检索注入、模型调用统计
  • 中间件可以自由组合叠加,不会侵入内核代码,方便业务侧定制

2.4 Session 会话与 Memory 记忆

  • Session:保存单次任务全量状态,消息历史、任务进度,支持持久化存储,断线之后前端重连可以回放历史
  • Memory:可插拔长期记忆,内置 ReMe、Mem0 两种后端,由中间件挂载,区分临时会话上下文和跨会话长期记忆

2.5 HITL 人工介入

升级为一等能力,不是附加功能,工具执行前可以触发人工审批,用户修改参数、拒绝执行或者确认放行,智能体等待审批完成后继续往下跑,适合敏感操作场景。

三、架构师基础落地步骤

  1. 选型确认:评估场景,原型验证选纯 ReAct 轻量模式;企业生产、长周期任务、需要沙箱隔离、多租户服务,选择 Harness+Agent Service 模式
  2. 环境准备:Python 版本≥3.11,通过 uv 或者 pip 安装指定版本 agentscope,按需安装 full 全套依赖
  3. 基础原型开发:编写基础 ReAct 智能体,接入模型,注册工具,调试推理和工具调用链路
  4. 按需接入 Harness 组件:配置 Workspace 隔离、挂载需要的中间件、开启记忆、配置权限策略
  5. 多智能体编排:使用内置团队能力,主智能体调度子智能体分配子任务
  6. 服务化部署:启用 Agent Service,配置 Redis 做分布式状态存储,对外提供 SSE 流式接口
  7. 安全与运维加固:配置工具白名单、沙箱隔离、模型重试降级、会话过期清理策略

四、架构设计关键注意点

  • Harness 是可选层,不是必选,不要所有场景都强行开启全套 Harness 组件,会增加资源开销
  • 上下文压缩由中间件接管,架构设计时要区分自动压缩策略和手动压缩逻辑
  • 权限管控在工具调用链路前置校验,所有危险操作默认走审批 HITL 流程
  • 事件总线是对外对接 UI、A2A、AG-UI 协议的标准通道,不要自己单独封装消息推送逻辑
  • 分布式部署状态依赖 Redis,单节点简单测试可以使用内存模式,生产环境必须切换 Redis

【相关 FAQ】

问题 1:AgentScope 2.0 的 Harness 和 ReAct 内核是什么关系?

回答 1:AgentScope 2.0 的 Harness 是包裹在 ReAct 内核之上的可选工程增强层,ReAct 负责基础推理工具循环,Harness 负责长任务状态、沙箱、会话、编排这些生产能力,开发者可以单独只用 ReAct,也可以叠加开启 Harness 全部能力。

问题 2:AgentScope 2.0 的 Middleware 中间件能实现哪些 Agent 扩展能力?

回答 2:AgentScope 2.0 的 Middleware 中间件支持在智能体执行五个关键节点插入自定义逻辑,能实现权限校验、日志追踪、动态提示词注入、上下文压缩、RAG 结果注入、模型调用限流与监控等扩展,并且不会改动 ReAct 内核代码。

问题 3:AgentScope 2.0 的 Workspace 解决了架构上什么痛点?

回答 3:AgentScope 2.0 的 Workspace 把智能体业务逻辑和执行环境解耦,解决了工具运行环境难隔离、大结果挤占上下文、资源权限不好管控的痛点,支持本地、容器、云沙箱环境无缝切换。

问题 4:AgentScope 2.0 对比 1.0 版本架构最大改动在哪?

回答 4:AgentScope 2.0 相比 1.0 架构最大改动就是新增 Harness 底座,重构消息模型、换成标准化 Middleware、原生支持事件流式、内置 HITL 和权限体系,定位从单纯智能体开发框架升级成企业级智能体运行底座。

【参考资料】

[2026-09-08](AgentScope v2.0.8 版本更新日志)AgentScope 官方文档

[2026-07-20](AgentScope 2.0 生产可用,企业级 Harness 底座全解析)阿里云开发者社区

[2026-05-25](AgentScope 2.0 正式发布公告)AgentScope 官方文档

[2026-11-11](从智能体框架到 Harness 底座:AgentScope 项目新定位)阿里云社区

【免责声明】

本文仅为 AgentScope 2.0 架构学习参考文档,不构成生产落地的工程承诺;框架功能、接口、能力随版本迭代持续变动,生产实施请以 AgentScope 官方最新文档和 Release Note 为准;文中架构方案仅为基础思路,企业上线前需要完成安全测试、压力测试、权限审计。

今日大家都在搜的词: