# 第九章 Spring Boot 集成：工厂方法 + WebFlux 流式端点，手动配置 HarnessAgent 为单例 Bean

> "1.x 时代有 `agentscope-spring-boot-starter`，2 行配置就能把 agent 注入到 Spring 容器里。2.0.0-RC2 没有官方 starter——这不是退步，而是模型本身的生命周期与 Spring Bean 生命周期（懒加载、scope、AOP）不匹配。2.0 推荐 **『手动配置 + 工厂方法 + WebFlux』** 三步集成。"
>
> 本章你将学到：如何把 `HarnessAgent` 注册成单例 Bean、如何在 Controller / Service 里注入它、如何用 WebFlux 流式输出 `streamEvents()`。

## 9.1 为什么 2.0 没有官方 starter？

1.x 的 `agentscope-spring-boot-starter` 把 `ReActAgent` 注册成 `singleton` Bean。2.0 不再提供这个 starter，原因是：

1. **`HarnessAgent` 不便宜** —— 每次 `.build()` 会创建 model client、tool registry、workspace 句柄。Spring 容器默认 eager-instantiation 可能在没人用 agent 时就建立这些连接。
2. **多用户隔离** —— 1.x 时代一个 Bean 服务所有用户；2.0 用 `RuntimeContext` 区分，`HarnessAgent` 内部需要 Session 后端支持，并发模型与 Spring MVC 的"每请求一线程"模型不匹配。
3. **响应式** —— 2.0 的 `streamEvents()` 返回 `Flux<AgentEvent>`，天然适合 WebFlux。Starter 把所有响应式 API 包装成同步形式，反而抹掉了这个能力。

所以 2.0 推荐：

- **生产用 WebFlux**（响应式）
- **小工具 / 批处理用 `@Configuration` + 工厂方法**（手动）

## 9.2 添加依赖

`pom.xml`（仅核心 + WebFlux）：

```xml
<dependencies>
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope-harness</artifactId>
        <version>2.0.0-RC2</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## 9.3 把 Model 注册成 Bean

模型对象是配置驱动的——交给 `application.yml`：

```yaml
agentscope:
  model:
    provider: dashscope
    api-key: ${DASHSCOPE_API_KEY}
    name: qwen-plus
  workspace: ./workspace
```

对应的 properties 类：

```java
package demo.config;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "agentscope")
public class AgentScopeProperties {

    private Model model = new Model();
    private String workspace = "./workspace";

    public static class Model {
        private String provider = "dashscope";
        private String apiKey;
        private String name = "qwen-plus";
        // getter / setter ...
    }

    public Model getModel() { return model; }
    public String getWorkspace() { return workspace; }
    public void setModel(Model m) { this.model = m; }
    public void setWorkspace(String w) { this.workspace = w; }
}
```

Model 工厂：

```java
package demo.config;

import io.agentscope.core.Model;
import io.agentscope.core.model.DashScopeChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ModelConfig {

    @Bean
    public Model chatModel(AgentScopeProperties props) {
        AgentScopeProperties.Model m = props.getModel();
        if (!"dashscope".equals(m.getProvider())) {
            throw new IllegalArgumentException("unsupported provider: " + m.getProvider());
        }
        return DashScopeChatModel.builder()
                .apiKey(m.getApiKey())
                .modelName(m.getName())
                .build();
    }
}
```

## 9.4 把 HarnessAgent 做成"工厂 Bean"

我们希望"按用途"区分 agent——比如天气 agent、翻译 agent、客服 agent。推荐用 **`@Bean` 工厂方法** 而不是把 `HarnessAgent` 自身注册成 Bean（避免 eager build）：

```java
package demo.config;

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.HarnessAgent;
import org.springframework.stereotype.Component;

import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.ConcurrentHashMap;

@Component
public class AgentFactory {

    private final Model model;
    private final Path workspace;
    private final ConcurrentHashMap<String, HarnessAgent> cache = new ConcurrentHashMap<>();

    public AgentFactory(Model model, AgentScopeProperties props) {
        this.model = model;
        this.workspace = Path.of(props.getWorkspace());
    }

    public HarnessAgent weatherAgent() {
        return cache.computeIfAbsent("weather", id ->
                HarnessAgent.builder()
                        .name("weather_bot")
                        .sysPrompt("你是一个中文天气助手，每次回答不超过 50 字。")
                        .model(model)
                        .workspace(workspace)
                        .build());
    }

    public HarnessAgent translatorAgent() {
        return cache.computeIfAbsent("translator", id ->
                HarnessAgent.builder()
                        .name("translator")
                        .sysPrompt("你是一个中英互译助手。")
                        .model(model)
                        .workspace(workspace)
                        .build());
    }
}
```

> 关键：业务方调 `factory.weatherAgent()` 才创建 agent；`ConcurrentHashMap` 保证单例；按用途区分，内存可控。

## 9.5 Controller：用 WebFlux 暴露流式端点

```java
package demo.web;

import demo.config.AgentFactory;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.event.AgentEvent;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.List;
import java.util.Map;
import java.util.UUID;

@RestController
@RequestMapping("/api/agent")
public class AgentController {

    private final AgentFactory factory;

    public AgentController(AgentFactory factory) {
        this.factory = factory;
    }

    /**
     * 流式 SSE 端点
     */
    @GetMapping(value = "/weather/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<AgentEvent> stream(
            @RequestParam String sessionId,
            @RequestParam String userId,
            @RequestParam String text) {

        return Mono.fromFuture(
                        factory.weatherAgent()
                                .streamEvents(
                                        List.of(new UserMessage("user", text)),
                                        RuntimeContext.builder()
                                                .sessionId(sessionId)
                                                .userId(userId)
                                                .traceId(UUID.randomUUID().toString())
                                                .build())
                                .toFuture())
                .flatMapMany(flux -> flux);
    }

    /**
     * 一次性同步端点
     */
    @PostMapping("/weather/once")
    public Mono<Map<String, String>> once(
            @RequestParam String sessionId,
            @RequestParam String userId,
            @RequestBody Map<String, String> body) {

        return Mono.fromFuture(
                        factory.weatherAgent()
                                .call(
                                        List.of(new UserMessage("user", body.get("text"))),
                                        RuntimeContext.builder()
                                                .sessionId(sessionId)
                                                .userId(userId)
                                                .build())
                                .toFuture())
                .map(msg -> Map.of("reply", msg.getTextContent()));
    }
}
```

前端用 `EventSource` 订阅：

```javascript
const es = new EventSource(
  `/api/agent/weather/stream?sessionId=s-1&userId=u-1&text=${encodeURIComponent('杭州今天多少度')}`
);
es.onmessage = (e) => console.log(e.data);
```

## 9.6 与 Spring Session 协作

如果前端用 `spring-session-data-redis`，把 `sessionId` 与 Spring Session 的 `Session.Id` 绑定，让 2.0 的 `RedisSession` 与 Spring Session 共享 Redis 实例：

```java
RuntimeContext.builder()
        .sessionId(httpSession.getId())   // 复用 Spring Session ID
        .userId(currentUser.getId())
        .build();
```

这样 Spring Session 里只放 HTTP 层的 attribute，agent state 由 `RedisSession` 单独管理——互不污染。

## 9.7 完整工程结构

```text
src/main/java/demo/
├── DemoApplication.java
├── config/
│   ├── AgentScopeProperties.java
│   ├── ModelConfig.java
│   └── AgentFactory.java
└── web/
    └── AgentController.java
src/main/resources/
└── application.yml
```

`DemoApplication.java`：

```java
package demo;

import demo.config.AgentScopeProperties;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(AgentScopeProperties.class)
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

## 9.8 本章小结

- 2.0 没有官方 starter——`HarnessAgent` 不适合直接做 Spring Bean，由 `AgentFactory` 工厂按需创建。
- Model 走 `@ConfigurationProperties` + `@Bean` 工厂。
- Controller 用 WebFlux：`streamEvents()` → SSE、`call()` → 一次性。
- `sessionId` 可以与 Spring Session ID 复用，agent state 单独走 `RedisSession`。


"1.x 时代有 agentscope-spring-boot-starter，2 行配置就能把 agent 注入到 Spring 容器里。2.0.0-RC2 没有官方 starter——这不是退步，而是模型本身的生命周期与 Spring Bean 生命周期（懒加载、scope、AOP）不匹配。2.0 推荐 『手动配置 + 工厂方法 + WebFlux』 三步集成。"

【AgentScope Java新手村系列】（9）SpringBoot集成

SpringBoot集成 — 工厂方法将 HarnessAgent 注册为单例 Bean，WebFlux 流式输出 streamEvents 到 SSE 端点。

后端

编程语言

开发工具

SpringBoot集成HarnessAgent 2.0采用工厂方法+WebFlux流式端点方案，通过手动配置实现单例Bean管理。文章详解了如何通过工厂模式按需创建Agent、利用WebFlux暴露流式SSE端点，以及如何与SpringSession协作实现会话管理。

容器

Redis

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【AgentScope Java新手村系列】（9）SpringBoot集成-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（9）SpringBoot集成

【AgentScope Java新手村系列】（9）SpringBoot集成

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐