VoltAgent 实时流式输出指南:SSE 与 WebSocket 端点全解析
VoltAgent 实时流式输出指南:SSE 与 WebSocket 端点全解析
VoltAgent 提供了基于 Server-Sent Events(SSE)与 WebSocket 两套实时输出通道,覆盖 Agent 文本生成、结构化对象生成、工作流执行以及日志/可观测性数据的实时推送场景。本文基于 website/docs/api/streaming.md 整理,并结合 server-core 与 server-hono 的源码实现,完整讲解各端点的请求格式、事件协议与前后端消费方式,读完后你可以直接接入 useChat、自定义 SSE 客户端或实时日志面板。
实时能力概览
VoltAgent 服务器(默认监听 http://localhost:3141)提供两类实时通道:
- SSE(Server-Sent Events):单向服务器推流,用于 Agent 文本、结构化对象与工作流执行事件的实时下发;
- WebSocket:全双工通道,基础路径为
/ws,用于连接测试、实时日志流与可观测性(span/log)推送。
从源码结构看,这些端点均由框架无关的 路由定义 统一声明(如 streamText、chatStream、streamObject、streamWorkflow),再由各服务端实现(Hono、Elysia 等)绑定到 HTTP 层,具体处理逻辑集中在 agent.handlers.ts 与 workflow.handlers.ts。
SSE 端点总览
| 端点 | 说明 |
|---|---|
POST /agents/:id/chat |
以 AI SDK UI 消息格式流式返回文本生成(useChat 兼容) |
POST /agents/:id/stream |
流式返回原始 fullStream 事件(覆盖全部事件类型) |
POST /agents/:id/stream-object |
流式返回结构化对象的局部更新(partial object updates) |
POST /workflows/:id/stream |
流式返回工作流执行事件 |
其中 :id 为已注册 Agent / Workflow 的 ID。所有 SSE 响应的 Content-Type 均为 text/event-stream(见 definitions.ts 中各端点的响应定义),请求体为 JSON,至少包含 input 字段。
Agents: Chat Stream(useChat 兼容)
POST /agents/:id/chat 针对 AI SDK 的 useChat Hook 做了优化,返回的是 UI 消息格式(message format),前端无需手动拼接消息即可直接渲染,适合聊天式界面。
使用 curl 验证
curl -N -X POST http://localhost:3141/agents/assistant/chat \
-H "Content-Type: application/json" \
-d '{"input": "Write a haiku"}'
-N 参数禁用 curl 的缓冲,保证事件到达即输出。
React 端接入(@ai-sdk/react)
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
const transport = new DefaultChatTransport({
api: "http://localhost:3141/agents/assistant/chat",
prepareSendMessagesRequest({ messages }) {
return {
body: {
input: [messages[messages.length - 1]],
options: {
/* your options */
},
},
};
},
});
const { messages, sendMessage } = useChat({ transport });
要点说明:
- 通过
DefaultChatTransport自定义请求体:把消息数组的最后一条作为input传给后端,options位置可以放入模型参数、工具配置等选项; useChat({ transport })直接消费该 transport,返回的messages会随流式事件自动增量更新,sendMessage负责发起请求。
从源码看,该端点在 agent.handlers.ts 中对应 handleChatStream:它调用 agent.streamText(input, options) 后将生成流编码为 UI 消息格式的 SSE;当请求携带 resumable 配置时还会把流持久化(consumeSseStream),并通过 GET /agents/:id/chat/:conversationId/stream(resumeChatStream)支持断线续流——该恢复端点无活动流时返回 204,未配置可续流时会回退到非续流模式。
Agents: Raw Stream(fullStream)
POST /agents/:id/stream 直接暴露 fullStream 的全部事件类型,适合需要完整掌控流处理的场景(自定义 UI、日志采集、事件驱动架构等)。路由定义(definitions.ts 中的 streamText)明确说明它提供"包括文本增量、工具调用与工具结果在内的全部流事件"。
使用 curl 验证
curl -N -X POST http://localhost:3141/agents/assistant/stream \
-H "Content-Type: application/json" \
-d '{"input": "Write a poem"}'
JavaScript 消费示例
const res = await fetch("http://localhost:3141/agents/assistant/stream", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ input: "Write a poem" }),
});
const reader = res.body!.getReader();
const dec = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = dec.decode(value);
// Parse SSE: data: {type: 'text-delta', delta: '...'}\n\n
const lines = chunk.split("\n");
for (const line of lines) {
if (line.startsWith("data: ")) {
const event = JSON.parse(line.slice(6));
// Handle event types like:
// - lifecycle: 'start', 'start-step', 'finish-step', 'finish', 'abort', 'error'
// - text: 'text-start', 'text-delta', 'text-end'
// - reasoning: 'reasoning-start', 'reasoning-delta', 'reasoning-end'
// - tools: 'tool-input-start', 'tool-input-delta', 'tool-input-end', 'tool-call', 'tool-result', 'tool-error'
// - other: 'source', 'file', 'raw'
}
}
}
源码实现上(agent.handlers.ts 的 handleStreamText),服务端会 for await (const part of fullStream) 遍历生成流,将每个 part 编码为 JSON 化的 SSE 事件写入 ReadableStream,并以 Content-Type: text/event-stream 返回——客户端看到的正是上例中 data: {...}\n\n 格式。
fullStream 常见事件类型
| 类别 | 事件 |
|---|---|
| Lifecycle(生命周期) | start、start-step、finish-step、finish、abort、error |
| Text(文本) | text-start、text-delta、text-end |
| Reasoning(推理) | reasoning-start、reasoning-delta、reasoning-end(仅当模型/提供商返回推理痕迹时发出) |
| Tools(工具) | tool-input-start、tool-input-delta、tool-input-end、tool-call、tool-result、tool-error |
| Other(其他) | source、file、raw |
各事件对象均以 JSON 编码,字段因类型而异(如 text-delta 携带 delta 文本,tool-call 携带工具名与参数,error 携带错误信息)。按 type 字段分支处理即可实现完整的流式交互。
Agents: Stream Object(结构化对象流)
POST /agents/:id/stream-object 用于流式生成符合 JSON Schema 的结构化对象:服务端边生成边推送局部更新,客户端可以实时展示对象构建进度,最终收到完整对象。该端点要求请求体同时提供 input 与 schema。
使用 curl 验证
curl -N -X POST http://localhost:3141/agents/assistant/stream-object \
-H "Content-Type: application/json" \
-d '{
"input": "List two cities with populations",
"schema": {"type": "array", "items": {"type": "object", "properties": {"name": {"type":"string"}, "pop": {"type":"number"}}}}
}'
响应为 text/event-stream 行,内容为 JSON,可能包含局部更新(partial updates)或最终完整对象。源码中(agent.handlers.ts 的 handleStreamObject)会将请求中的 JSON Schema 转换为 Zod schema(兼容 zod v3 与 v4,对应 convertJsonSchemaToZod / convertJsonSchemaToZodV3 两条路径),再调用 agent.streamObject 完成生成。
Workflows: Stream Execution(工作流执行流)
POST /workflows/:id/stream 在执行工作流的同时实时推送执行事件。与同步端点 POST /workflows/:id/execute(跑完返回最终结果)不同,流式端点适合长耗时、需要中断/恢复(suspension)的工作流——路由定义(definitions.ts 的 streamWorkflow)明确说明:"流在挂起期间保持打开,并在恢复后继续"。
使用 curl 验证
curl -N -X POST http://localhost:3141/workflows/my-workflow/stream \
-H "Content-Type: application/json" \
-d '{"input": {"id": "123"}}'
事件类型
workflow-start:工作流开始执行;step-start:某个步骤开始;step-complete:某个步骤完成;workflow-suspended:工作流挂起(等待外部确认/恢复);workflow-complete:工作流执行完毕;workflow-result:最终结果事件,通常作为流末尾的收尾事件。
从源码结构看,workflow.handlers.ts 中维护了 activeWorkflowStreamSessions 会话表:每个会话持有订阅者集合、replayBuffer(回放缓冲区,默认上限 500 条,对应 MAX_STREAM_REPLAY_HISTORY)与递增序列号 nextSequence;挂起期间流不关闭,恢复后(resume)继续推送。同时提供了 GET /workflows/:id/executions/:executionId/stream(attachWorkflowStream)用于附加到进行中的执行流,可通过 Last-Event-ID 请求头或 fromSequence 查询参数在重连时回放错过的历史事件。
WebSockets
WebSocket 基础路径为 /ws,连接建立后即可实时收发 JSON 消息。
连接测试 / Echo
ws://localhost:3141/ws 用于连通性测试:连接建立后服务端会立即下发一条测试消息,客户端发送的每条消息都会被原样回显(handlers.ts 中的 handleTestConnection)。
const testWs = new WebSocket("ws://localhost:3141/ws");
实时日志流
ws://localhost:3141/ws/logs 推送系统实时日志,支持通过查询参数过滤:
| 参数 | 说明 |
|---|---|
level |
日志级别(如 info、debug、error),低于该级别的日志被过滤 |
agentId |
按 Agent ID 过滤 |
workflowId |
按 Workflow ID 过滤 |
executionId |
按执行 ID 过滤(同时匹配 executionId 与 parentExecutionId) |
conversationId |
按会话 ID 过滤 |
since / until |
时间范围过滤 |
limit |
初始历史日志条数上限 |
const logsWs = new WebSocket("ws://localhost:3141/ws/logs?level=info");
logsWs.onmessage = (e) => console.log("log event", JSON.parse(e.data));
底层由 log-stream.ts 的 LogStreamManager 实现:客户端接入时先回放全局日志缓冲区内符合过滤条件的历史日志(默认上限 100 条),随后监听全局 log buffer 的 log-added 事件,按各客户端的过滤器逐条广播(type: "initial" 或 type: "update");级别优先级为 fatal(60) > error(50) > warn(40) > info(30) > debug(20) > trace(10)。客户端也可发送 {"type": "updateFilter", "filter": {...}} 消息动态调整过滤条件。
实时可观测性(span 与 log)
ws://localhost:3141/ws/observability 推送 OpenTelemetry 相关的 span 事件与日志记录,支持 ?entityType=agent|workflow&entityId=<id> 过滤根实体:
const obsWs = new WebSocket(
"ws://localhost:3141/ws/observability?entityType=agent&entityId=assistant"
);
obsWs.onmessage = (e) => console.log("obs event", JSON.parse(e.data));
从 observability-handler.ts 的实现看,该通道通过 WebSocketEventEmitter 单例订阅 OpenTelemetry span 事件,并向订阅者广播;entityId / entityType 过滤基于 span 属性 entity.id 与 entity.type(根 span 判断依据为 !event.span?.parentSpanId),子 span 不过滤以保证链路完整;连接建立时会收到 CONNECTION_SUCCESS 确认消息,客户端可发送 PING(回复 PONG)与 SUBSCRIBE(回复 SUBSCRIPTION_SUCCESS)进行心跳与订阅管理。
消息信封
可观测性通道的推送消息统一使用信封结构:
- span 事件:
{ type: "OBSERVABILITY_EVENT", success: true, data: {...} } - 日志事件:
{ type: "OBSERVABILITY_LOG", success: true, data: {...} }
安全注意事项
WebSocket 端点目前未做鉴权(unauthenticated)。如需保护 /ws/*,官方建议通过以下两种方式之一实施:
- 前置代理(proxy):在网关/反向代理层对
/ws/*路径做身份校验; - 自定义 Provider:在服务端实现中接入自定义认证逻辑。
在接入生产环境前,请务必评估日志流、可观测性流是否会被未授权方读取,并按需为其增加访问控制。
小结
- 聊天界面优先用
POST /agents/:id/chat+useChat,零手工消息组装; - 需要细粒度控制(工具调用、推理痕迹、生命周期)时用
POST /agents/:id/stream消费fullStream; - 结构化输出用
POST /agents/:id/stream-object,配合 JSON Schema 实时展示对象构建; - 长工作流用
POST /workflows/:id/stream,挂起恢复不断流,并可用附加端点断线重连; - 运维侧用
/ws/logs与/ws/observability构建实时日志与链路面板,注意默认无鉴权。
如需深入各端点的服务端实现细节,可继续阅读 agent.handlers.ts、workflow.handlers.ts 与 websocket 目录下的 handlers.ts、log-stream.ts、observability-handler.ts;HTTP 层绑定示例可参考 server-hono/src/routes/index.ts。