VoltAgent 实时流式输出指南:SSE 与 WebSocket 端点全解析

原创2026-09-24 09:00:281,637 阅读
文章标签:人工智能AI AgentAgent 框架多智能体工具调用MCP 服务Agent 记忆RAGAgent 工作流Agent 编排可观测性AI 评测语音后端

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/*,官方建议通过以下两种方式之一实施:

  1. 前置代理(proxy):在网关/反向代理层对 /ws/* 路径做身份校验;
  2. 自定义 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。

登录后查看全文
voltagent