# Using Assistant UI

[Assistant UI](https://assistant-ui.com) is the TypeScript/React library for AI Chat. Built on shadcn/ui and Tailwind CSS, it enables developers to create beautiful, enterprise-grade chat experiences in minutes.

> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/runtimes/mastra/full-stack-integration) on Assistant UI's documentation site.

> **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.

## Integration Guide

Run Mastra as a standalone server and connect your Next.js frontend (with Assistant UI) to its API endpoints.

1. Set up your directory structure. A possible directory structure could look like this:

   ```bash
   project-root
   ├── mastra-server
   │   ├── src
   │   │   └── mastra
   │   └── package.json
   └── my-app
       └── package.json
   ```

   Bootstrap your Mastra server:

   ```bash
   npx create-mastra@latest
   ```

   This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project.

   Navigate to your newly created Mastra server directory:

   ```bash
   cd mastra-server # Replace with the actual directory name you provided
   ```

   You now have a basic Mastra server project ready. You should have the following files and folders:

   ```bash
   src
   └── mastra
       ├── agents
       │   └── weather-agent.ts
       ├── scorers
       │   └── weather-scorer.ts
       ├── tools
       │   └── weather-tool.ts
       ├── workflows
       │   └── weather-workflow.ts
       └── index.ts
   ```

   > **Note:** Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.

2. Create a chat route for the Assistant UI frontend by using the `chatRoute()` helper from `@mastra/ai-sdk`. Add it to your Mastra project:

   **npm**:

   ```bash
   npm install @mastra/ai-sdk@latest
   ```

   **pnpm**:

   ```bash
   pnpm add @mastra/ai-sdk@latest
   ```

   **Yarn**:

   ```bash
   yarn add @mastra/ai-sdk@latest
   ```

   **Bun**:

   ```bash
   bun add @mastra/ai-sdk@latest
   ```

   In your `src/mastra/index.ts` file, register the chat route:

   ```typescript
   import { Mastra } from '@mastra/core/mastra';
   import { chatRoute } from '@mastra/ai-sdk';
   // Rest of the imports...

   export const mastra = new Mastra({
     // Rest of the configuration...
     server: {
       apiRoutes: [
         chatRoute({
           path: '/chat/:agentId'
         })
       ]
     }
   });
   ```

   This will make all agents available in AI SDK-compatible formats, including the `weatherAgent` at the endpoint `/chat/weatherAgent`.

3. Run the Mastra server using the following command:

   ```bash
   npm run dev
   ```

   By default, the Mastra server will run on `http://localhost:4111`. Keep this server running for the next steps where we'll set up the Assistant UI frontend to connect to it.

4. Go up one directory to your project root.

   ```bash
   cd ..
   ```

   Create a new `assistant-ui` project with the following command.

   ```bash
   npx assistant-ui@latest create
   ```

   > **Note:** For detailed setup instructions, including adding API keys, basic configuration, and manual setup steps, please refer to [assistant-ui's official documentation](https://assistant-ui.com/docs).

5. The default Assistant UI setup configures the chat runtime to use a local API route (`/api/chat`) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server's endpoint.

   Open the file in your assistant-ui frontend project that contains the `useChatRuntime` hook (usually `app/assistant.tsx` or `src/app/assistant.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:

   ```tsx
   "use client";

   // Rest of the imports...

   export const Assistant = () => {
     const runtime = useChatRuntime({
       transport: new AssistantChatTransport({
         api: "http://localhost:4111/chat/weatherAgent",
       }),
     });

     // Rest of the component...
   };
   ```

   Now, the Assistant UI frontend will send chat requests directly to your running Mastra server.

6. You're ready to connect the pieces! Make sure both the Mastra server and the Assistant UI frontend are running. Start the Next.js development server:

   ```bash
   npm run dev
   ```

   You should now be able to chat with your agent in the browser.

Congratulations! You have successfully integrated Mastra with Assistant UI using a separate server approach. Your Assistant UI frontend now communicates with a standalone Mastra agent server.