序言：AgentScope 2.0 与如何使用本书
本章导读：当你想让 Java 应用不只是“调用一次模型、返回一段文本”，而是拥有一个能查订单、更新工单、中途还会向你确认的智能体（Agent，能自主调用模型与工具、持续完成任务的程序）时，你需要的是一个智能体开发框架——本书介绍的 AgentScope 2.0 正是为此设计的开源框架。本序言先说明它的定位。接着对比两种使用方式——AgentScope Harness（以 SDK 形式嵌入自己应用的开发包）与 AgentScope Service（由平台代为运行 Agent 的托管服务）。最后给出全书结构与按角色划分的学习路线。读完本序言，你就能决定从哪一章读起，以及以哪种方式把框架接入自己的项目。
AgentScope 2.0 是什么
AgentScope 2.0 是面向智能体应用的开源开发框架，帮助你把模型、工具和业务数据组织成能够持续执行任务的 Agent。你可以用它构建多轮对话助手，也可以让 Agent 检索资料、处理文件、运行代码、委派子任务，在需要时等待人的确认，再继续完成工作。拿一个具体例子来说：客服助手里用户问“我的订单到哪了”，Agent 要调用订单工具查询进度，可能还要更新工单，拿不准时先向用户确认，再把事情办完——而不是返回一段固定文案。这就是“持续执行任务”与“调用一次模型”的区别。
本书介绍它的 Java 版本。你可以将 Agent 直接嵌入现有 Java 或 Spring Boot 应用，从一次调用开始，逐步加入上下文管理、工作区（Workspace，以文件形式存放 Agent 的人格、知识与技能的目录）、持久会话和多 Agent 协作；需要统一部署和对外提供 API 时，还可以使用 AgentScope Service。
Harness 与 Service：两种使用方式
AgentScope 2.0 提供两种彼此独立、可按需选择与组合的使用方式：AgentScope Harness（SDK，自主开发——把框架作为依赖嵌进你的工程，Agent 逻辑由你用代码定制）与 AgentScope Service（平台，托管服务——Agent 由平台统一运行，业务应用通过 API 使用它）。需要在应用代码中深度定制 Agent，选择前者；希望专注业务接入、由平台统一运行 Agent，选择后者。Service 上的托管 Agent（Managed Agent，配置在平台上、由平台代为运行的 Agent）基于 AgentScope HarnessAgent 内核，两种方式共享同一执行内核。
| 方式 | 你如何开发 | 谁管理运行 | 适合谁 |
|---|---|---|---|
| AgentScope Harness（SDK · 自主开发） | 将 SDK 嵌入自己的 Java 或 Spring Boot 应用，组合上下文、工作区与工具执行，自主定制 Agent 逻辑 | 你自己的应用，负责部署与运维 | 需要嵌入 Java 应用、自定义运行逻辑的团队 |
| AgentScope Service（平台 · 托管服务） | 在平台上配置 Managed Agent，或接入自己部署的 Agent、连接已有的 Coding Agent；具备相应任务能力的 Agent 还可以组成 Team 或参与 Workflow | Service 平台统一管理 Agent 运行时；业务应用通过 API 提交工作、查询结果、接收事件与处理待办 | 希望专注业务接入、减少重复运行时建设的团队 |
两种方式不必一起使用：可以只用 Harness SDK 开发并运行自己的 Agent 应用，也可以直接在 Service 中配置 Managed Agent，无需先开发一个 SDK 应用。已有的 Harness 应用还可以作为 External Agent（进程留在自己手里、注册接入平台的外部 Agent）接入 Service，保留自己的运行进程，同时使用平台的发布与调用能力。
注意：AgentScope Service 当前为预览能力，正式版本尚未发布；使用 Java SDK 构建和运行 Agent 不依赖部署 Service。Service 的部署与使用详见第 29-34 章。
本书结构与学习路线
选定了使用方式，下一步是规划学习路径。本书共七篇 44 章，外加两个附录，按“核心构建块 → 工程能力 → 生态集成 → 平台托管 → 语义判断 → 生产实践”的层次组织（其中“语义判断”指用模型评判回答是否有依据、工具选择是否合适这类问题，对应第六篇）：
| 篇章 | 内容 | 适合谁 | 预计阅读时长 |
|---|---|---|---|
| 第一篇 起步（第 1-3 章） | 框架概览、快速开始、核心概念地图 | 所有读者 | 约 1 小时 |
| 第二篇 核心构建块（第 4-10 章） | Agent 与 ReAct 循环、消息与事件、模型、工具、上下文、中间件、权限系统 | 需要理解与定制 Agent 行为的开发者 | 约 4 小时 |
| 第三篇 Harness 工程能力（第 11-20 章） | Harness 架构、工作区、上下文管理、记忆、技能、子 Agent、计划模式、沙箱、会话、渠道 | 构建长任务与生产级应用的开发者 | 约 6 小时 |
| 第四篇 生态与集成（第 21-28 章） | 模型提供商、RAG、会话存储与分布式、IM 渠道、Agent 协议、Skill 仓库等 | 按需选读的集成内容 | 按需查阅 |
| 第五篇 AgentScope Service 平台（第 29-34 章） | Service 部署、托管 Agent、Session API、Team 与 Workflow 编排、运维 | 平台建设者与业务接入方 | 约 5 小时 |
| 第六篇 JEV 语义判断（第 35-38 章） | 为什么需要独立判断、判断的生命周期、三个判断域精讲、评估与校准 | 关注输出质量与评估的读者 | 约 3 小时 |
| 第七篇 生产实践（第 39-44 章） | 如何构建 Agent Harness、最佳实践、走向生产、跨境电商平台实战、FAQ | 准备上线的团队 | 约 4 小时 |
| 附录 | Release Notes 与术语表 | 随查随用 | 工具性 |
按读者画像，推荐三条学习路线：
- Java 应用开发者：顺序阅读第 1-20 章（第一至三篇），建立完整的应用内开发能力；之后按需补充第 22 章（RAG 集成——RAG 即检索增强生成，先检索外部资料、再让模型据此作答）、第 24 章（会话存储与分布式部署）与第 42 章（走向生产）。
- 平台建设者：先读第 1-3 章建立概念，再进入第 29-34 章（第五篇）完成 Service 的部署、托管 Agent 配置与编排；需要理解托管内核时回读第 11-20 章。
- 关注质量与评估的读者：读完第 1-3 章后，可直接进入第 35-38 章（第六篇）。
开始前的准备
动手运行书中示例需要 JDK 17 及以上版本、Maven 3.9+，以及所选模型的 API 凭据；工具可以在本地或配置的沙箱（sandbox，与主机隔离的执行环境）中执行，环境搭建步骤见第 2 章。从 1.x 升级的读者，可参考附录 A 的 Release Notes 了解各版本的具体变化。