How do I integrate Assistant-UI with Vercel AI SDK using @assistant-ui/cloud-ai-sdk and useCloudChat?

Integrating Assistant-UI with the Vercel AI SDK using @assistant-ui/cloud-ai-sdk and useCloudChat lets you ship a full ChatGPT-style experience with persistent state in just a few steps. This stack gives you a production-ready chat UI, robust state management, and cloud-backed sessions without rebuilding any of the core UX yourself.

Below is a step‑by‑step guide you can adapt to your own app.

---

What you’ll build

By the end, you’ll have:

• A React chat interface powered by Assistant-UI
• A backend using Vercel AI SDK (Edge or Node, depending on your setup)
• Cloud-backed chat state using @assistant-ui/cloud-ai-sdk and the useCloudChat hook
• Streaming responses, multi-turn conversations, and persistent threads stored in Assistant-UI Cloud

---

Prerequisites

Before you start, make sure you have:

• A React app (Next.js, Vite, or similar)
• Node.js and npm (or pnpm / yarn)
• Access to an LLM provider supported by Vercel AI SDK (e.g., OpenAI, Anthropic, etc.)
• An Assistant-UI Cloud project/API key (for @assistant-ui/cloud-ai-sdk and useCloudChat)

---

1. Install the required packages

From your project root, install the core libraries:

npm install assistant-ui @assistant-ui/cloud-ai-sdk ai
# or
yarn add assistant-ui @assistant-ui/cloud-ai-sdk ai
# or
pnpm add assistant-ui @assistant-ui/cloud-ai-sdk ai

Where:

• assistant-ui is the open‑source React toolkit that gives you ChatGPT-style components and state management.
• @assistant-ui/cloud-ai-sdk connects Assistant-UI to your cloud backend and Vercel AI SDK.
• ai is the Vercel AI SDK package.

---

2. Set up your Vercel AI SDK route

You need an API route that:

1. Accepts chat messages from the frontend.
2. Uses Vercel AI SDK to call your LLM provider.
3. Streams responses back.

In a Next.js app (App Router example):

// app/api/chat/route.ts
import { NextRequest } from 'next/server'
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
})

export const runtime = 'edge'

export async function POST(req: NextRequest) {
  const { messages } = await req.json()

  const response = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    stream: true,
    messages,
  })

  const stream = OpenAIStream(response)

  return new StreamingTextResponse(stream)
}

You can adapt this route to any provider supported by the Vercel AI SDK (Gemini, Claude, Groq, etc.).

---

3. Configure Assistant-UI Cloud

Assistant-UI Cloud powers features like:

• Thread storage
• Session persistence across refreshes
• Coordinated state management for multi-turn conversations

Create a configuration file for your cloud client, for example:

// lib/assistantUiCloud.ts
import { createCloudClient } from '@assistant-ui/cloud-ai-sdk'

export const cloudClient = createCloudClient({
  apiKey: process.env.NEXT_PUBLIC_ASSISTANT_UI_API_KEY!,
  // Optional: configure projectId, baseUrl, etc., if needed
})

Make sure your API key is loaded from environment variables and available to the client (using NEXT_PUBLIC_ prefix for Next.js frontends, or your framework’s equivalent).

---

4. Wire useCloudChat to your Vercel route

The useCloudChat hook comes from Assistant-UI’s cloud integration and is responsible for:

• Managing messages and streaming state
• Talking to your Vercel AI SDK endpoint
• Persisting threads in Assistant-UI Cloud

Create a composable hook that points to your /api/chat route:

// hooks/useChatWithCloud.ts
'use client'

import { useCloudChat } from '@assistant-ui/cloud-ai-sdk'
import { cloudClient } from '@/lib/assistantUiCloud'

export function useChatWithCloud() {
  const chat = useCloudChat({
    client: cloudClient,
    api: {
      // Endpoint that uses Vercel AI SDK
      chatUrl: '/api/chat',
    },
    // Optional settings:
    // initialMessages: [],
    // threadId: 'some-fixed-id' // use this for specific conversations
  })

  return chat
}

Under the hood, useCloudChat manages streaming, retries, interruptions, and multi-turn context, while persisting the session in Assistant-UI Cloud.

---

5. Render the Assistant-UI chat components

Assistant-UI ships with production-ready React components that give you a ChatGPT-style UX with minimal code.

A simple chat page might look like this:

// app/chat/page.tsx (Next.js example)
'use client'

import { Chat } from 'assistant-ui'
import { useChatWithCloud } from '@/hooks/useChatWithCloud'

export default function ChatPage() {
  const chat = useChatWithCloud()

  return (
    <div className="h-screen flex items-center justify-center bg-neutral-950">
      <div className="w-full max-w-3xl h-[80vh] border border-neutral-800 rounded-xl overflow-hidden bg-neutral-900">
        <Chat
          chat={chat}
          // You can customize theme or layout via props, if desired
        />
      </div>
    </div>
  )
}

What this does:

• Uses useChatWithCloud() to get a fully managed chat state connected to your Vercel AI SDK route and Assistant-UI Cloud.
• Renders a ChatGPT-style interface via <Chat /> from assistant-ui.
• Automatically handles streaming tokens, pending states, and retries.

---

6. Theming and customization

Assistant-UI is designed to be dropped in with sensible defaults, but you can customize:

• Colors, fonts, spacing
• Message bubbles and avatars
• Layout (sidebar, “ChatGPT-like” centered column, etc.)

Common approaches:

• Wrap your app with your design system (Tailwind, shadcn/ui, etc.).
• Use props or component overrides offered by assistant-ui to adjust visuals.
• Extend message rendering to add tool calls, citations, or custom content blocks.

Because Assistant-UI is React-based, it works with:

• Vercel AI SDK
• LangChain / LangGraph
• Other LLM providers or custom backends

The same UI layer can sit on top of different backends without major changes.

---

7. Persisting and resuming conversations

Assistant-UI Cloud lets you keep conversation context across refreshes and sessions. With useCloudChat, you can:

• Persist threads by default (Cloud will assign IDs)
• Pass a threadId to resume a specific conversation
• Use user identifiers to tie conversations to accounts

Example: resuming a thread via URL param:

// hooks/useChatWithCloud.ts
import { useSearchParams } from 'next/navigation'
import { useCloudChat } from '@assistant-ui/cloud-ai-sdk'
import { cloudClient } from '@/lib/assistantUiCloud'

export function useChatWithCloud() {
  const searchParams = useSearchParams()
  const threadId = searchParams.get('thread')

  const chat = useCloudChat({
    client: cloudClient,
    api: { chatUrl: '/api/chat' },
    threadId: threadId ?? undefined,
  })

  return chat
}

Now, /chat?thread=abc123 would load an existing conversation, with state managed by Assistant-UI Cloud and responses streamed via Vercel AI SDK.

---

8. Handling tools and advanced agent behavior

As you evolve your agent logic, you can:

• Use Vercel AI SDK’s tools / function-calling features.
• Or move more logic into LangChain or LangGraph while still using Assistant-UI for chat UX.
• Leverage @assistant-ui/cloud-ai-sdk to route tool calls, track metrics, or store richer state.

Key point: you don’t need to rewrite the UI when you change your agent implementation. Assistant-UI stays the same; only your /api/chat logic and cloud configuration evolve.

---

9. Production tips

To make this integration production-ready:

• Secure keys: keep OpenAI / Anthropic keys server-side; only expose what’s necessary to the browser.
• Error handling: wrap your Vercel AI SDK route with try/catch and return structured error messages.
• Rate limiting: add middleware or edge protection if you expect heavy usage.
• Analytics and observability: integrate with LangSmith or other tools alongside Assistant-UI Cloud to inspect traces and improve agent behavior.

---

Summary

To integrate Assistant-UI with Vercel AI SDK using @assistant-ui/cloud-ai-sdk and useCloudChat:

1. Install assistant-ui, @assistant-ui/cloud-ai-sdk, and ai.
2. Create an API route that uses Vercel AI SDK (ai) to talk to your LLM.
3. Configure a cloud client with your Assistant-UI Cloud credentials.
4. Use useCloudChat to connect the cloud client to your Vercel AI route.
5. Render the <Chat /> component from assistant-ui in your React UI.
6. Customize styling and conversation behavior as needed.

This pattern gives you a high-performance, production-ready chat experience with minimal custom code, so you can focus on agent logic rather than rebuilding the chat UX from scratch.