AgentScope：Java构建生产级记忆型AI Agent中台

1. 项目概述：为什么“记忆型 AI Agent”不是玩具，而是生产级基础设施的起点

你有没有遇到过这样的场景：一个客服对话系统，用户第一次问“我的订单发货了吗”，系统查了订单状态并回复；五分钟后用户又问“那个订单发的是什么快递”，系统却像失忆一样，重新要求用户提供订单号——明明上下文就在眼前，它却要从头开始。这不是模型能力不足，而是架构设计缺失。AgentScope 这个项目标题里藏着三个被很多人轻描淡写、实则决定成败的关键词：“生产级”、“记忆型”、“从零构建”。它不教你怎么调用一个 API 就跑通 demo，而是直面真实业务中那些让 AI 项目卡在 POC 阶段、永远无法上线的硬骨头：状态持久化怎么不丢数据？多轮对话中用户意图漂移如何锚定？不同 agent 之间协作时上下文怎么共享而不混乱？任务失败后怎么回滚重试？这些不是“高级功能”，而是生产环境的底线要求。

我带团队落地过 7 个面向金融、政务、电商场景的 AI Agent 系统，最深的体会是：90% 的失败不是败在模型效果，而是败在记忆管理的粗糙上。有人用 Redis 存 session ID，结果用户换设备就断上下文；有人把整个对话 history 塞进 prompt，30 轮之后 token 爆表、响应变慢、关键信息被截断；还有人用本地内存缓存，一重启服务，所有用户记忆全清零。AgentScope 的价值，正在于它把“记忆”这件事，从一个临时补丁，变成了可插拔、可审计、可伸缩的一等公民。它不绑定 Python 或 JavaScript，而是用 Java 构建核心骨架——这绝非偶然。Java 的强类型、JVM 的成熟 GC、Spring 生态的事务管理、以及国内企业级中间件（如 RocketMQ、ShardingSphere）的无缝集成能力，决定了它是承载高并发、长生命周期、强一致性要求的 AI Agent 中台的现实选择。你看到的“agentscope 2.0 rag as service”，背后是把向量检索、文档切片、元数据过滤、权限校验全部封装成标准服务接口；你搜到的“agentscope java 教程”，本质是在教你怎么把一个 AI 模块，像部署一个 Spring Boot 微服务一样，纳入现有 CI/CD 流水线。这不是学一门新语言，而是用你已有的 Java 工程能力，去驾驭下一代智能体范式。

2. 核心架构拆解：记忆不是“记住”，而是“可追溯、可干预、可演化”的状态管理

2.1 “记忆型”的本质：三层状态空间与生命周期治理

很多人把“记忆型 AI Agent”简单理解为“能记住上一轮对话”，这是对复杂性的严重低估。AgentScope 定义的记忆，是一个立体的状态空间，由三个正交维度构成：会话级（Session）、实体级（Entity）、全局知识级（Global Knowledge）。这三者不是并列关系，而是存在明确的依赖与隔离边界。

• 会话级记忆：对应单个用户的一次完整交互周期，比如一次电商咨询从“查订单”到“申请售后”再到“催物流”的全过程。AgentScope 不把它存在内存里，而是抽象为SessionState对象，其核心字段包括sessionId（UUID）、lastActiveAt（时间戳，用于自动过期）、stateVersion（乐观锁版本号，防并发覆盖）、metadata（JSON 字符串，存用户设备、渠道、当前步骤等上下文）。关键点在于，这个对象的序列化/反序列化过程，强制要求所有字段实现Serializable接口，并通过@JsonInclude(JsonInclude.Include.NON_NULL)注解控制 JSON 输出，避免空字段污染下游。我见过太多项目因为没处理好null和空集合，在 Kafka 消息反序列化时直接抛NullPointerException，导致整个消息队列积压。

• 实体级记忆：这是真正体现“生产级”的地方。它不记录“用户说了什么”，而是记录“系统确认了什么事实”。比如用户说“我的手机号是138****1234”，AgentScope 的EntityMemory模块会触发一个PhoneNumberValidator，调用运营商实名认证接口验证真伪，验证通过后才将{"type": "phone", "value": "138****1234", "verifiedAt": "2024-06-15T10:23:45Z", "source": "user_input"}写入数据库。这个过程有完整的事务边界：验证失败则整个会话状态回滚；验证成功但 DB 写入失败，则触发补偿机制，将事件发往死信队列。这种设计让记忆不再是“印象”，而是“可审计的事实”。

• 全局知识级记忆：对应 RAG（检索增强生成）中的知识库。AgentScope 2.0 将其产品化为RagAsService，核心是把“知识”和“检索逻辑”解耦。知识源（PDF、Word、数据库快照）经过统一的DocumentProcessor流水线：先用 Apache Tika 提取纯文本，再用SentenceSplitter按语义切分（不是简单按换行），最后用EmbeddingGenerator（支持 BGE-M3、text2vec-large-chinese 等模型）生成向量。而检索逻辑则封装在RagQueryEngine中，它接收queryText、filterConditions（如{"department": "finance", "validUntil": ">2024-12-31"}）、topK三个参数，返回结构化结果。这意味着，前端业务代码完全不需要关心向量数据库怎么连、索引怎么建，只需要调用一个 REST 接口或 gRPC 方法。我们线上一个政务问答系统，就是靠这套机制，让知识库更新从“停服半小时”变成“热更新，毫秒级生效”。

提示：AgentScope 的记忆模块默认使用 H2 数据库存储会话和实体状态，这仅用于开发测试。生产环境必须替换为 MySQL 或 PostgreSQL。替换方法不是改配置文件那么简单，而是要执行schema.sql中定义的 DDL 语句，并确保application-prod.yml中的spring.datasource.hikari.connection-timeout设置为 30000（30秒），避免网络抖动导致连接池耗尽。

2.2 “生产级”的四大支柱：可观测性、弹性、一致性、可维护性

一个能跑通 demo 的 Agent 是玩具，一个能扛住双十一流量峰值、连续运行 365 天无故障的 Agent 才是生产级。AgentScope 用四个工程实践，把这四个抽象概念落地为可触摸的代码。

• 可观测性（Observability）：AgentScope 内置了 Micrometer + Prometheus + Grafana 的监控栈。每个 Agent 的execute()方法都被@Timed注解包裹，自动上报执行耗时、成功率、错误类型（如LLMTimeoutException,MemoryWriteFailedException）。更关键的是，它提供了TraceContext工具类，能在日志中自动注入traceId和spanId。当你在 Grafana 看到某个order-query-agent的 P95 延迟突然飙升到 8 秒，你可以直接在 ELK 日志平台搜索traceId=abc123，精准定位到是调用第三方物流 API 的那行代码超时，而不是在几百行日志里大海捞针。我们曾用这个能力，在 3 分钟内定位并修复了一个因 Redis 连接池配置不当导致的雪崩问题。

• 弹性（Resilience）：AgentScope 的AgentExecutor类不是简单地顺序执行子 Agent，而是实现了 Circuit Breaker（熔断器）模式。它维护一个滑动窗口（默认 60 秒），统计最近 100 次调用的成功率。当成功率低于阈值（默认 60%）时，熔断器进入 OPEN 状态，后续请求直接返回预设的 fallback 响应（如“系统繁忙，请稍后再试”），不再调用下游。经过 30 秒休眠期后，进入 HALF-OPEN 状态，放行少量请求试探。这个机制救了我们不止一次。去年双十一，一个依赖外部天气 API 的营销 Agent 因对方服务宕机，触发熔断，避免了整个营销活动页面因超时而白屏。

• 一致性（Consistency）：这是 Java 工程师最熟悉的战场。AgentScope 在SessionStateService中，对updateSessionState()方法加了@Transactional注解，并指定了isolation = Isolation.REPEATABLE_READ。这意味着，即使两个线程同时尝试更新同一个 sessionId 的状态，数据库也会保证它们看到的是同一份快照，不会出现 A 线程读到旧值、B 线程读到旧值、然后都基于旧值计算出新值并写回，导致最终状态丢失的问题。更进一步，对于跨微服务的强一致性场景（如“扣减库存”和“创建订单”必须同时成功），AgentScope 提供了SagaOrchestrator，它把一个分布式事务拆解为一系列本地事务和补偿事务，用 Kafka 作为事件总线，确保最终一致性。这比盲目追求 ACID 更符合云原生架构。

• 可维护性（Maintainability）：AgentScope 的核心设计哲学是“约定优于配置”。它定义了Agent接口，强制所有 Agent 实现getName(),getDescription(),execute(AgentInput input)三个方法。这意味着，当你接手一个新项目，看到PaymentAgent、RefundAgent、FraudCheckAgent这几个类，你不需要看源码，就能猜到它们各自的功能边界。它的pom.xml里没有一堆版本号，而是通过spring-boot-dependenciesBOM 统一管理，所有依赖版本由父 POM 控制。我们团队内部有个不成文规定：任何新加入的 Agent，必须提供一份README.md，里面包含输入输出 JSON Schema、典型调用示例、以及一个curl命令，让 QA 同学能立刻上手测试。这种纪律性，让我们的 Agent 库从最初的 5 个，增长到现在的 47 个，依然能保持清晰的脉络。

3. 从零构建实操：手把手搭建你的第一个生产级记忆型 Agent

3.1 环境准备与项目初始化：避开 JDK 和 Spring Boot 的经典陷阱

别急着写代码，先搞定环境。AgentScope 官方推荐 JDK 17+ 和 Spring Boot 3.x，但这背后有血泪教训。我见过太多团队卡在第一步：用 JDK 21 编译，却在 JDK 17 的生产服务器上运行，报java.lang.UnsupportedClassVersionError。所以，第一件事，就是在pom.xml的<properties>里明确锁定编译和运行版本：

<properties> <java.version>17</java.version> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> </properties>

第二件事，是 Spring Boot 版本的选择。网上很多教程用 2.7.x，但它对 Jakarta EE 9+ 的支持不完善，而 AgentScope 2.0 的RagAsService模块大量使用了jakarta.annotation包。因此，必须使用 Spring Boot 3.2.x。在pom.xml中，用spring-boot-starter-parent3.2.5 作为 parent：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <relativePath/> </parent>

第三件事，也是最容易被忽略的：禁用 Spring Boot 的 DevTools 在生产环境的自动重启。DevTools 在开发时很好用，但它会监听 classpath 变化并热重启 JVM。在生产环境，这会导致服务短暂不可用，且可能引发内存泄漏。在application-prod.yml中，必须显式关闭：

spring: devtools: restart: enabled: false livereload: enabled: false

完成这些后，用 Spring Initializr 初始化项目，勾选Spring Web,Spring Data JPA,Lombok,Validation这四个核心依赖。特别注意，不要勾选Spring Boot DevTools，它只该存在于devprofile 下。

3.2 记忆模块实战：用 JPA 实现可审计的会话状态管理

现在，让我们亲手实现 AgentScope 的核心——会话记忆。创建entity/SessionState.java：

import jakarta.persistence.*; import jakarta.validation.constraints.NotBlank; import java.time.LocalDateTime; import java.util.Map; @Entity @Table(name = "session_state") public class SessionState { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @NotBlank @Column(name = "session_id", unique = true, length = 64) private String sessionId; @Column(name = "state_data", columnDefinition = "TEXT") @Convert(converter = JsonStringConverter.class) // 自定义 JSON 转换器 private Map<String, Object> stateData; @Column(name = "last_active_at") private LocalDateTime lastActiveAt; @Column(name = "state_version") private Long stateVersion; @Column(name = "created_at") private LocalDateTime createdAt; @Column(name = "updated_at") private LocalDateTime updatedAt; // 构造函数、getter、setter 省略 }

关键点在于@Convert(converter = JsonStringConverter.class)。JPA 默认不支持直接存 Map，我们需要一个自定义转换器：

import jakarta.persistence.AttributeConverter; import jakarta.persistence.Converter; import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; @Converter(autoApply = true) public class JsonStringConverter implements AttributeConverter<Map<String, Object>, String> { private final ObjectMapper objectMapper = new ObjectMapper(); @Override public String convertToDatabaseColumn(Map<String, Object> attribute) { try { return objectMapper.writeValueAsString(attribute); } catch (JsonProcessingException e) { throw new RuntimeException("Failed to serialize map to JSON", e); } } @Override public Map<String, Object> convertToEntityAttribute(String dbData) { try { return objectMapper.readValue(dbData, new TypeReference<Map<String, Object>>() {}); } catch (JsonProcessingException e) { throw new RuntimeException("Failed to deserialize JSON to map", e); } } }

接着，创建repository/SessionStateRepository.java：

import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.JpaSpecificationExecutor; import org.springframework.data.jpa.repository.Modifying; import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; import org.springframework.stereotype.Repository; import java.time.LocalDateTime; import java.util.Optional; @Repository public interface SessionStateRepository extends JpaRepository<SessionState, Long>, JpaSpecificationExecutor<SessionState> { Optional<SessionState> findBySessionId(String sessionId); @Modifying @Query("UPDATE SessionState s SET s.stateData = :stateData, s.lastActiveAt = :lastActiveAt, s.stateVersion = s.stateVersion + 1, s.updatedAt = :updatedAt WHERE s.sessionId = :sessionId AND s.stateVersion = :expectedVersion") int updateStateWithOptimisticLock( @Param("sessionId") String sessionId, @Param("stateData") Map<String, Object> stateData, @Param("lastActiveAt") LocalDateTime lastActiveAt, @Param("updatedAt") LocalDateTime updatedAt, @Param("expectedVersion") Long expectedVersion ); @Query("DELETE FROM SessionState s WHERE s.lastActiveAt < :cutoffTime") int deleteExpiredSessions(@Param("cutoffTime") LocalDateTime cutoffTime); }

这个updateStateWithOptimisticLock方法是生产级的关键。它使用了乐观锁（s.stateVersion = s.stateVersion + 1和AND s.stateVersion = :expectedVersion），确保并发更新时不会覆盖彼此的修改。如果updateStateWithOptimisticLock返回 0，说明有其他线程抢先更新了，此时你应该捕获OptimisticLockException，重新加载最新状态，再计算新值，重试更新。这就是“可追溯、可干预”的体现——你永远知道状态是怎么一步步变过来的。

3.3 构建第一个 Agent：订单查询 Agent 的完整链路

现在，我们来构建一个真实的业务 Agent：OrderQueryAgent。它的职责是：根据用户提供的订单号，查询订单详情，并将结果存入会话记忆，供后续 Agent（如LogisticsQueryAgent）复用。

首先，定义输入输出：

// dto/OrderQueryInput.java public class OrderQueryInput { @NotBlank(message = "订单号不能为空") private String orderNo; // getter/setter } // dto/OrderQueryOutput.java public class OrderQueryOutput { private String orderNo; private String status; // "已支付", "已发货", "已完成" private BigDecimal amount; private String logisticsNo; // 物流单号，供后续查询 private LocalDateTime shippedAt; // getter/setter }

然后，实现 Agent 核心逻辑：

import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import java.math.BigDecimal; import java.time.LocalDateTime; @Service public class OrderQueryAgent implements Agent<OrderQueryInput, OrderQueryOutput> { private final OrderQueryService orderQueryService; private final SessionStateRepository sessionStateRepository; public OrderQueryAgent(OrderQueryService orderQueryService, SessionStateRepository sessionStateRepository) { this.orderQueryService = orderQueryService; this.sessionStateRepository = sessionStateRepository; } @Override @Transactional public OrderQueryOutput execute(OrderQueryInput input) { // 1. 查询订单主数据 Order order = orderQueryService.findByOrderNo(input.getOrderNo()); if (order == null) { throw new IllegalArgumentException("未找到订单: " + input.getOrderNo()); } // 2. 构建输出 OrderQueryOutput output = new OrderQueryOutput(); output.setOrderNo(order.getOrderNo()); output.setStatus(order.getStatus()); output.setAmount(order.getAmount()); output.setLogisticsNo(order.getLogisticsNo()); output.setShippedAt(order.getShippedAt()); // 3. 将关键信息写入会话记忆 // 注意：这里不是存整个 Order 对象，而是存业务需要的最小字段集 Map<String, Object> memoryData = new HashMap<>(); memoryData.put("order_status", order.getStatus()); memoryData.put("order_amount", order.getAmount().toString()); memoryData.put("logistics_no", order.getLogisticsNo()); memoryData.put("shipped_at", order.getShippedAt().toString()); // 4. 使用乐观锁更新会话状态 String sessionId = getCurrentSessionId(); // 从 ThreadLocal 或 RequestContextHolder 获取 SessionState currentState = sessionStateRepository.findBySessionId(sessionId) .orElseThrow(() -> new IllegalStateException("Session not found: " + sessionId)); int updatedRows = sessionStateRepository.updateStateWithOptimisticLock( sessionId, memoryData, LocalDateTime.now(), LocalDateTime.now(), currentState.getStateVersion() ); if (updatedRows == 0) { // 乐观锁失败，重试逻辑 throw new OptimisticLockRetryException("Session state update failed, retry needed"); } return output; } @Override public String getName() { return "order-query-agent"; } @Override public String getDescription() { return "根据订单号查询订单详情，并将关键信息存入会话记忆"; } }

最后，暴露一个 REST 接口来触发这个 Agent：

import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/agent") public class AgentController { private final OrderQueryAgent orderQueryAgent; public AgentController(OrderQueryAgent orderQueryAgent) { this.orderQueryAgent = orderQueryAgent; } @PostMapping("/order-query") public ResponseEntity<OrderQueryOutput> queryOrder(@RequestBody OrderQueryInput input) { try { OrderQueryOutput output = orderQueryAgent.execute(input); return ResponseEntity.ok(output); } catch (IllegalArgumentException e) { return ResponseEntity.badRequest().body(null); } catch (OptimisticLockRetryException e) { // 实际项目中，这里可以返回 409 Conflict，并提示前端重试 return ResponseEntity.status(HttpStatus.CONFLICT).build(); } } }

这个看似简单的 Agent，已经包含了生产级的所有要素：输入校验、事务管理、乐观锁、异常分类处理、清晰的职责边界。它不是一个孤立的函数，而是整个记忆型 Agent 网络中的一个节点。

4. 进阶与避坑：那些只有踩过才知道的“Java 面试题”级细节

4.1 关于“Java 是静态链接的”：AgentScope 如何实现动态 Agent 注册

网上常有人说“Java 是静态链接的，不如 Python 灵活”，这在 AgentScope 里被彻底颠覆。AgentScope 的AgentRegistry是一个典型的 SPI（Service Provider Interface）应用。它不靠new OrderQueryAgent()这种硬编码，而是通过java.util.ServiceLoader动态加载。

首先，在src/main/resources/META-INF/services/下创建一个文件，名为com.example.agentscope.agent.Agent，内容只有一行：

com.example.agentscope.agent.impl.OrderQueryAgent

然后，AgentRegistry的核心代码是：

public class AgentRegistry { private static final ServiceLoader<Agent> AGENT_LOADER = ServiceLoader.load(Agent.class); public static <I, O> Agent<I, O> getAgent(String name) { return AGENT_LOADER.stream() .map(ServiceLoader.Provider::get) .filter(agent -> agent.getName().equals(name)) .findFirst() .orElseThrow(() -> new AgentNotFoundException("Agent not found: " + name)); } }

这意味着，你可以把OrderQueryAgent打包成一个独立的 JAR，放到lib/目录下，只要它的META-INF/services/文件正确，AgentScope 启动时就会自动发现并注册它。这完美解决了“AI Agent 中台”需要快速接入新业务能力的需求。我们一个客户，就是靠这个机制，在 2 小时内，把他们自研的“发票识别 Agent”集成进了现有的 Agent 平台，全程无需修改平台代码。

4.2 关于“Java 怎么保证数据一致性”：AgentScope 的两阶段提交模拟

在分布式系统中，强一致性很难，但最终一致性必须可控。AgentScope 的SagaOrchestrator就是为此而生。假设一个“下单”流程需要三个 Agent 协作：InventoryCheckAgent（检查库存）、PaymentAgent（扣款）、OrderCreateAgent（创建订单）。Saga 模式要求，如果任何一个失败，前面成功的步骤必须回滚。

AgentScope 的实现是：SagaOrchestrator维护一个SagaStep列表，每个SagaStep包含doAction（正向操作）和compensateAction（补偿操作）两个Runnable。它用一个ConcurrentLinkedQueue<SagaStep>来记录已执行的步骤。当doAction执行成功，SagaStep入队；当某一步失败，SagaOrchestrator从队尾开始，依次执行每个SagaStep的compensateAction，直到队列为空。

关键点在于，compensateAction必须是幂等的。例如，PaymentAgent的补偿操作不是“退款”，而是“检查该笔支付是否已退款，若未退款则发起退款”。这就要求你的补偿逻辑本身也要有状态判断。我们在线上曾遇到过补偿失败的情况，根源是补偿操作的数据库连接池配置太小，导致在高并发下获取连接超时。解决方案是：为补偿操作单独配置一个CompensationDataSource，其hikari.maximum-pool-size设为 20，远高于主数据源的 10。

4.3 关于“Java 面试宝典”里的八股文：AgentScope 如何优雅处理 LLM 调用超时

Java 面试必考Future和CompletableFuture，但在 AgentScope 里，它们被用到了极致。LLM API 调用是典型的 I/O 密集型操作，不能阻塞主线程。AgentScope 的LLMClient封装了完整的异步调用链：

public class LLMClient { private final ScheduledExecutorService timeoutScheduler = Executors.newScheduledThreadPool(2); public CompletableFuture<LLMResponse> callAsync(LLMRequest request) { CompletableFuture<LLMResponse> future = new CompletableFuture<>(); // 1. 发起 HTTP 请求 httpClient.sendAsync(request.toHttpRequest(), HttpResponse.BodyHandlers.ofString()) .thenAccept(httpResponse -> { if (httpResponse.statusCode() == 200) { LLMResponse response = parseResponse(httpResponse.body()); future.complete(response); } else { future.completeExceptionally(new LLMCallException("HTTP Error: " + httpResponse.statusCode())); } }) .exceptionally(throwable -> { future.completeExceptionally(new LLMCallException("Network Error", throwable)); return null; }); // 2. 设置超时，超时后取消 future 并抛出异常 timeoutScheduler.schedule(() -> { if (!future.isDone()) { future.completeExceptionally(new LLMTimeoutException("LLM call timed out after 30s")); } }, 30, TimeUnit.SECONDS); return future; } }

这段代码展示了CompletableFuture的组合能力：thenAccept处理成功，exceptionally处理网络异常，schedule处理超时。它比简单的Future.get(30, TimeUnit.SECONDS)更优雅，因为后者会阻塞线程，而这里是纯异步的。这也是为什么 AgentScope 能在单机上支撑 500+ 并发 LLM 调用而不崩溃——它把所有耗时操作都扔进了异步世界。

5. 常见问题与排查技巧实录：来自 7 个真实项目的故障手册

5.1 问题速查表：高频故障现象、根因与解决方案

5.2 独家避坑技巧：那些文档里不会写的“潜规则”

• 技巧一：用ThreadLocal管理会话上下文，但必须手动清理。AgentScope 的SessionContext类用ThreadLocal<SessionState>来传递当前会话状态，这很高效。但如果你在 Controller 里用了@Async注解，ThreadLocal的值不会自动传递到新线程！解决方案是：在@Async方法的参数里，显式传入sessionId，然后在新线程里重新sessionStateRepository.findBySessionId()。更重要的是，在finally块里，一定要调用ThreadLocal.remove()，否则在 Tomcat 的线程池里，旧的SessionState会被下一个请求复用，造成严重的数据污染。我们曾因此泄露过用户隐私数据，教训惨痛。

• 技巧二：@Valid注解的嵌套校验，必须配合@Validated接口组。OrderQueryInput里如果有一个Address对象，而Address里又有@NotBlank字段，光用@Valid是不够的。你必须在 Controller 方法上，用@Validated({Default.class, OrderQueryGroup.class})，并在Address类上，用@Valid标注其字段。否则，嵌套对象的校验会静默失败。这是 Spring Validation 的一个经典陷阱。

• 技巧三：@Transactional的传播行为，REQUIRES_NEW是双刃剑。当一个 Agent 需要独立于外部事务执行（比如发一条 Kafka 消息，无论主事务成功与否都要发），你会用@Transactional(propagation = Propagation.REQUIRES_NEW)。但要注意，这会开启一个全新的数据库连接，如果主事务和子事务都操作同一张表，可能会引发死锁。我们的解决方案是：给REQUIRES_NEW的方法，加上@Retryable(value = {DeadlockLoserDataAccessException.class}, maxAttempts = 3)，用 Spring Retry 自动重试。

• 技巧四：Lombok的@Data是方便，但@Builder和@AllArgsConstructor不能共存。@Data会自动生成@AllArgsConstructor，而@Builder也会生成一个全参构造器，导致编译错误。正确的姿势是：用@Value（不可变对象）或@Data+@RequiredArgsConstructor（只生成必需参数的构造器），然后手动写@Builder。否则，你在单元测试里用Builder创建对象时，会发现final字段无法赋值。

• 技巧五：application.yml的 profile 激活，spring.profiles.active必须是第一个属性。如果你把spring.profiles.active=prod写在yml文件的中间，它可能被后面的spring:块覆盖。最佳实践是：把spring.profiles.active单独放在application.yml的最顶部，或者干脆用 JVM 参数-Dspring.profiles.active=prod启动。我们一个项目就是因为这个顺序问题，在测试环境跑了两周才发现，它其实一直在用dev配置连接测试数据库。

6. 从练手到产品：如何用 AgentScope 构建你的第一个 AI Agent 产品

6.1 练手小项目：一个“智能会议纪要助手”的完整闭环

别被“生产级”吓住。AgentScope 的魅力在于，它让你用生产级的架构，做练手级的小项目。我们来做一个“智能会议纪要助手”，它能：1）接收一段会议录音的文本转录稿；2）自动提取参会人、议题、待办事项、截止日期；3）将结果格式化为 Markdown，并发送邮件。

这个项目只需要 3 个 Agent：

• TranscriptParserAgent：解析原始文本，用正则提取【主持人】、【发言人】等标签。
• MeetingSummaryAgent：调用 LLM，Prompt 是：“你是一个专业的会议秘书。请从以下会议记录中，提取：1) 所有参会人姓名；2) 讨论的 3 个核心议题；3) 明确的待办事项（Action Items），每个事项包含负责人和截止日期。输出 JSON 格式。”
• EmailSenderAgent：将 JSON 结果渲染为 Markdown 模板，并调用 JavaMailSender 发送。

关键点在于，MeetingSummaryAgent的输出，会自动成为EmailSenderAgent的输入，而这个输入的 schema，是由MeetingSummaryOutput类严格定义的。这保证了整个流水线的类型安全。你甚至可以为EmailSenderAgent写一个单元测试，MockMeetingSummaryOutput，验证它生成的 Markdown 是否符合预期。这种“契约先行”的开发方式，正是大型项目可维护性的基石。

6.2 2026 年国内 AI Agent 产品盘点启示：AgentScope 的定位与演进

回看 2026 年国内涌现的 AI Agent 产品，如“钉钉智能助理”、“飞书多维表格 Agent”、“百度文心一言工作流”，它们的共同点是：都构建在强大的 Agent 中台之上。而 AgentScope，正是这样一个中台的开源参考实现。它的价值不在于取代商业产品，而在于告诉你，一个健壮的中台，应该长什么样。

• 面向对象编程 Java 的终极体现：每一个 Agent 都是一个对象，有清晰的state（记忆）、behavior（execute 方法）、identity（name 和 description）。AgentScope的AgentExecutor就是那个“指挥官”，它不关心每个 Agent 内部怎么实现，只关心它们是否遵守了Agent接口的契约。这完美诠释了 OOP 的开闭原则——对扩展开放，对修改关闭。

• Java 基础的深度运用：Optional处理可能为空