HTTP 流式与 SSE 双通道

流式体验不依赖“同一个 POST 响应体里推 token”。Agent Forge 使用双通道：写通道触发会话调度并可选等待本轮结束；读通道用 SSE 长连接订阅总线事件，接收文本增量、工具状态与会话忙闲。

双通道

flowchart LR
  C[Client] -->|POST /session/.../message| W[写通道 SessionPrompt]
  C -->|GET /event| R[读通道 SSE]
  W --> Loop[runLoop / Processor]
  Loop --> Bus[Bus]
  Bus --> R

通道	典型接口	作用
写	POST .../message 或 .../prompt_async	下达任务；同步接口等到本轮结果，异步接口先受理
读	GET /event	text/event-stream，持续收事件

端到端时序

sequenceDiagram
  participant C as Client
  participant E as SSE
  participant H as HTTP
  participant L as runLoop
  participant B as Bus

  C->>E: 订阅 /event
  E-->>C: connected / heartbeat
  C->>H: POST message
  H->>L: prompt
  L->>B: PartDelta / status
  B-->>E: 推送
  E-->>C: 增量渲染
  L-->>H: 本轮 assistant
  H-->>C: 同步响应（若走同步接口）

客户端应在发 prompt 之前或同时建立 SSE。只发 POST、不订阅事件时，通常只能在请求结束后看到整包结果。

服务端行为要点

• 订阅总线，将事件写入 SSE 流
• 定期 heartbeat，降低代理空闲断连概率
• 连接中止时清理订阅
• 另有全局级事件与同步事件通道，服务控制面与多实例同步场景；会话 UI 主路径仍是实例级 /event

事件从哪来

来源	典型内容
Processor	文本 / 推理 Part 增量
会话投影	Message / Part 更新类同步事件
会话状态	busy / idle / retry
权限	待用户授权

updatePartDelta 可只发总线；完整 Part 在 text-end 等时机落库。因此“SSE 已有 delta、存储稍后对齐”是预期行为。见消息模型与跨轮记忆。

同步与异步 prompt

接口	HTTP 语义	进度
同步 message/prompt	等到本轮结束再返回助手消息	仍应靠 SSE 看增量
prompt_async	先返回受理（如 204），后台跑同一套 SessionPrompt	只靠 SSE 或事后读消息

SDK 封装见SDK 到 Server 完整流程。

排障

现象	优先核对
UI 不流式	是否订阅 /event；代理是否缓冲 SSE
偶发断流	heartbeat 是否到达；反向代理超时
异步任务“没动静”	是否看错成同步响应体；总线是否有会话错误事件

---

相关阅读：

• 端到端主链路
• SDK 到 Server 完整流程
• 消息模型与跨轮记忆