feat: add resumable streaming support via @voltagent/resumable-streams

.changeset/common-geese-fetch.md

@@ -0,0 +1,81 @@
+---
+"@voltagent/resumable-streams": patch
+"@voltagent/serverless-hono": patch
+"@voltagent/server-core": patch
+"@voltagent/server-hono": patch
+"@voltagent/core": patch
+---
+
+feat: add resumable streaming support via @voltagent/resumable-streams, with server adapters that let clients reconnect to in-flight streams.
+
+```ts
+import { openai } from "@ai-sdk/openai";
+import { Agent, VoltAgent } from "@voltagent/core";
+import {
+  createResumableStreamAdapter,
+  createResumableStreamRedisStore,
+} from "@voltagent/resumable-streams";
+import { honoServer } from "@voltagent/server-hono";
+
+const streamStore = await createResumableStreamRedisStore();
+const resumableStream = await createResumableStreamAdapter({ streamStore });
+
+const agent = new Agent({
+  id: "assistant",
+  name: "Resumable Stream Agent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o-mini"),
+});
+
+new VoltAgent({
+  agents: { assistant: agent },
+  server: honoServer({
+    resumableStream: { adapter: resumableStream },
+  }),
+});
+
+await fetch("http://localhost:3141/agents/assistant/chat", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: `{"input":"Hello!","options":{"conversationId":"conv-1","userId":"user-1","resumableStream":true}}`,
+});
+
+// Resume the same stream after reconnect/refresh
+const resumeResponse = await fetch(
+  "http://localhost:3141/agents/assistant/chat/conv-1/stream?userId=user-1"
+);
+
+const reader = resumeResponse.body?.getReader();
+const decoder = new TextDecoder();
+while (reader) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const chunk = decoder.decode(value, { stream: true });
+  console.log(chunk);
+}
+```
+
+AI SDK client (resume on refresh):
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+
+const { messages, sendMessage } = useChat({
+  id: chatId,
+  messages: initialMessages,
+  resume: true,
+  transport: new DefaultChatTransport({
+    api: "/api/chat",
+    prepareSendMessagesRequest: ({ id, messages }) => ({
+      body: {
+        message: messages[messages.length - 1],
+        options: { conversationId: id, userId },
+      },
+    }),
+    prepareReconnectToStreamRequest: ({ id }) => ({
+      api: `/api/chat/${id}/stream?userId=${encodeURIComponent(userId)}`,
+    }),
+  }),
+});
+```

examples/README.md

@@ -113,6 +113,7 @@ Create a multi-agent research workflow where different AI agents collaborate to
 - [MCP Server](./with-mcp-server) — Implement and run a local MCP server that exposes custom tools.
 - [Netlify Functions](./with-netlify-functions) — Ship serverless agent APIs on Netlify.
 - [Next.js](./with-nextjs) — React UI with agent APIs and streaming responses.
+- [Next.js + Resumable Streams](./with-nextjs-resumable-stream) — AI Elements chat UI with VoltAgent and resumable streams.
 - [Nuxt](./with-nuxt) — Vue/Nuxt front‑end talking to VoltAgent APIs.
 - [Offline Evals](./with-offline-evals) — Batch datasets and score outputs for regression testing.
 - [Peaka (MCP)](./with-peaka-mcp) — Integrate Peaka services via MCP tools.
@@ -132,6 +133,8 @@ Create a multi-agent research workflow where different AI agents collaborate to
 - [Turso](./with-turso) — Persist memory on LibSQL/Turso with simple setup.
 - [Vector Search](./with-vector-search) — Semantic memory with embeddings and automatic recall during chats.
 - [Vercel AI](./with-vercel-ai) — VoltAgent with Vercel AI SDK provider and streaming.
+- [Resumable Streams](./with-resumable-streams) — Persist and resume chat streams with Redis-backed SSE storage.
+- [VoltOps Resumable Streams](./with-voltops-resumable-streams) — Persist and resume chat streams with VoltOps managed storage.
 - [ViteVal](./with-viteval) — Integrate ViteVal to evaluate agents and prompts.
 - [Voice (ElevenLabs)](./with-voice-elevenlabs) — Convert agent replies to speech using ElevenLabs TTS.
 - [Voice (OpenAI)](./with-voice-openai) — Speak responses with OpenAI’s TTS voices.

examples/with-nextjs-resumable-stream/.env.example

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=sk-proj-
+REDIS_URL=redis://localhost:6379

examples/with-nextjs-resumable-stream/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/with-nextjs-resumable-stream/README.md

@@ -0,0 +1,53 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1800" alt="435380213-b6253409-8741-462b-a346-834cd18565a9" src="https://github.com/user-attachments/assets/452a03e7-eeda-4394-9ee7-0ffbcf37245c" />
+</a>
+
+<br/>
+<br/>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a> |
+    <a href="https://s.voltagent.dev/discord">Discord</a> |
+    <a href="https://voltagent.dev/blog/">Blog</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+    <strong>VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.</strong><br>
+Escape the limitations of no-code builders and the complexity of starting from scratch.
+    <br />
+    <br />
+</div>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev)
+
+</div>
+
+<br/>
+
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="896" alt="VoltAgent Schema" src="https://github.com/user-attachments/assets/f0627868-6153-4f63-ba7f-bdfcc5dd603d" />
+</a>
+
+</div>
+
+## VoltAgent: Build AI Agents Fast and Flexibly
+
+VoltAgent is an open-source TypeScript framework for creating and managing AI agents. It provides modular components to build, customize, and scale agents with ease. From connecting to APIs and memory management to supporting multiple LLMs, VoltAgent simplifies the process of creating sophisticated AI systems. It enables fast development, maintains clean code, and offers flexibility to switch between models and tools without vendor lock-in.
+
+## Try Example
+
+```bash
+npm create voltagent-app@latest -- --example with-nextjs-resumable-stream
+```

examples/with-nextjs-resumable-stream/app/api/chat/[id]/stream/route.ts

@@ -0,0 +1,37 @@
+import { getResumableStreamAdapter } from "@/lib/resumable-stream";
+import { supervisorAgent } from "@/voltagent";
+import { safeStringify } from "@voltagent/internal/utils";
+import { createResumableChatSession } from "@voltagent/resumable-streams";
+
+const jsonError = (status: number, message: string) =>
+  new Response(safeStringify({ error: message, message }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+
+export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  if (!id) {
+    return jsonError(400, "conversationId is required");
+  }
+
+  const userId = new URL(request.url).searchParams.get("userId");
+  if (!userId) {
+    return jsonError(400, "userId is required");
+  }
+  const agentId = supervisorAgent.id;
+  const resumableStream = await getResumableStreamAdapter();
+  const session = createResumableChatSession({
+    adapter: resumableStream,
+    conversationId: id,
+    userId,
+    agentId,
+  });
+
+  try {
+    return await session.resumeResponse();
+  } catch (error) {
+    console.error("[API] Failed to resume stream:", error);
+    return new Response(null, { status: 204 });
+  }
+}

examples/with-nextjs-resumable-stream/app/api/chat/route.ts

@@ -0,0 +1,87 @@
+import { getResumableStreamAdapter } from "@/lib/resumable-stream";
+import { supervisorAgent } from "@/voltagent";
+import { setWaitUntil } from "@voltagent/core";
+import { safeStringify } from "@voltagent/internal/utils";
+import { createResumableChatSession } from "@voltagent/resumable-streams";
+import { after } from "next/server";
+
+const jsonError = (status: number, message: string) =>
+  new Response(safeStringify({ error: message, message }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const messages = Array.isArray(body?.messages) ? body.messages : [];
+    const message = body?.message;
+    const options =
+      body?.options && typeof body.options === "object"
+        ? (body.options as Record<string, unknown>)
+        : undefined;
+    const conversationId =
+      typeof options?.conversationId === "string" ? options.conversationId : undefined;
+    const userId = typeof options?.userId === "string" ? options.userId : undefined;
+    const input =
+      message !== undefined ? (typeof message === "string" ? message : [message]) : messages;
+
+    if (!conversationId) {
+      return jsonError(400, "options.conversationId is required");
+    }
+
+    if (!userId) {
+      return jsonError(400, "options.userId is required");
+    }
+
+    if (isEmptyInput(input)) {
+      return jsonError(400, "Message input is required");
+    }
+
+    // Enable non-blocking OTel export for Vercel/serverless
+    // This ensures spans are flushed in the background without blocking the response
+    setWaitUntil(after);
+
+    const agentId = supervisorAgent.id;
+    const resumableStream = await getResumableStreamAdapter();
+    const session = createResumableChatSession({
+      adapter: resumableStream,
+      conversationId,
+      userId,
+      agentId,
+    });
+
+    try {
+      await session.clearActiveStream();
+    } catch (error) {
+      console.error("[API] Failed to clear active resumable stream:", error);
+    }
+
+    // Stream text from the supervisor agent with proper context
+    // The agent accepts UIMessage[] directly
+    const result = await supervisorAgent.streamText(input, {
+      userId,
+      conversationId,
+    });
+
+    return result.toUIMessageStreamResponse({
+      consumeSseStream: session.consumeSseStream,
+      onFinish: session.onFinish,
+    });
+  } catch (error) {
+    console.error("[API] Chat error:", error);
+    return jsonError(500, "Internal server error");
+  }
+}
+
+function isEmptyInput(input: unknown) {
+  if (input == null) {
+    return true;
+  }
+
+  if (typeof input === "string") {
+    return input.trim().length === 0;
+  }
+
+  return Array.isArray(input) && input.length === 0;
+}

examples/with-nextjs-resumable-stream/app/api/messages/route.ts

@@ -0,0 +1,17 @@
+import { sharedMemory } from "@/voltagent/memory";
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const conversationId = searchParams.get("conversationId");
+  const userId = searchParams.get("userId");
+
+  if (!conversationId || !userId) {
+    return Response.json({ error: "conversationId and userId are required" }, { status: 400 });
+  }
+
+  const uiMessages = await sharedMemory.getMessages(userId, conversationId);
+
+  return Response.json({
+    data: uiMessages || [],
+  });
+}