Spring AI · 第12节 · Agent 编排与 AgentScope

九

Agent 编排与 AgentScope

Agent & AgentScope

前面的 AI 是"一问一答"。Agent 是"能自己思考、自己用工具、自己记得之前干了啥"的 AI。它接到一个任务（比如"帮我写一份行业报告"），会自己拆步骤：先搜索资料、再整理、再写作、再检查——中间自己决定调哪个工具。单个 Agent 不够时，让多个 Agent 协作，就是 AgentScope 干的事。

论一个 Agent 的四要素

大脑（LLM）：做决策的核心。

工具（Tools）：能调的外部能力——搜索、查数据库、发邮件。

记忆（Memory）：记得之前的对话和做过的事。

规划（Planning）：把大任务拆成小步骤，一步步执行。

AgentScope：阿里开源的多 Agent 框架，让多个 Agent（比如"搜索 Agent"和"写作 Agent"）像同事一样协作。Spring AI 偏"单应用里调模型"，AgentScope 偏"多智能体编排"，两者可以结合用。具体 API 以 AgentScope 官方最新文档为准。

想象中的多 Agent 协作流程（研究助手）

// 任务：写一份"2026 年微服务趋势"报告
// 1. 搜索 Agent：自己调搜索工具，收集 5 篇资料
// 2. 写作 Agent：读这些资料，写成报告初稿
// 3. 评审 Agent：检查报告有没有事实错误
// 4. 三个 Agent 通过 AgentScope 互相对话，最后产出成稿

// Spring AI 这边负责把工具（搜索、查库）注册成 @Tool
// AgentScope 负责编排这几个角色怎么对话、谁先谁后
// 具体接入代码以 spring-ai-alibaba + AgentScope 官方示例为准

Agent 的角色与协作模式

多 Agent 协作常见两种模式，了解一下就行：

模式	怎么协作
流水线（Sequential）	一个 Agent 干完交给下一个：搜索 Agent → 写作 Agent → 评审 Agent。像工厂流水线。
对话（Conversation）	两个 Agent 互相讨论，比如"正方"和"反方"辩论，最后收敛出结论。

每个 Agent 有自己的 system prompt（角色）、自己能调的工具、自己的记忆。AgentScope 负责管它们之间传消息、谁先说话、什么时候停。具体 API 以 AgentScope 官方最新文档为准——这个生态还在快速迭代，本文不编造具体类名。

Agent 的记忆怎么管

Agent 干长任务时会记住中间结果——"我刚才搜了哪几篇、写作 Agent 交了初稿"。这种记忆分两种：短期记忆（当前任务的上下文，任务结束就丢）和长期记忆（跨任务记住用户偏好，存数据库/向量库）。学习阶段先用内存短期记忆，真做产品再上长期记忆。记忆别无限涨，跟聊天历史一样要截断和摘要，否则 token 爆炸。

什么时候才真的需要多 Agent

多 Agent 是个坑，别上来就用。判断标准：

单 Agent 够了	考虑多 Agent
一个任务、一类工具。	任务要拆成不同角色干。
AI 自己能一步步完成。	需要"专家"之间讨论/审查。
调试简单，日志能看懂。	单 Agent 已无法满足质量要求。

绝大多数客服、文档问答、信息抽取场景，单 Agent + 几个 @Tool + RAG 就够了。多 Agent 留到真的有"研究报告自动生成"这种复杂需求再上。

别为了 Agent 而 Agent

能"一问一答 + 几个 @Tool"解决的事，就别上多 Agent。多 Agent 协作调试极痛苦——它俩吵架、死循环、互相传错信息，排查起来比写业务代码累十倍。先从单 Agent + 工具开始，真的需要分工协作再上 AgentScope。

AgentScope 是什么：阿里开源的 Agent 全家桶

用一句官网原话："Where Agents Come Alive"——一个"开发、评估、托管、进化"Agent 的开源栈。它不只是个框架，而是覆盖 Agent 全生命周期的一整套东西。关键更新：它现在多语言了，有 agentscope-java（JVM 版），Java 团队不用绕到 Python 也能玩。

成员	定位
agentscope-core（Python）	核心框架，构建"看得见、能理解、可信任"的 Agent。
agentscope-java	面向 JVM 的 Agent 编程框架：推理、工具集成、记忆、多 Agent 协作，直接服务 Java 企业应用。
agentscope-ts	TypeScript 版，为 Agent 系统而生。
ReMe	记忆管理工具包：文件 + 向量双通道，让 Agent 跨会话记得用户偏好。
OpenJudge	统一评估框架，50+ 生产级评判器，给 Agent 输出打分。
agentscope-studio	面向开发者的可视化调试工具，看一次 Agent 运行全过程。

核心概念：Agent / Message / Tool / Workflow / Service

Agent → 一个有角色、有工具、有记忆的智能体

每个 Agent 有自己的 system prompt、能调的工具、独立的记忆。

大白话：一个有岗位说明书、有工具箱、有笔记本的员工。

Message → Agent 之间传的消息

结构化消息（角色 + 内容 + 工具调用），是协作的"公文"。

解析：多 Agent 协作的本质，就是互相收发标准消息。

Tool → 能力

搜索、查库、调 API，和 Spring AI 的 @Tool 是一个思路。

2.0 新特性：多模型调用、重试、fallback、工具权限边界。

Workflow / Service → 编排与托管

把多个 Agent 按流程串起来；Agent Service 管运行时上下文和生命周期。

大白话：Workflow 是流水线图纸，Service 是车间。

多 Agent 编排的五种姿势

模式	怎么排
顺序 Sequential	A 干完 → B → C，流水线。需求分析 → 写码 → 测试。
并行 Parallel	A、B 同时干，最后合并。同时查 5 个资料源再汇总。
条件 Conditional	按上一步结果决定走哪条分支。简单问题走小模型，复杂走大模型。
循环 Loop	不达标就重来。写代码 → 跑测试 → 失败再改，直到通过。
层级 Hierarchical	一个主管 Agent 分派任务给下属 Agent。主管拆活，下属执行。

Java 里怎么借鉴：三个 Agent 顺序协作

AgentScope 核心是 Python，但已有 agentscope-java；在 Java 端还可以直接用 spring-ai-alibaba 的 Graph 模块，或用 Spring AI 的 ChatClient 串出类似能力。下面是用 Spring AI 思路实现的"需求分析 → 程序员 → 测试"顺序流水线（伪结构，具体 API 以 spring-ai-alibaba-graph 官方示例为准）。

三个角色 Agent，顺序传递消息

// 1. 需求分析师 Agent：把口语化需求整理成结构化需求
//    输入："做个能登录的小网站"
//    输出：{功能: 用户注册/登录, 技术: Spring Boot, 验收: 能登录跳首页}
String spec = analyst.run(requirement);

// 2. 程序员 Agent：拿到 spec，产出代码（可借 @Tool 写文件/跑命令）
String code = coder.run(spec);

// 3. 测试 Agent：拿到 spec + code，跑用例，不通过就回退给程序员（循环）
TestResult r = tester.run(spec, code);
while (!r.passed()) {
    code = coder.run(code + "\n测试没通过：" + r.feedback());
    r = tester.run(spec, code);
}
# 输出：一个能跑的、测试通过的小网站

论这跟前面单 Agent 啥区别

单 Agent 是"一个聪明员工什么都干"；多 Agent 是"三个专家各管一段，靠 Message 接力"。顺序编排靠上一个 Agent 的输出当下一个的输入；循环编排靠"测试不过就退回"。调试时用 agentscope-studio / spring-ai-alibaba-studio 看每一步 Message 长啥样，比打日志直观。

Java 端选型一句话

纯 Java、要融进现有 Spring 系统 → spring-ai-alibaba（含 Graph/Studio）；想玩最前沿的多 Agent 生态、能接受 Python → agentscope 全家桶；Java 又想直接上 Agent 框架 → 关注 agentscope-java。三者设计理念相通（Agent+Message+Tool+Workflow），概念一套通吃。

AgentScope Java：Java 开发者自己的 Agent 框架

前面讲 AgentScope 全家桶时，重点在 Python。现在轮到 Java 了：agentscope-java 是阿里巴巴开源的 JVM 版 Agent 框架（官方文档 java.agentscope.io，GitHub 仓库 agentscope-ai/agentscope-java，JDK 17+，Apache-2.0）。2026 年它已经迭代到 2.0——从"调模型的玩具"升级成"能上生产的分布式 Agent 运行时"。一句话：让 Java 团队不用绕道 Python，直接用自己熟悉的 Maven + Spring 生态写生产级 Agent。

版本	说明
1.x	ReAct 循环为主：推理 → 工具 → 回复，能跑通单 Agent。
2.0	平台级重构：新增 Harness 工程层（工作区/长期记忆/会话持久化/子 agent/沙箱/技能/计划模式），兼容 1.x 平滑升级，主打企业级分布式。
配套生态	agentscope-extensions-model-*（各模型适配）、agentscope-extensions-redis（分布式状态）、agentscope-spring-boot-starter（Spring Boot 自动配置）。

快速开始：第一个 HarnessAgent（Maven 依赖 + 完整代码）

HarnessAgent 是 2.0 推荐的入口——把工作区、长期记忆、会话持久化、子 agent、沙箱等工程能力打包进一个 builder。依赖 agentscope-harness 会自动把核心 agentscope-core 拉进来。

pom.xml：只需要两个依赖

<!-- 主依赖：harness 自动带 core -->
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-harness</artifactId>
  <version>${agentscope.version}</version>   <!-- 替换为 Release Notes 里的最新版，如 2.0.0 -->
</dependency>

<!-- 用 DashScope(通义千问) 需要这个模型扩展；换厂商就换对应扩展 -->
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-extensions-model-dashscope</artifactId>
  <version>${agentscope.version}</version>
</dependency>

FirstAgent.java：一段代码跑通"人格 + 记忆 + 自动压缩"三件事

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import io.agentscope.harness.agent.memory.compaction.CompactionConfig;
import java.nio.file.Paths;

public class FirstAgent {
    public static void main(String[] args) {
        HarnessAgent agent = HarnessAgent.builder()
                .name("note-taker")                          // Agent 名（也是状态目录名）
                .sysPrompt("你是一个帮助用户做笔记的助手。")      // 人设，一句话
                .model("dashscope:qwen-plus")                // 字符串由 ModelRegistry 解析，自动读 DASHSCOPE_API_KEY
                .workspace(Paths.get(".agentscope/workspace"))  // 工作区：AGENTS.md/MEMORY.md/skills/subagents
                .compaction(CompactionConfig.builder()          // 对话压缩：超 30 条压缩，留最近 10 条
                        .triggerMessages(30)
                        .keepMessages(10)
                        .build())
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId("demo-session")
                .userId("alice")
                .build();

        // 第一轮：自我介绍
        agent.call(new UserMessage("我叫天宇，今天准备一个关于 ReAct 的技术分享。"), ctx).block();
        // 第二轮：同 sessionId，自动恢复上一轮状态后回答——记得第一轮
        agent.call(new UserMessage("我叫什么？我今天要干什么？"), ctx).block();
    }
}

跑跑完你会看到两棵目录树

工作区（agent 的内容）：.agentscope/workspace/AGENTS.md（写一份就是 agent 的人格，不写也能跑）+ sessions/（永不压缩的原始对话日志）。状态存储（工作区之外）：~/.agentscope/state/note-taker/alice/demo-session/agent_state.json——状态必须放工作区外，因为"沙箱清空后要先有状态才能重建工作区"。

验证点：进程重启、sessionId 不变，第二轮对话依然记得第一轮；多聊几轮触发压缩后，提炼的事实先落到 workspace/memory/日期.md，再周期性合并到 MEMORY.md，下一轮自动注入 system prompt。

生产级提醒

默认的 JsonFileAgentStateStore 是本地文件实现，只适合开发/单机。生产集群要用分布式实现：RedisAgentStateStore（由 agentscope-extensions-redis 提供）或自己实现 AgentStateStore 接口。

ReActAgent vs HarnessAgent：什么时候用哪个

两者共享同一套推理核心（推理 → 工具 → 回复），区别只在"叠加了多少工程能力"。从 ReActAgent 起步，需要长期稳定运行时无缝迁移到 HarnessAgent，业务逻辑不用改。

对比	ReActAgent（裸核心）
定位	"一次推理"的循环：推理 → 工具 → 回复。
适合	原型验证、单次问答、无状态场景。
工程能力	无（要自己管记忆/持久化）。

对比	HarnessAgent（工程底座）
定位	长期稳定运行的工程底座：工作区 + 记忆 + 沙箱 + 子 agent + 技能 + 计划模式。
身份持续	工作区即人格 + 长期记忆 + 领域知识，每轮自动注入。
上下文可控	自动压缩、大工具结果落盘、ContextOverflow 兜底重试。
状态可恢复	同 sessionId 跨进程恢复完整对话；沙箱状态可快照。
能力可沉淀	四层 Skill 合成 + 自学习闸门；声明式子 agent 编排。

模型接入：一个字符串切换五家大模型

.model(...) 里传字符串，由 ModelRegistry 解析并自动读取对应环境变量；需要精细控制超时/自定义 endpoint 时，用对应厂商的 builder 构造实例再传。统一 Credential + ChatModel 抽象支持最大重试与备用模型——主模型挂了自动切换。

模型字符串	环境变量	需要的扩展
`dashscope:qwen-plus` / `qwen-max`	DASHSCOPE_API_KEY	agentscope-extensions-model-dashscope
`openai:gpt-5.5`	OPENAI_API_KEY	agentscope-extensions-model-openai
`anthropic:claude-sonnet-4-5`	ANTHROPIC_API_KEY	agentscope-extensions-model-anthropic
`gemini:gemini-2.0-flash`	GEMINI_API_KEY	agentscope-extensions-model-gemini
`ollama:llama3`（本地）	无需 key	agentscope-extensions-model-ollama

官方还支持 xAI Grok、DeepSeek、Kimi、Moonshot（走 OpenAI 兼容端点 vLLM 等）。提示：OpenAI 兼容端点统一走 openai 扩展即可，本地推理服务也用它。

会话、记忆与自动压缩：让 Agent 真的"记得"

RuntimeContext → 每次调用带上"你是谁"

RuntimeContext.builder().sessionId(...).userId(...).build()，Agent 按 (userId, sessionId) 自动加载/隔离上下文。

多用户并发：Agent 实例在调用间无状态，同一个实例可服务不同用户；同 session 串行，不同 session 完全并行。

CompactionConfig → 对话太长自动"记笔记"

triggerMessages=30、keepMessages=10：超 30 条消息就压缩，只留最近 10 条 + 提炼的长期事实。

落地路径：事实先写 workspace/memory/日期.md，再并入 MEMORY.md，下轮自动进 system prompt——相当于给 Agent 配了个"长期笔记本"。

上下文工程 → 别把上下文撑爆

超大工具结果自动落盘、上下文只留占位符；文件读写强制"先读后改"，减少重复 IO。

大白话：它自己知道"论文太长就别整篇塞脑子里，记个目录，用的时候再翻"。

流式输出与类型化事件：进度可见、人可干预

streamEvents() 实时拿到文本片段、工具调用等中间事件

agent.streamEvents(new UserMessage("帮我把今天的关键点列三条。"))
    .doOnNext(event -> {
        if (event.getType() == AgentEventType.TEXT_BLOCK_DELTA) {
            // 模型返回的流式文本片段 —— 追加到界面
            System.out.print(((TextBlockDeltaEvent) event).getDelta());
        } else if (event.getType() == AgentEventType.TOOL_CALL_START) {
            // 智能体即将调用工具 —— 展示调用信息
            System.out.println("\n[tool] " + ((ToolCallStartEvent) event).getToolCallName());
        }
    })
    .blockLast();

懂为什么"类型化事件"是 2.0 的杀手锏

一次 call() 不再只返回最终文本，而是流式产生模型调用、文本增量、工具调用、工具结果、用户确认等类型化事件（前端无需手动 diff）。多模态消息用 DataBlock 同时兼容 base64 和 URL 两种数据源。权限三态决策（静态规则 + 工具类型 + 输入分析 → 允许/用户审批/拒绝）和 HITL（人在回路）是框架内生能力——该人确认的步骤，Agent 会停下来等你点确认。

工具与 MCP：注解驱动 + 任意 MCP 服务器

工具用注解注册，AI 自己挑；workspace/tools.json 集中管理白名单。2.0 统一接入任意 MCP 兼容服务器（文件系统、数据库、浏览器、代码解释器）——等于给 Agent 插了一排"万能插座"。

注解驱动：给 Java 方法加注解即成为工具，按属性自动批处理（串行或并发）。
MCP：官方 MCP SDK 集成（参考 agentscope-examples/documentation/pom.xml），模型层与工具层解耦。
安全边界：tools.json 白名单 + 权限三态审批，工具不是想调就能调。

Spring Boot 集成与生产部署：从单机 Demo 到 K8s

环节	怎么做
接入 Spring Boot	核心模块是与框架无关的 Java 库，加依赖即可（Spring Boot / Quarkus / Micronaut / 纯 Java 都行）；官方还有 agentscope-spring-boot-starter 提供自动配置。把 HarnessAgent 注册成 `@Bean` 单例，HTTP handler 里每次调用传不同 RuntimeContext。
分布式状态	会话状态由 Session 自动持久化（默认 WorkspaceSession）；换 `RedisAgentStateStore` 支持多实例共享。
沙箱执行	`DockerFilesystemSpec` / E2B 云沙箱：隔离执行 + 快照恢复；本地/远端 KV 一行切换。
水平扩展	Agent 无状态 + 状态外置 → 配 Kubernetes + HPA，任意副本都能恢复同一用户完整上下文。
冷启动	Quarkus + GraalVM 原生镜像可做到 100ms 内冷启动（低延迟场景用）。
运维配套	阿里云 AgentLoop 支持接入 AgentScope Java 应用做观测与优化；Nacos AI Registry 可集成 Skill 仓库。

和 spring-ai-alibaba 怎么配合：一张表说清

	spring-ai-alibaba	AgentScope Java
出身	阿里（Spring AI 生态）	阿里（AgentScope 多语言栈）
定位	Spring AI 的百炼适配 + DAG 编排 + Studio	独立 JVM Agent 框架（Harness 工程底座）
强项	与 Spring 全家桶无缝、注解风格熟悉	生产级分布式：沙箱/快照/MCP/A2A/权限审批
选谁	要"Spring 一套到底"、偏业务集成	要"Agent 平台级能力"、多 Agent 复杂协作
能一起用吗	可以：spring-ai-alibaba 管业务侧接入与编排，AgentScope Java 管重活（沙箱/记忆/分布式）——都是阿里系，概念相通（Agent/Message/Tool/Workflow）。

AgentScope Java 面试题

面试快答 · AgentScope Java

Q1. AgentScope Java 是什么？和 Python 版什么关系？

参考答案

阿里巴巴开源的 JVM 版 Agent 框架（JDK 17+、Apache-2.0），与 Python 版功能对等：推理、工具集成、记忆、多 Agent 协作。2.0 升级为企业级分布式底座（Harness 层）。

Q2. ReActAgent 和 HarnessAgent 的区别？

参考答案

ReActAgent 是"推理→工具→回复"裸核心；HarnessAgent 在其上叠加工作区/记忆/压缩/沙箱/子 agent/技能/计划模式等工程能力。二者共享推理核心，可从 ReAct 起步平滑迁到 Harness，业务逻辑不变。

Q3. AgentScope Java 怎么做到多用户并发？

参考答案

Agent 实例调用间无状态，通过 RuntimeContext 传 (userId, sessionId)；同 session 自动串行化防并发写，不同 session 完全并行；状态持久化到 AgentStateStore（生产用 Redis 实现）。

Q4. 模型切换怎么最省事？

参考答案

用字符串如 "dashscope:qwen-plus" / "openai:gpt-5.5" / "ollama:llama3"，ModelRegistry 解析并自动读对应环境变量；换厂商只改字符串 + 换模型扩展依赖。需要容错时配置重试与备用模型。

Q5. 生产级要换掉哪块默认实现？

参考答案

默认 JsonFileAgentStateStore 只适合单机；生产换 RedisAgentStateStore（或自实现 AgentStateStore），配 Docker 沙箱 + K8s/HPA 水平扩展。

附：java2ai.com 是什么，怎么用它学

java2ai.com 就是 spring-ai-alibaba 的官方文档站——"帮助 Java 开发者步入 AI Native 时代"。它不是付费课程，而是一套带版本号的官方教程（如 /docs/1.0.0.2/），从快速开始到 Workflow、Agent、RAG、实践案例全覆盖，还配了 examples/ 下可直接 clone 运行的示例。

站点分区	对应你在学的
快速开始 / Chatbot	本页第二章，第一个对话接口。
教程 → Chat Model / RAG / Tool	本页 ChatClient、结构化输出、Function Calling、RAG。
Workflow / Graph	本章多 Agent 编排。
Practices / Playground / MCP	生产实践、本地调试、MCP 工具注册。
examples/ 仓库	clone 下来直接跑，比看十篇文章管用。

学习路径建议：① 在 java2ai.com 把"快速开始"跑通；② 挑一个 tutorial（RAG 或 Tool）跟着敲；③ 去 examples 仓库找一个完整案例（如 chatbot）读源码；④ 再回到本页补原理（Embedding、Agent、成本）。官方文档版本号 = 你 Maven 里的版本号，两边对上才不懵。

本章面试题

面试快答 · Agent 与框架选型

Q1. 一个 Agent 的四要素是什么？

参考答案

大脑（LLM 做决策）、工具（能调的外部能力）、记忆（短期上下文 + 长期偏好）、规划（把大任务拆成小步）。单 Agent 够用就别上多 Agent。

Q2. 多 Agent 编排有哪几种模式？

参考答案

顺序（流水线）、并行（同时干再合并）、条件（按结果分支）、循环（不达标重来）、层级（主管分派下属）。Java 端用 spring-ai-alibaba Graph（DAG），Python 端用 agentscope。

Q3. spring-ai-alibaba 和 AgentScope 什么关系？

参考答案

都出自阿里。spring-ai-alibaba 是 Java 生态（Spring AI 的百炼适配 + DAG Agent 编排 + Studio）；AgentScope 是多语言 Agent 栈（Python 核心 + agentscope-java），覆盖记忆(ReMe)、评估(OpenJudge)、调试(studio)。Java 企业优先 spring-ai-alibaba。

Q4. 什么时候别上多 Agent？

参考答案

一个任务、一类工具、AI 自己能一步步完成时，单 Agent + 几个 @Tool + RAG 就够。多 Agent 调试极痛苦（吵架、死循环、互传错信息），只有"真需要不同专家协作/审查"时才上。

← 返回总览 Spring AI总览下一节：模型管理与成本控制 →