目录：
1. 面向生产环境的智能体工程平台
2. 快速上手 从零构建生产级智能体
3. Agent —— 智能体的核心抽象与工程化实践
4. Message & Event —— 消息模型与事件流深度解
5. Middleware —— 无侵入式智能体扩展机制深度解析
6. Model —— 统一模型接入层与容错机制深度解析
7. Permission System —— 权限控制系统深度解析
8. Tool —— 工具系统架构与生产级实践深度解析
9. Context —— 运行时上下文与状态管理深度解析
一、概述
AgentScope Java 2.0 是阿里巴巴通义实验室推出的面向生产环境运行智能体的完整平台。它从"构建一个智能体"的工具箱，升级为覆盖智能体全生命周期的工程底座。
本次升级围绕三大核心主题展开：
| 主题 | 核心定位 |
|---|---|
| Harness 工程化 | 长期运行、复杂任务的工程底座 |
| 企业级分布式部署 | 多租户、安全隔离、无状态水平扩展 |
| 底层框架升级 | 更轻、更正交、更顺手的核心抽象 |
兼容性说明：AgentScope Java 2.0 尽量保持了对 1.x 版本的兼容，确保大部分用户的平滑升级；但同时带来了 API 层面的不兼容变更，在核心抽象、API 和架构上均有大幅改进。
二、Harness 工程化 —— 长期运行、复杂任务的工程底座
裸的 ReAct 循环只解决"一次推理"。真实任务往往要跑数小时、积累大量状态、依赖可持续沉淀的能力。Harness 把这套工程基础设施一次给齐：核心推理循环原样保留，能力按需叠加，让智能体能稳定长跑、能力越用越强、能从容完成复杂作业。
2.1 自进化与技能仓库
成功模式以Markdown 技能自动沉淀到 workspace/skills/，每轮按需加载、跨会话共享——know-how 在每次运行之间累积。这意味着智能体不再是一次性对话工具，而是具备持续学习和能力积累的工程实体。
2.2 分层记忆管理
AgentScope 2.0 设计了三层记忆架构：
┌─────────────────────────────────────────────┐ │ Layer 1: 上下文对话（Context Dialogue） │ ├─────────────────────────────────────────────┤ │ Layer 2: Agent 自维护的 MEMORY.md │ ├─────────────────────────────────────────────┤ │ Layer 3: 磁盘事实流水账（Fact Log） │ └─────────────────────────────────────────────┘- 自动压缩控制 prompt 体量，避免上下文溢出
- memory_* 工具提供显式回忆能力，让智能体按需检索历史
2.3 子智能体（Subagent）
在 Markdown 里声明子 agent 规格，运行时按需 agent_spawn / agent_send，支持：
- 同步调用：等待子 agent 返回结果
- 后台委派：后台终态经 system-reminder 反向推送，无需轮询
2.4 上下文自动管理（Compaction）
这是解决长任务上下文膨胀的关键机制：
| 策略 | 说明 |
|---|---|
| 结构化压缩 | 保留目标 / 状态 / 关键发现 / 下一步 |
| 超大工具结果落盘 | 只留占位符，避免 prompt 膨胀 |
| ContextOverflow 兜底重试 | 最后防线，确保系统不崩溃 |
2.5 复杂任务规划（Plan Mode）
只读规划态编排长任务；计划文件持久化到 workspace/plans/ 并驱动执行，让意图与动作解耦。智能体先"想清楚"再"动手做"。
2.6 Workspace 工程底座
人格、知识、技能、子 agent 规格、会话日志全部以磁盘Markdown / JSON表达，每轮自动注入 system prompt。这是一个文件系统即智能体状态的设计哲学。
三、企业级分布式部署
生产环境的智能体要服务多租户、要安全运行不可信工具代码、要在滚动发布时不丢失在途上下文。AgentScope 2.0 天然面向无状态水平扩展。
3.1 多租户隔离
支持 session / user / agent / org 多维度状态隔离。RuntimeContext 的键贯穿：
- 工作区路径
- KV 命名空间
- 沙箱状态槽
3.2 安全沙箱执行
工具执行限定在隔离环境内，支持三种模式：
| 模式 | 适用场景 |
|---|---|
| 本地子进程 | 轻量工具、开发调试 |
| Docker | 中等隔离需求 |
| 远端 AgentRun | 高安全要求、弹性扩缩 |
支持快照与恢复，长任务能在进程重启后继续。
3.3 工具权限管控
权限三态决策模型：
允许（Allow） ──→ 直接执行 审批（Approve） ──→ 人工确认后执行 拒绝（Deny） ──→ 阻断执行综合静态规则、工具类型、输入分析进行决策；敏感工具强制人工审批，HITL（Human-in-the-Loop）是框架内生能力。
3.4 优雅上下线与会话恢复
同一 (userId, sessionId) 在任意进程恢复完整对话。AgentStateStore 支持多种后端：
- 内存（开发调试）
- JSON 文件（单机持久化）
- MySQL（生产级）
- Redis（高性能缓存）
支撑零停机滚动发布与崩溃恢复。
四、底层框架升级 —— 更轻、更顺手的核心抽象
4.1 事件流式输出原生支持
每一步——模型调用、文本增量、工具执行、工具结果——都以类型化事件流出。订阅一次，前端 UI 实时跟上。
ModelCallEvent → TextDeltaEvent → ToolCallEvent → ToolResultEvent4.2 更简洁的消息模型
文本、文件、图片、音视频、模型思考、工具结果统一收敛到一个 ContentBlock；按 role 严格校验，非法消息在构造期就被拦下。
4.3 Middleware 取代松散 Hook
五个明确阶段取代 v1 的扁平 hook：
| Middleware 阶段 | 职责 |
|---|---|
| onAgent | Agent 生命周期 |
| onReasoning | 推理阶段 |
| onActing | 行动阶段 |
| onModelCall | 模型调用 |
| onSystemPrompt | 系统提示词构建 |
每个关注点各居其层，组合干净利落。
4.4 HITL 一等公民
可在执行中确认工具参数、审批敏感操作，或把执行交给外部系统。智能体在暂停点等待并精确恢复，无需自己搭脚手架。
五、集成生态
AgentScope 2.0 提供了丰富的集成能力：
| 类别 | 集成项 |
|---|---|
| 记忆 | Mem0、百炼记忆、ReMe |
| 状态存储 | MySQL、Redis、OSS |
| RAG 知识库 | Simple、百炼、Dify、HayStack、RAGFlow |
| 技能仓库 | Git、MySQL、PostgreSQL |
| 智能体协议 | A2A、AG-UI、Agent Protocol |
| 基础设施 | Higress、Nacos、Scheduler |
| 生态扩展 | Chat Completions Web、Studio、在线训练 |
六、总结
AgentScope 2.0 的核心设计哲学可以概括为：
从"跑通一个 Demo"到"稳定运行一个生产系统"。
它通过 Harness 工程化解决长期运行问题，通过企业级分布式部署解决规模化问题，通过底层框架升级解决开发体验问题。三者共同构成了一个面向生产环境的智能体工程平台。
