OpenParable
Skip to content
← Back to skills

Vercel AI SDK

Development
vercel-ai-sdk

Vercel AI SDK is an Agent Skill for development published in the durable-streams/durable-streams repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Vercel AI SDK integration with Durable Streams. createDurableChatTransport() for useChat(), toDurableStreamResponse() for server-side streaming, resumable chat sessions with reconnectToStream(), read proxy pattern for auth. Load when building chat apps with Vercel AI SDK (@ai-sdk/react) and durable streams.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/durable-streams/durable-streams/blob/HEAD/packages/aisdk-transport/skills/vercel-ai-sdk/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/vercel-ai-sdk, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

This skill builds on durable-streams/getting-started. Read it first for setup and offset basics.

Durable Streams — Vercel AI SDK

Drop-in transport for useChat() that writes AI responses to durable streams. Chat sessions survive page refreshes and can be resumed mid-generation.

Setup

Client

import { useMemo } from "react"
import { useChat } from "@ai-sdk/react"
import { createDurableChatTransport } from "@durable-streams/aisdk-transport"

function Chat({ id, initialMessages }) {
  const transport = useMemo(
    () => createDurableChatTransport({ api: "/api/chat" }),
    []
  )

  const { messages, sendMessage, status } = useChat({
    id,
    messages: initialMessages,
    transport,
    resume: true, // reconnect to in-flight generation on page reload
  })
}

Server — POST /api/chat

import { streamText, convertToModelMessages } from "ai"
import { toDurableStreamResponse } from "@durable-streams/aisdk-transport"

export async function POST(request: Request) {
  const { messages, id } = await request.json()

  const result = streamText({
    model: openai("gpt-4o-mini"),
    messages: await convertToModelMessages(messages),
  })

  const streamPath = `chat/${id}/${crypto.randomUUID()}`
  await saveChat({ id, activeStreamId: streamPath })

  return toDurableStreamResponse({
    source: result.toUIMessageStream({
      originalMessages: messages,
      onFinish: ({ messages: finalMessages }) => {
        void saveChat({ id, messages: finalMessages, activeStreamId: null })
      },
    }),
    stream: {
      writeUrl: buildWriteStreamUrl(streamPath),
      readUrl: buildReadProxyUrl(request, streamPath), // never expose writeUrl
      headers: WRITE_HEADERS,
    },
  })
}

mode: "immediate" (default) returns 201 immediately; writes continue in background. Use mode: "await" when the runtime needs an active request to keep running.

Reconnect endpoint — GET /api/chat/:id/stream

Required for resume: true. Returns the active stream URL or 204 if no generation is in flight:

export async function GET(request, { params }) {
  const { id } = await params
  const chat = await loadChat(id)

  if (!chat?.activeStreamId) {
    return new Response(null, { status: 204 })
  }

  const streamUrl = buildReadProxyUrl(request, chat.activeStreamId)
  return Response.json(
    { streamUrl },
    { status: 200, headers: { Location: streamUrl } }
  )
}

The transport defaults to ${api}/${chatId}/stream. Pass reconnectApi to override.

Read proxy

Always proxy reads through an app route so write credentials stay server-side. Pass the proxy URL as readUrl in toDurableStreamResponse().

// app/api/chat-stream/route.ts (Next.js) or equivalent server route
function copyHeaders(response: Response): Headers {
  const headers = new Headers()
  for (const [key, value] of response.headers.entries()) {
    const k = key.toLowerCase()
    if (
      k === "connection" ||
      k === "transfer-encoding" ||
      k === "content-encoding" ||
      k === "content-length"
    )
      continue
    headers.set(key, value)
  }
  headers.set("Cache-Control", "no-store")
  return headers
}

export async function GET(request: Request) {
  const url = new URL(request.url)
  const streamPath = url.searchParams.get("path")
  if (!streamPath)
    return Response.json({ error: "Missing stream path" }, { status: 400 })

  const upstreamUrl = new URL(buildReadStreamUrl(streamPath))
  for (const [key, value] of url.searchParams) {
    if (key === "path") continue
    upstreamUrl.searchParams.append(key, value)
  }

  const response = await fetch(upstreamUrl, {
    headers: {
      Authorization: `Bearer ${process.env.DS_SECRET}`,
      ...(request.headers.get("accept")
        ? { Accept: request.headers.get("accept")! }
        : {}),
    },
  })

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: copyHeaders(response),
  })
}

Common Mistakes

CRITICAL Not persisting activeStreamId for resume

Save the active stream path before returning and clear it in onFinish. Without it, the reconnect endpoint has nothing to return and resume: true silently fails. See the server setup above for the correct pattern.

CRITICAL Exposing write URLs to the client

Wrong: omitting readUrl — defaults to writeUrl, leaking credentials in the Location header. Fix: always set readUrl to a read proxy route.

Source: packages/aisdk-transport/src/server.ts

HIGH Not using waitUntil on serverless runtimes

In immediate mode, the response returns before writes finish. Without waitUntil, serverless runtimes may kill the process and drop chunks.

Fix: pass waitUntil: ctx.waitUntil.bind(ctx) to toDurableStreamResponse().

Source: packages/aisdk-transport/src/server.ts

HIGH Not clearing activeStreamId on finish

A stale activeStreamId causes the reconnect endpoint to return a completed stream. Always clear it in onFinish. See the server setup above.

MEDIUM Missing reconnect endpoint

resume: true calls GET ${api}/${chatId}/stream on mount. If this endpoint doesn't exist, reconnection fails silently with a 404. See the reconnect endpoint setup above.

Source: packages/aisdk-transport/src/client.ts

See also

Version

Targets @durable-streams/aisdk-transport v0.2.1.