给 Agent 装上对话框——AgentScope-Java 接入 Spring Boot 与 SSE 流式实战
「P5:给 Agent 装上对话框」系列解读:把 HarnessAgent 接进 Spring Boot,用 SSE 把回答逐段推给浏览器。这篇把对话入口的设计、三层代码分工与 SSE 流式输出的四个实战坑逐个拆开,并给出可直接改造的 Controller 骨架与 curl 验证命令。
文章目录
做 Agent 的团队大概都遇到过同一种尴尬:能力早就跑通了,Demo 也惊艳,可要让业务同事真正用起来,还得先装环境、敲命令行、盯着终端刷字。 Agent 缺的往往不是能力,而是一个像样的「入口」。
「P5:给 Agent 装上对话框」这个系列处理的正是这件事:把 HarnessAgent 接进 Spring Boot,用 SSE 把回答一段一段推到浏览器上,让 Agent 从「一个能跑的脚本」变成「一个能对话的服务」。这是该系列的第 5 篇。我把它拆成三个可落地的工程问题来读:入口该怎么设计、代码该怎么分层、流式输出怎么才不翻车。
1、Agent 要的不是又一个 API,而是一个「能对话的入口」
1、Agent 要的不是又一个 API,而是一个「能对话的入口」 · AI 生成示意图
先把这件事的性质说清楚。一个能跑的 Agent,本质上是一段有状态、会思考、还要调工具的逻辑;把它变成服务,绕不开三件事:谁来发起会话、结果怎么一段段送回来、断线之后从哪儿续上。
前端的直觉做法是「再开个 WebSocket」。但很多场景根本不需要双向长连接——用户发一句话,Agent 回一段话,中间的推送是单向的。这时候 SSE(Server-Sent Events) 才是更划算的选择:它是浏览器原生支持的文本事件流,HTTP 响应本身就是一条长连接,Spring MVC 里用一个 SseEmitter 就能把内容一段段 send 出去,不需要额外装 WebSocket 容器,也不用自己处理心跳协议。
| 维度 | SSE | WebSocket | 轮询 |
|---|---|---|---|
| 通信方向 | 单向(服务端 → 浏览器) | 全双工 | 单向,靠频率硬撑 |
| 接入成本 | Spring MVC 直接支持,一个 SseEmitter 搞定 |
需要额外的处理器与握手流程 | 代码最少,但浪费最大 |
| 断线恢复 | 浏览器自动重连,可配合事件 id 续传 | 要自己实现重连与补发 | 不涉及 |
| 典型场景 | 逐字输出、思考过程流式展示 | 语音、协同编辑、双向指令 | 低频状态查询 |
选型结论其实很干脆:「用户说话、Agent 答话」用 SSE;「人和 Agent 同时持续互动」才用 WebSocket;「只是查个进度」就老实轮询。 别一上来就上最重的那个。
还有一个容易被忽略的细节:浏览器内置的 EventSource 只支持 GET,且不能带请求体。所以「POST 一段问题过去、然后流式收答案」这种最常见的形态,前端多半要用 fetch 加 ReadableStream 自己读流。后端倒是无所谓的,SSE 只负责把字节按事件格式吐出去。
2、接进 Spring Boot:分层比代码量更重要
把 Agent 接进一个已有的 Spring Boot 服务,最容易犯的错是把所有东西塞进 Controller:构造 Agent、发消息、拼 SSE、记日志、写会话,全在一个方法里。Demo 阶段完全没问题,等到你要接第二个 Agent、要加多轮上下文、要在别处复用同一套编排逻辑时,就会发现它没法拆。
比较稳的分法是三层:协议层只负责 SSE 的格式与生命周期;编排层封装 HarnessAgent 的调用,把「一问一答」抽象成可迭代的输出流;基础设施层管模型、工具、会话存储这些可以替换的东西。
package com.example.agent;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicLong;
/**
* 把 Agent 暴露成一个 SSE 端点。
* 运行环境:Spring Boot 应用(依赖与版本以官方文档为准)
* 说明:AgentService 是本工程自定义的编排层,
* HarnessAgent 的具体类名、构造参数与调用方式以官方文档为准,
* 这里只保留分层结构与流式转发的骨架。
*/
@RestController
@RequestMapping("/api/agent")
public class AgentStreamController {
private final ExecutorService sseExecutor = Executors.newCachedThreadPool();
private final AgentService agentService;
private final AtomicLong eventSeq = new AtomicLong();
public AgentStreamController(AgentService agentService) {
this.agentService = agentService;
}
@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter stream(@RequestBody ChatRequest request) {
// 超时时间给足:Agent 思考较久时,别让容器提前掐断连接
SseEmitter emitter = new SseEmitter(0L);
sseExecutor.execute(() -> {
try {
// 关键:Agent 每产出一段就推一段,而不是等全部生成完再一次性返回
agentService.streamAnswer(request.getQuestion())
.forEach(chunk -> sendChunk(emitter, chunk));
emitter.complete();
} catch (Exception ex) {
// 出错也要给前端一个明确事件,否则页面会一直转圈
sendEvent(emitter, "error", String.valueOf(ex.getMessage()));
emitter.complete();
}
});
return emitter;
}
private void sendChunk(SseEmitter emitter, String chunk) {
// 带 id 的事件可以在断线重连后用于续传
sendEvent(emitter, "message", chunk);
}
private void sendEvent(SseEmitter emitter, String name, String data) {
try {
emitter.send(SseEmitter.event()
.id(String.valueOf(eventSeq.incrementAndGet()))
.name(name)
.data(data));
} catch (Exception ex) {
throw new IllegalStateException("SSE 推送失败", ex);
}
}
}
这段骨架里有三个判断值得单独拎出来说。
其一,线程不能留在请求线程上。 SSE 的响应要一直开着直到流结束,如果你在 Controller 里同步等 Agent 出结果,这个请求线程就被占住了,并发一上来就会把业务接口拖垮。所以要用独立线程池承接 Agent 的执行,并且给线程池设上界。
其二,超时值不要随手写。 默认值往往短得离谱,Agent 多想两轮就断线;写成 0(不超时)又意味着这条连接会一直挂着,要配合网关的空闲超时策略一起看。
其三,错误要走同一条流。 别把异常直接抛给容器,容器会返回一个普通的 JSON 错误体,前端拿到的 SSE 流就断了,页面转圈转到天荒地老。在流里显式发一个 error 事件,前端才有办法收尾。
3、SSE 流式输出:把「等答案」变成「看答案」
SSE 的报文其实极其简单,一条消息由若干行「字段名: 值」组成,以一个空行结束。data: 是正文,event: 是事件名,id: 是事件序号(可用于重连续传),retry: 告诉浏览器断线后等多久再连。
理解了格式,验证也就一步到位。用 curl 打一次接口,看它是不是真的一段一段往外吐——注意 -N 这个参数,它关掉的是 curl 的输出缓冲,不加它,你会一直等不到内容,误以为是接口卡住了。
#!/usr/bin/env bash
# 验证 SSE 端点是否真的逐段返回
# 运行环境:macOS 自带 Bash 即可
set -euo pipefail
URL="http://127.0.0.1:8080/api/agent/chat/stream"
curl -N -sS -X POST "${URL}" \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-d '{"question":"用三句话解释什么是 Agent 的流式输出"}' \
| while IFS= read -r line; do
case "${line}" in
data:*) printf '内容: %s\n' "${line#data: }" ;;
event:*) printf '[事件] %s\n' "${line#event: }" ;;
id:*) printf '[序号] %s\n' "${line#id: }" ;;
*) : ;;
esac
done
同一段逻辑搬到浏览器端,就是 fetch + ReadableStream 按块读、按空行切事件。流式输出真正的价值不只是「好看」,而是把等待时间摊薄:Agent 还在想的时候,用户已经看到第一段,用户能提前判断要不要打断。
4、实战里最容易踩的四个坑
坑一:缓冲。 链路上有好几层缓冲——curl 的、Nginx 的、浏览器 fetch 的、框架的。结果就是后端明明 send 了,前端一个字都收不到。逐层排查很折磨人,所以第一步就写个 curl -N 的验证脚本,问题出在哪一层一目了然。
坑二:线程被占死。 上一节说过,SSE 天然占住一个连接。要么限制并发,要么异步化,别让「开一个对话」变成「占一个业务线程」。
坑三:消息格式不合法。 一条事件必须以空行收尾;JSON 最好单行序列化,不要手工拼多行;data: 后面那个空格可有可无,但客户端解析习惯不同,最好保持统一。
坑四:长连接被中间层掐断。 网关与负载均衡都有空闲超时,Agent 思考久了没动静,连接就被回收。更隐蔽的是心跳缺失:Agent 安静思考时本来就没什么可推的,连接看起来是死的。解法是定期发一条注释行(形如 : ping)作为心跳,它对客户端是透明的。
写在最后
「P5:给 Agent 装上对话框」这一篇的落点,其实不在某个框架的用法,而在把 Agent 当成一条需要长期维护的服务链路来看:入口要有协议层、编排层、基础设施层三层,输出要走 SSE 这样天生适合单向推送的通道,异常、心跳、缓冲、重连这四件事要在第一版就考虑进去。
我的判断是:Agent 从 Demo 走向可用,卡住绝大多数团队的从来不是模型能力,而是工程化的一半。谁先把「对话入口」做成稳定的服务,谁就能真的让人天天用起来。
相关阅读
- 给 Agent 装上对话框——AgentScope-Java 接入 Spring Boot 与 SSE 流式实战 —— 本文原文,「P5」系列第 5 篇
- MDN:Server-sent events —— SSE 协议与浏览器 API 参考
- Spring 官方文档 ——
SseEmitter与 Web MVC 配置以官方文档为准 - 掘金搜索:AgentScope —— 更多 AgentScope 实践文章
想把 AI 工具接进自己的团队、或把这套内容流水线搬到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见:查看技术服务
文中链接
整理自本文的外部链接,请以来源页面说明为准。