跳到主要内容

stream 接口与 SSE 事件协议

Super Agent 的聊天回答不是"等模型想完再一次性返回"，而是模型每产出一小段文字就立刻推给前端，用户能看到"边想边写"的效果。这背后靠的就是 SSE（Server-Sent Events）协议。

这篇文档会把 SSE 事件协议的实现细节拆开来讲——后端定义了哪些事件类型、每种事件的 JSON 长什么样、事件是怎么被格式化和推送出去的、流是怎么创建和关闭的。

SSE 协议概览​

先看一张时序图，对整个 SSE 事件流有个直观印象：

PlantUML 图
PlantUML 图
为什么用 SSE 而不是 WebSocket？

SSE 是单向的（服务端 → 客户端），天然适合"模型输出推送"这种场景。它基于 HTTP，不需要额外的协议升级，部署和调试都更简单。WebSocket 是双向的，适合聊天室那种"双方都在发消息"的场景，但对于"用户提问 → 模型回答"这种请求-响应模式来说，SSE 就够了。

事件类型与 JSON 格式​

Super Agent 定义了 6 种 SSE 事件类型，每种事件都是一个 JSON 字符串，通过 SSE 流逐条推送给前端：

事件类型type 字段用途触发时机
文本增量text模型输出的正文片段模型每产出一个 chunk
思考步骤thinking后端正在做什么编排器分析、执行器启动时
状态通知status会话状态变更用户停止生成时
错误通知error执行失败的错误信息任何阶段出错时
引用来源reference回答引用的证据来源正文输出完成后
推荐追问recommend建议用户接下来问什么引用发送完成后

每种事件的 JSON 结构都遵循统一的格式：

{
  "type": "text",
  "content": "这是模型输出的一段文字",
  "timestamp": "2025-03-15T08:30:00.123Z",
  "conversationId": "abc123",
  "exchangeId": 1001
}

其中 type 和 content 是必有字段，timestamp 是事件产生的时间戳，conversationId 和 exchangeId 是可选的会话元信息——有了它们，前端就能知道每条事件归属哪个会话、哪个轮次。

引用和推荐事件会多一个 count 字段，告诉前端这批数据一共有多少条：

{
  "type": "reference",
  "content": [
    { "title": "文档A", "sectionPath": "第三章/3.1", "snippet": "..." },
    { "title": "文档B", "sectionPath": "第五章/5.2", "snippet": "..." }
  ],
  "count": 2,
  "timestamp": "2025-03-15T08:30:05.456Z",
  "conversationId": "abc123",
  "exchangeId": 1001
}

这些元信息由 StreamEventMetadata 这个 record 承载：

// StreamEventMetadata.java —— SSE 事件元数据
public record StreamEventMetadata(
    String conversationId,  // 会话 ID
    Long exchangeId         // 轮次 ID
) {
}

付费内容提示

该文档的全部内容仅对「码力全开」项目实战&技术讲解 知识星球用户开放

加入星球，一次获得完整项目资料、全栈技术知识库和长期答疑服务。

100万+字全栈技术知识库深入讲解技术核心、数据库、中间件和分布式等内容
8套热门的实战项目持续更新的企业级项目覆盖高并发、微服务、数据中台 和 AI Agent 等方向
AI 技术知识大模型面试详解覆盖 AI 模型原理、Agent、RAG、MCP、Skills、Harness 等核心知识点
文档 + 视频两种讲解形式既能系统阅读，也能跟随视频理解核心业务

完整项目实战资料

每套项目均包含从 0 到 1 讲解文档核心业务讲解视频

从基础项目到复杂业务场景，项目资料会持续更新。

8 套项目
  • 01Nexus Agent AI 智能体
  • 02Nexus Agent Pro 完全版
  • 03黑马点评Plus
  • 04大麦
  • 05大麦Pro
  • 06大麦AI
  • 07流量切换
  • 08数据中台

加入后还能获得

进入星球后，即可享受上述所有服务，保证不会再有其他隐藏费用。

从学习、面试到项目启动，都可以继续获得支持。

  • 1 对 1 解答项目和技术问题都可以提问
  • 针对性补充没有讲清楚的内容会继续补充
  • 面试与简历指导梳理回答技巧和项目亮点
  • 中间件云环境项目依赖可以直接接入使用
  • 面试后复盘被问住的问题可以继续交流
  • 远程问题解决项目启动问题可协助排查
知识星球二维码

扫码进入知识星球

  1. 打开微信，扫描左侧二维码，加入「码力全开」项目实战&技术讲解 知识星球
  2. 查看星球使用指导，获取完整项目讲解资料索引
解锁全部付费内容
🎁优惠