[Feature] WebSockets implementation of ChatTransport

[mindplay-dk]

Description

I am looking for this, basically:

#9559

It is probably outdated by now - sadly, it was just left there and no one ever even commented.

I'm building an agent that needs to do potentially many client-side tool calls, and the default SSE transport is going to suck for this - it's going to "stop the world" on every tool call, and add unreasonable HTTP overhead (and much slower requests) for a single end user chat request.

I looked everywhere and can't find a package that does this, which is frustrating - I could take that draft and try to update it and complete it (not sure how finished it is) but it's more than I'm willing to own. I could let my agent hammer something out, and it would probably work, but I'm not an expert at either AI SDK or WebSockets, so I wouldn't trust it in a work setting.

Vercel's own docs for ChatTransport actually state:

This is particularly useful for alternative communication protocols like WebSockets

It really would be. 😊

Any chance you could take a look at the work that's already been done here? 🙏

Reproduction

No response

AI SDK Version

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[ai-sdk-factory]

Identify issue type

Identified as Feature
Confidence: High

Rationale

This is a request for a new WebSocket-based transport capability and associated ergonomics, rather than a concrete failure of current AI SDK behavior.

Evidence

• The title explicitly requests a WebSockets implementation of ChatTransport.
• The description seeks an alternative to the existing SSE transport for workflows with many client-side tool calls.
• The reporter references prior draft work and asks maintainers to provide or complete this new transport capability; no existing promised behavior is reported as broken.

[ai-sdk-factory]

Feature Analysis

Feature is not available.

Feature Description

• Provide an official WebSocketChatTransport for useChat that reuses a persistent browser-to-server connection, sends chat turns, and returns correlated UIMessageChunk streams with cancellation and reconnection behavior.
• Current main exports DefaultChatTransport, HttpChatTransport, TextStreamChatTransport, and DirectChatTransport but no WebSocketChatTransport; a built-package probe against ai 7.0.93 found no WebSocket chat export.
• The Transport documentation only directs users to implement custom transports; the implementation, tests, and example from draft PR feat(ai): add websocket transport support #9559 remain solely on origin/aayush/wss-chat-transport and are absent from main.
• Experimental Realtime uses WebSockets but is a separate provider-realtime model and hook API, not a ChatTransport implementation usable with useChat.

AI SDK Fit

• The feature directly fits ChatTransport's documented purpose of supporting alternative communication protocols such as WebSockets.
• It belongs in the AI SDK UI transport layer because it would carry provider-independent UIMessageChunk data and work with any backend using streamText or an Agent.
• It follows the existing pattern of concrete ChatTransport implementations and can serve all UI frameworks through the shared Chat abstraction.
• The client transport, matching wire protocol, lifecycle behavior, and server integration form one user-facing capability and should not be split into independently released features.

Implications / Considerations

• The work is cross-cutting within AI SDK UI transport and runtime support, principally affecting packages/ai and potentially reusable WebSocket helpers in @ai-sdk/provider-utils, but it should not require provider integrations or changes to @ai-sdk/provider model specifications.
• The ai package would need to export WebSocketChatTransport and narrowly defined initialization and request-preparation options; ordinary sequential turns can implement the existing ChatTransport interface without a breaking change.
• A persistent transport needs an explicit close or dispose lifecycle so hooks can release sockets when a transport is replaced or a component is unmounted; an optional lifecycle member could remain backward compatible, while a required ChatTransport change would need a major release.
• AI SDK must define and document an application-level WebSocket protocol for send, regenerate, resume, abort, chunk, end, error, and no-active messages, including request identifiers, ordering, schema validation, and multiplexing because the WebSocket standard does not define these semantics.
• A matching framework-neutral server adapter or authoritative server example is needed to validate UI messages, invoke streamText or an Agent, forward UIMessageChunk objects, propagate cancellation, and retain any state required for reconnection; a client-only class would not be operationally complete.
• Reusing one socket removes repeated HTTP connection overhead, but current Chat waits for a response stream to finish before sendAutomaticallyWhen invokes sendMessages again; if the requested no-stop behavior means returning tool output to an active server generation, Chat and ChatTransport need a new bidirectional event contract plus corresponding server or agent support.
• Existing UIMessage and UIMessageChunk formats and framework hook signatures need no change for sequential WebSocket turns, but React, Vue, Svelte, and Angular integrations must avoid leaked sockets, stale callbacks, and transport replacement races.
• Reconnect behavior must specify retry and backoff, replay and idempotency, request correlation, stream cursors or deduplication, and durable server state; Vercel Function WebSockets remain bounded by function duration, so recovery cannot depend only on process memory.
• The implementation must preserve frame ordering, decode text, binary, and Blob messages safely, support concurrent chats or requests, queue sends, and apply bufferedAmount backpressure; existing provider-utils WebSocket connection, decoding, abort, and drain utilities provide comparable building blocks.
• Security requirements include using wss in production, authenticating the handshake through cookies, short-lived query tokens, or subprotocols because browser WebSocket cannot set arbitrary headers, validating Origin and every envelope, authorizing chat IDs and tool actions, rate-limiting, limiting payload sizes, and avoiding long-lived credentials in URLs or message metadata.
• Tests should cover connection reuse, concurrent request correlation, all UIMessageChunk variants, malformed frames, cancellation, close and error races, reconnection, replay, backpressure, disposal, authentication configuration, and Node, browser, and Edge-compatible behavior, supplemented by an end-to-end WebSocket server example.
• Documentation should add a WebSocketChatTransport API reference, update the Transport and Stream Protocols guides, provide secure client and server setup, demonstrate repeated client-side tool calls, explain the distinction from experimental Realtime, and document deployment and reconnection constraints.

Relevant Documentation

• Transport
• Chatbot Tool Usage
• Stream Protocols
• useChat
• Realtime
• WebSockets Standard
• Do Vercel Serverless Functions support WebSocket connections?