logoassistant-ui

Getting Started

Get assistant-ui running in 5 minutes with npm and your first chat component.

Quick Start

The fastest way to get started with assistant-ui.

animated gif showing the steps to create a new project

Initialize assistant-ui

Create a new project:

npx assistant-ui@latest create

Or choose a template:

# Assistant Cloud - with persistence and thread management
npx assistant-ui@latest create -t cloud

# LangGraph
npx assistant-ui@latest create -t langgraph

# MCP support
npx assistant-ui@latest create -t mcp

Add to an existing project:

npx assistant-ui@latest init

Add API key

Create a .env file with your API key:

OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Start the app

npm run dev

Add to Existing Project

If you prefer not to use the CLI, you can install components manually.

Add assistant-ui

npx shadcn@latest add @assistant-ui/thread @assistant-ui/thread-list

Setup Backend Endpoint

Install provider SDK:

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

Add an API endpoint:

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

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: openai("gpt-4o-mini"),
    messages: convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse();
}

Define environment variables:

/.env.local
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

If you aren't using Next.js, you can also deploy this endpoint to Cloudflare Workers, or any other serverless platform.

Use it in your app

/app/page.tsx
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { ThreadList } from "@/components/assistant-ui/thread-list";
import { Thread } from "@/components/assistant-ui/thread";

const MyApp = () => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({
      api: "/api/chat",
    }),
  });

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

What's Next?