assistant-ui

name: assistant-ui description: Add, configure, and integrate assistant-ui components in React apps. Use when developers ask to add a chat thread, set up a runtime, integrate with AI SDK, configure tools, or build AI chat interfaces with assistant-ui.

assistant-ui

Use this skill to help users build AI chat interfaces with assistant-ui.

Step 1: Check Project Setup

Check if the project has components.json (shadcn config) and @assistant-ui/react installed.

If assistant-ui is not yet set up, run:

npx assistant-ui init --yes

This initializes shadcn and installs the default assistant-ui chat components.

Step 2: Add Components

Install components via the shadcn registry:

npx shadcn@latest add "https://r.assistant-ui.com/chat/b/ai-sdk-quick-start/json"

Available component presets:

You can also add individual assistant-ui shadcn components:

npx shadcn@latest add assistant-ui/thread
npx shadcn@latest add assistant-ui/markdown-text

Step 3: Runtime Setup

assistant-ui requires a runtime. The most common setup uses AI SDK:

AI SDK Runtime (recommended)

Install the integration package:

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

Create a chat API route (Next.js App Router):

// app/api/chat/route.ts
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

export const maxDuration = 30;

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

  const result = streamText({
    model: openai("gpt-5.4-nano"),
    messages,
    ...config,
  });

  return result.toDataStreamResponse();
}

Create the assistant component:

"use client";

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

export const Assistant = () => {
  const runtime = useChatRuntime({
    api: "/api/chat",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
};

Step 4: Tools (optional)

To add tool calling support, define tools on the backend and render them on the frontend:

Backend tool (AI SDK):

import { streamText, tool } from "ai";
import { z } from "zod";

const result = streamText({
  model: openai("gpt-5.4-nano"),
  messages,
  tools: {
    get_weather: tool({
      description: "Get weather for a location",
      parameters: z.object({
        location: z.string(),
      }),
      execute: async ({ location }) => {
        return { temperature: 72, condition: "sunny", location };
      },
    }),
  },
});

Frontend tool UI:

Create a toolkit with a renderer for the tool. The tool executes on the backend, so the entry uses externalTool() and only attaches UI:

// app/toolkit.tsx
"use generative";

import { defineToolkit, externalTool } from "@assistant-ui/react";

export default defineToolkit({
  get_weather: {
    execute: externalTool(),
    render: ({ args, result }) => {
      return (
        <div>
          <p>Weather for {args?.location}</p>
          {result && <p>{result.temperature}F, {result.condition}</p>}
        </div>
      );
    },
  },
});

Register the toolkit in your assistant component:

import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
import toolkit from "@/app/toolkit";

const aui = useAui({
  tools: Tools({ toolkit }),
});

<AssistantRuntimeProvider aui={aui} runtime={runtime}>
  <Thread />
</AssistantRuntimeProvider>

Do not use makeAssistantToolUI, useAssistantToolUI, makeAssistantTool, or useAssistantTool; they are deprecated in favor of toolkits.

Key Packages

Environment Variables

For OpenAI-based setups, ensure OPENAI_API_KEY is set in .env.local.