AI SDK v5

Overview

Integration with the Vercel AI SDK v5 using the new useChatRuntime hook from @assistant-ui/react-ai-sdk.
This provides a streamlined way to integrate AI SDK v5 features including the new streamText API and improved TypeScript support.

Getting Started

Create a Next.JS project

npx create-next-app@latest my-app
cd my-app

Install AI SDK v5 and `@assistant-ui/react`

npm install @assistant-ui/react @assistant-ui/react-ai-sdk ai @ai-sdk/openai

Setup a backend route under `/api/chat`

@/app/api/chat/route.ts

import { openai } from "@ai-sdk/openai";
import { streamText, UIMessage, convertToModelMessages, tool } from "ai";
import { frontendTools } from "@assistant-ui/react-ai-sdk";
import { z } from "zod";

// Allow streaming responses up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const {
    messages,
    system,
    tools,
  }: {
    messages: UIMessage[];
    system?: string; // System message forwarded from AssistantChatTransport
    tools?: any; // Frontend tools forwarded from AssistantChatTransport
  } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system, // Use the system message from the frontend if provided
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with frontendTools helper
      ...frontendTools(tools),
      // Backend tools
      get_current_weather: tool({
        description: "Get the current weather",
        inputSchema: z.object({
          city: z.string(),
        }),
        execute: async ({ city }) => {
          return `The weather in ${city} is sunny`;
        },
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}

Wrap your app with `AssistantRuntimeProvider` using `useChatRuntime`

@/app/page.tsx

"use client";

import { Thread } from "@/components/assistant-ui/thread";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

export default function Home() {
  const runtime = useChatRuntime();

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="h-full">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

API Reference

useChatRuntime

Creates a runtime directly with AI SDK v5's useChat hook integration.

import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  api: "/api/chat",
  // All standard useChat options are supported
});

By default, useChatRuntime uses AssistantChatTransport which automatically forwards system messages and frontend tools to your backend API. This enables your backend to receive the full context from the assistant-ui.

Custom Transport Configuration

If you need to customize the transport configuration:

import { DefaultChatTransport } from "ai";
import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

// Example 1: Custom API URL while keeping system/tools forwarding
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat", // Custom API URL with forwarding
  }),
});

// Example 2: Disable system/tools forwarding
const runtime = useChatRuntime({
  api: "/api/chat",
  transport: new DefaultChatTransport(), // Standard AI SDK transport without forwarding
});

When customizing the API URL, you must explicitly use AssistantChatTransport if you want to keep frontend system messages and tools forwarding. Simply passing api to useChatRuntime will use the default transport configuration.

Transport Options

AssistantChatTransport (default): Automatically forwards system messages and frontend tools from the assistant-ui context to your backend
DefaultChatTransport: Standard AI SDK transport without automatic forwarding

Using Frontend Tools with `frontendTools`

When using AssistantChatTransport, frontend tools are forwarded to your backend. Use the frontendTools helper to properly integrate them:

import { frontendTools } from "@assistant-ui/react-ai-sdk";

export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with the helper
      ...frontendTools(tools),
      // Your backend tools
      myBackendTool: tool({
        // ...
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}

The frontendTools helper converts frontend tool definitions to the AI SDK format and ensures they are properly handled by the streaming response.

useAISDKRuntime (Advanced)

For advanced use cases where you need direct access to the useChat hook:

import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";

const chat = useChat();
const runtime = useAISDKRuntime(chat);

Example

For a complete example, check out the AI SDK v5 example in our repository.

AI SDK v5

On this page