> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 使用 Assistant UI

[Assistant UI](https://assistant-ui.com) 是一个用于 AI 聊天的 TypeScript/React 库。它基于 shadcn/ui 和 Tailwind CSS 构建，让开发者能在几分钟内打造美观的企业级聊天体验。

> **信息:** 如需让 Mastra 直接运行在 Next.js API 路由中的全栈集成方式，请参阅 Assistant UI 文档站点上的[全栈集成指南](https://www.assistant-ui.com/docs/integrations/frameworks/mastra/full-stack)。

访问 Mastra 的 [**“UI Dojo”**](https://ui-dojo.mastra.ai/)，查看 Assistant UI 与 Mastra 集成的实际示例。

## 集成指南

将 Mastra 作为独立 Server 运行，并把使用 Assistant UI 的 Next.js 前端连接到其 API 端点。

1. 设置目录结构。可以采用如下目录结构：

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

   初始化 Mastra Server：

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

   该命令会启动交互式向导，帮助你搭建新的 Mastra 项目，包括提示输入项目名称并完成基础配置。按照提示创建 Server 项目。

   进入新创建的 Mastra Server 目录：

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

   现在，基础 Mastra Server 项目已准备就绪，其中应包含以下文件和文件夹：

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

   > **备注:** 请确保已在 `.env` 文件中为 LLM Provider 设置适当的环境变量。

2. 使用 `@mastra/ai-sdk` 中的 `chatRoute()` 辅助函数，为 Assistant UI 前端创建聊天路由。将其添加到 Mastra 项目：

   **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
   ```

   在 `src/mastra/index.ts` 文件中注册聊天路由：

   ```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',
         }),
       ],
     },
   })
   ```

   这样，所有 Agent 都会以 AI SDK 兼容格式提供，包括位于 `/chat/weatherAgent` 端点的 `weatherAgent`。

3. 使用以下命令运行 Mastra Server：

   ```bash
   npm run dev
   ```

   默认情况下，Mastra Server 在 `http://localhost:4111` 上运行。请保持 Server 运行，后续步骤将设置 Assistant UI 前端并连接到该 Server。

4. 向上一级返回项目根目录。

   ```bash
   cd ..
   ```

   使用以下命令创建新的 `assistant-ui` 项目。

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

   > **备注:** 有关添加 API Key、基础配置和手动设置步骤等详细说明，请参阅 [assistant-ui 官方文档](https://assistant-ui.com/docs)。

5. Assistant UI 的默认设置会将聊天 Runtime 配置为使用 Next.js 项目内的本地 API 路由（`/api/chat`）。由于 Mastra Agent 运行在独立 Server 上，需要更新前端，使其指向该 Server 的端点。

   在 assistant-ui 前端项目中打开包含 `useChatRuntime` hook 的文件（通常为 `app/assistant.tsx` 或 `src/app/assistant.tsx`）。找到 `useChatRuntime` hook，将 `api` 属性改为 Mastra Agent 流式端点的完整 URL：

   ```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...
   }
   ```

   现在，Assistant UI 前端会将聊天请求直接发送到正在运行的 Mastra Server。

6. 现在可以将各部分连接起来了。请确保 Mastra Server 和 Assistant UI 前端均在运行，然后启动 Next.js 开发 Server：

   ```bash
   npm run dev
   ```

   现在，你应该可以在浏览器中与 Agent 聊天。

恭喜！你已使用独立 Server 方式成功集成 Mastra 与 Assistant UI。Assistant UI 前端现在可以与独立的 Mastra Agent Server 通信。