AI SDK + assistant-ui

Integrate cloud persistence using assistant-ui runtime and pre-built components.

Overview

This guide shows how to integrate Assistant Cloud with the AI SDK using assistant-ui's runtime system and pre-built UI components.

Using the AI SDK with your own UI? See AI SDK for a lighter integration with just one hook.

What You Get

This integration provides:

<Thread /> — A complete chat interface with messages, composer, and status indicators
<ThreadList /> — A sidebar showing all conversations with auto-generated titles, plus new/delete/manage actions
Automatic Persistence — Messages save as they stream. Threads are created automatically on first message.
Runtime Integration — The assistant-ui runtime handles all cloud synchronization behind the scenes.

How It Works

The useChatRuntime hook from @assistant-ui/react-ai-sdk wraps AI SDK's useChat and adds cloud persistence via the cloud parameter. The runtime automatically:

Creates a cloud thread on the first user message
Persists messages as they complete streaming
Generates a conversation title after the assistant's first response
Loads historical messages when switching threads via <ThreadList />

You provide the AI SDK endpoint (api: "/api/chat") and the cloud configuration—everything else is handled.

Prerequisites

You need an assistant-cloud account to follow this guide. Sign up here to get started.

Setup Guide

Create a Cloud Project

Create a new project in the assistant-cloud dashboard and from the settings page, copy:

Frontend API URL: https://proj-[ID].assistant-api.com
Assistant Cloud API Key: sk_aui_proj_*

Configure Environment Variables

Add the following environment variables to your project:

.env.local

# Frontend API URL from your cloud project settings
NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com

# API key for server-side operations
ASSISTANT_API_KEY=your-api-key-here

Install Dependencies

Install the required packages:

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

Set Up the Cloud Runtime

Create a client-side AssistantCloud instance and integrate it with your AI SDK runtime:

app/chat/page.tsx

"use client";

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

export default function ChatPage() {
  const cloud = new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
    anonymous: true, // Creates browser-session based user ID
  });

  const runtime = useChatRuntime({
    api: "/api/chat", // Your AI SDK endpoint
    cloud,
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
        <ThreadList />
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

Authentication

The example above uses anonymous: true which creates a browser session-based user ID. This is suitable for public demos or prototypes.

For production apps with user accounts, see the Cloud Authorization guide to persist threads per user or workspace.

Next Steps

Add User Authentication

For multi-user apps, integrate your auth provider (Clerk, Auth0, etc.) to scope threads per user. See the Authorization guide for setup details.

Customize the UI

The <Thread /> and <ThreadList /> components are fully customizable via CSS and composition. See the UI components docs for styling options.

Explore Runtime Features

Learn about runtime hooks for advanced use cases like custom message handling or tool streaming.

When to Use This vs Standalone

Approach	Best For	Components
This guide — `useChatRuntime` + assistant-ui	You want pre-built, polished UI components	`<Thread />`, `<ThreadList />`
AI SDK standalone — `useCloudChat`	You have custom UI, want minimal dependencies	Your own components

Both approaches use the same cloud backend and offer the same persistence features—choose based on your UI needs.

Complete Example

Check out the with-cloud example on GitHub for a fully working implementation.