# AI SDK + assistant-ui
URL: /docs/cloud/ai-sdk-assistant-ui

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

Overview \[#overview]

This guide shows how to integrate Assistant Cloud with the [AI SDK](https://sdk.vercel.ai/) using assistant-ui's runtime system and pre-built UI components.

<Callout type="tip">
  Using the AI SDK with your own UI? See [AI SDK](/docs/cloud/ai-sdk) for a lighter integration with just one hook.
</Callout>

What You Get \[#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 \[#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:

1. Creates a cloud thread on the first user message
2. Persists messages as they complete streaming
3. Generates a conversation title after the assistant's first response
4. 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 \[#prerequisites]

<Callout type="info">
  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
</Callout>

Setup Guide \[#setup-guide]

<Steps>
  <Step>
    Create a Cloud Project \[#create-a-cloud-project]

    Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy:

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

  <Step>
    Configure Environment Variables \[#configure-environment-variables]

    Add the following environment variables to your project:

    ```bash title=".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
    ```
  </Step>

  <Step>
    Install Dependencies \[#install-dependencies]

    Install the required packages:

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk"]} />
  </Step>

  <Step>
    Set Up the Cloud Runtime \[#set-up-the-cloud-runtime]

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

    ```tsx title="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>
      );
    }
    ```
  </Step>
</Steps>

Authentication \[#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](/docs/cloud/authorization) guide to persist threads per user or workspace.

Next Steps \[#next-steps]

<Steps>
  <Step>
    Add User Authentication \[#add-user-authentication]

    For multi-user apps, integrate your auth provider (Clerk, Auth0, etc.) to scope threads per user. See the [Authorization guide](/docs/cloud/authorization) for setup details.
  </Step>

  <Step>
    Customize the UI \[#customize-the-ui]

    The `<Thread />` and `<ThreadList />` components are fully customizable via CSS and composition. See the [UI components docs](/docs/ui/thread) for styling options.
  </Step>

  <Step>
    Explore Runtime Features \[#explore-runtime-features]

    Learn about [runtime hooks](/docs/api-reference/integrations/vercel-ai-sdk) for advanced use cases like custom message handling or tool streaming.
  </Step>
</Steps>

When to Use This vs Standalone \[#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](/docs/cloud/ai-sdk) — `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 \[#complete-example]

Check out the [with-cloud example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud) on GitHub for a fully working implementation.