给 Agent 装上对话框——AgentScope-Java 接入 Spring Boot 与 SSE 流式实战

「P5:给 Agent 装上对话框」系列解读:把 HarnessAgent 接进 Spring Boot,用 SSE 把回答逐段推给浏览器。这篇把对话入口的设计、三层代码分工与 SSE 流式输出的四个实战坑逐个拆开,并给出可直接改造的 Controller 骨架与 curl 验证命令。

文章目录

原文:给 Agent 装上对话框——AgentScope-Java 接入 Spring Boot 与 SSE 流式实战

做 Agent 的团队大概都遇到过同一种尴尬:能力早就跑通了,Demo 也惊艳,可要让业务同事真正用起来,还得先装环境、敲命令行、盯着终端刷字。 Agent 缺的往往不是能力,而是一个像样的「入口」。

「P5:给 Agent 装上对话框」这个系列处理的正是这件事:把 HarnessAgent 接进 Spring Boot,用 SSE 把回答一段一段推到浏览器上,让 Agent 从「一个能跑的脚本」变成「一个能对话的服务」。这是该系列的第 5 篇。我把它拆成三个可落地的工程问题来读:入口该怎么设计、代码该怎么分层、流式输出怎么才不翻车。

1、Agent 要的不是又一个 API,而是一个「能对话的入口」

1、Agent 要的不是又一个 API,而是一个「能对话的入口」(AI 生成示意图)

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 走向可用,卡住绝大多数团队的从来不是模型能力,而是工程化的一半。谁先把「对话入口」做成稳定的服务,谁就能真的让人天天用起来。

相关阅读

想把 AI 工具接进自己的团队、或把这套内容流水线搬到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见:查看技术服务

文中链接

整理自本文的外部链接,请以来源页面说明为准。

给 Agent 装上对话框——AgentScope-Java 接入 Spring Boot 与 SSE 流式实战 · 阿凡达博客