AI SDK

Overview

The @assistant-ui/cloud-ai-sdk package provides a single hook that adds full message and thread persistence to any AI SDK application:

• useCloudChat — wraps useChat with automatic cloud persistence and built-in thread management

This hook works with any React UI. You keep full control of your components.

Prerequisites

Setup

NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com

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

"use client";

import { useState } from "react";
import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

export default function Chat() {
  // Zero-config: auto-initializes anonymous cloud from env var with built-in threads.
  // For custom config, pass: { cloud, threads: useThreads(...), onSyncError }
  const { messages, sendMessage, threads } = useCloudChat();

  const [input, setInput] = useState("");
  const handleSubmit = () => {
    if (!input.trim()) return;
    sendMessage({ text: input });
    setInput("");
  };

  return (
    <div>
      {/* Thread list */}
      <ul>
        {threads.threads.map((t) => (
          <li key={t.id} onClick={() => threads.selectThread(t.id)}>
            {t.title || "New conversation"}
          </li>
        ))}
        <li onClick={() => threads.selectThread(null)}>New chat</li>
      </ul>

      {/* Chat messages */}
      <div>
        {messages.map((m) => (
          <div key={m.id}>
            {m.parts.map((p) => p.type === "text" && p.text)}
          </div>
        ))}
      </div>

      {/* Composer */}
      <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
        <input value={input} onChange={(e) => setInput(e.target.value)} />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

That's it. Messages persist automatically as they complete, and switching threads loads the full history.

API Reference

useCloudChat(options?)

Wraps AI SDK's useChat with automatic cloud persistence and built-in thread management. Messages are persisted as they finish streaming. Thread creation is automatic on the first message — the hook will auto-create the thread, select it, refresh the thread list, and generate a title after the first response.

Configuration Modes

1. Zero-config — Set NEXT_PUBLIC_ASSISTANT_BASE_URL env var, call with no args:

const chat = useCloudChat();

2. Custom cloud instance — For authenticated users or custom configuration:

const cloud = new AssistantCloud({ baseUrl, authToken });
const chat = useCloudChat({ cloud });

3. External thread management — When threads need to be accessed from a separate component or you need custom thread options like includeArchived:

// In a context provider or parent component
const myThreads = useThreads({ cloud, includeArchived: true });

// Pass to useCloudChat - it will use your thread state
const chat = useCloudChat({ threads: myThreads });

Parameters

All other AI SDK useChat options are also accepted.

Returns: UseCloudChatResult

Plus all other properties from AI SDK's UseChatHelpers.

Thread management (threads):

useThreads(options)

Thread list management for use with useCloudChat. Call this explicitly and pass to useCloudChat({ threads }) when you need access to thread operations outside the chat context (e.g., in a separate sidebar component).

const myThreads = useThreads({ cloud: myCloud });
const { messages, sendMessage } = useCloudChat({ threads: myThreads });

Parameters:

Returns: UseThreadsResult — same shape as threads from useCloudChat().

Telemetry

The useCloudChat hook automatically reports run telemetry to Assistant Cloud after each assistant response. This includes:

Automatically captured:

• status — "completed" or "incomplete" based on response content
• tool_calls — Tool invocations with name, arguments, results, and source (MCP, frontend, or backend)
• total_steps — Number of reasoning/tool steps in the response
• output_text — Full response text (truncated at 50K characters)

Requires route configuration:

• model_id — The model used for the response
• input_tokens / output_tokens — Token usage statistics

To capture model and usage data, configure the messageMetadata callback in your AI SDK route:

import { streamText } from "ai";

export async function POST(req: Request) {
  const result = streamText({
    model: openai("gpt-5-mini"),
    messages,
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") {
        return {
          usage: part.totalUsage,
        };
      }
      if (part.type === "finish-step") {
        return {
          modelId: part.response.modelId,
        };
      }
      return undefined;
    },
  });
}

Customizing Reports

Use the beforeReport hook to enrich or filter telemetry:

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  telemetry: {
    beforeReport: (report) => ({
      ...report,
      metadata: { environment: "production", version: "1.0.0" },
    }),
  },
});

Return null from beforeReport to skip reporting a specific run. To disable telemetry entirely, pass telemetry: false.

Authentication

The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:

import { useAuth } from "@clerk/nextjs";
import { AssistantCloud } from "assistant-cloud";
import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

function Chat() {
  const { getToken } = useAuth();

  const cloud = useMemo(() => new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
    authToken: async () => getToken({ template: "assistant-ui" }),
  }), [getToken]);

  const { messages, sendMessage, threads } = useCloudChat({ cloud });
  // ...
}

See the Cloud Authorization guide for other auth providers.

Next Steps

• If you want pre-built UI components, see AI SDK + assistant-ui for the full integration
• Learn about user authentication for multi-user applications
• Check out the complete example on GitHub