@built-in-ai/web-llm
useChat Integration
Integrate @built-in-ai/web-llm with the useChat hook in AI SDK v6
Overview
When using this library with the useChat hook, you'll need to create a custom transport implementation to handle client-side AI with download progress.
This is not required, but it makes it easier for you to build better user experiences.
Complete Transport Example
import {
ChatTransport,
UIMessageChunk,
streamText,
convertToModelMessages,
ChatRequestOptions,
createUIMessageStream,
tool,
stepCountIs,
} from "ai";
import {
WebLLMProgress,
WebLLMUIMessage,
WebLLMLanguageModel,
} from "@built-in-ai/web-llm";
import z from "zod";
export const createTools = () => ({
webSearch: tool({
description:
"Search the web for information when you need up-to-date information or facts not in your knowledge base. Use this when the user asks about current events, recent developments, or specific factual information you're unsure about.",
inputSchema: z.object({
query: z
.string()
.describe("The search query to find information on the web"),
}),
execute: async ({ query }) => {
// ...
},
}),
});
/**
* Client-side chat transport AI SDK implementation that handles AI model communication
* with in-browser AI capabilities.
*
* @implements {ChatTransport<WebLLMUIMessage>}
*/
export class WebLLMChatTransport implements ChatTransport<WebLLMUIMessage> {
private readonly model: WebLLMLanguageModel;
private tools: ReturnType<typeof createTools>;
constructor(model: WebLLMLanguageModel) {
this.model = model;
this.tools = createTools();
}
async sendMessages(
options: {
chatId: string;
messages: WebLLMUIMessage[];
abortSignal: AbortSignal | undefined;
} & {
trigger: "submit-message" | "submit-tool-result" | "regenerate-message";
messageId: string | undefined;
} & ChatRequestOptions,
): Promise<ReadableStream<UIMessageChunk>> {
const { messages, abortSignal } = options;
const prompt = convertToModelMessages(messages);
const model = this.model;
return createUIMessageStream<WebLLMUIMessage>({
execute: async ({ writer }) => {
let downloadProgressId: string | undefined;
const availability = await model.availability();
// Only track progress if model needs downloading
if (availability !== "available") {
await model.createSessionWithProgress((progress: WebLLMProgress) => {
const percent = Math.round(progress.progress * 100);
if (progress.progress >= 1) {
if (downloadProgressId) {
writer.write({
type: "data-modelDownloadProgress",
id: downloadProgressId,
data: {
status: "complete",
progress: 100,
message:
"Model finished downloading! Getting ready for inference...",
},
});
}
return;
}
if (!downloadProgressId) {
downloadProgressId = `download-${Date.now()}`;
}
writer.write({
type: "data-modelDownloadProgress",
id: downloadProgressId,
data: {
status: "downloading",
progress: percent,
message: `Downloading browser AI model... ${percent}%`,
},
transient: !downloadProgressId,
});
});
}
const result = streamText({
model,
tools: this.tools,
stopWhen: stepCountIs(5),
messages: prompt,
abortSignal,
onChunk: (event) => {
if (event.chunk.type === "text-delta" && downloadProgressId) {
writer.write({
type: "data-modelDownloadProgress",
id: downloadProgressId,
data: { status: "complete", progress: 100, message: "" },
});
downloadProgressId = undefined;
}
},
});
writer.merge(result.toUIMessageStream({ sendStart: false }));
},
});
}
async reconnectToStream(
options: {
chatId: string;
} & ChatRequestOptions,
): Promise<ReadableStream<UIMessageChunk> | null> {
// Client-side AI doesn't support stream reconnection
return null;
}
}Basic Transport Structure
Here's a simplified example of how to structure a custom transport:
import {
ChatTransport,
UIMessageChunk,
streamText,
convertToModelMessages,
ChatRequestOptions,
} from "ai";
import {
WebLLMLanguageModel,
WebLLMUIMessage,
} from "@built-in-ai/web-llm";
// This class won't stream back data parts with the download progress if
// the model hasn't yet been downloaded
export class SimpleWebLLMChatTransport
implements ChatTransport<WebLLMUIMessage>
{
private readonly model: WebLLMLanguageModel;
constructor(model: WebLLMLanguageModel) {
this.model = model;
}
async sendMessages(
options: {
chatId: string;
messages: WebLLMUIMessage[];
abortSignal: AbortSignal | undefined;
} & {
trigger: "submit-message" | "submit-tool-result" | "regenerate-message";
messageId: string | undefined;
} & ChatRequestOptions,
): Promise<ReadableStream<UIMessageChunk>> {
const prompt = convertToModelMessages(options.messages);
const result = streamText({
model: this.model,
messages: prompt,
abortSignal: options.abortSignal,
});
return result.toUIMessageStream();
}
async reconnectToStream(
options: {
chatId: string;
} & ChatRequestOptions,
): Promise<ReadableStream<UIMessageChunk> | null> {
// Client-side AI doesn't support stream reconnection
return null;
}
}You can then use the useChat() hook in your components:
import { webLLM, WebLLMUIMessage } from "@built-in-ai/web-llm";
const model = webLLM("Qwen3-0.6B-q0f16-MLC", {
worker: new Worker(new URL("./worker.ts", import.meta.url), {
type: "module",
}),
});
const {
sendMessage,
messages,
stop,
} = useChat<WebLLMUIMessage>({
transport: new WebLLMChatTransport(model),
});In case the device is incompatible with local in-browser LLMs, and we want to use a server-side AI model, we can simply use the utility function from the package first:
import {
webLLM,
WebLLMUIMessage,
doesBrowserSupportWebLLM,
} from "@built-in-ai/web-llm";
const model = webLLM("Qwen3-0.6B-q0f16-MLC", {
worker: new Worker(new URL("./worker.ts", import.meta.url), {
type: "module",
}),
});
const {
sendMessage,
messages,
stop,
} = useChat<WebLLMUIMessage>({
transport: doesBrowserSupportWebLLM() // check for device compatibility
? new WebLLMChatTransport(model)
: new DefaultChatTransport<UIMessage>({
api: "/api/chat",
}),
});