跳到主要内容

在 React + Vite 项目中集成 Mastra

本指南将介绍如何使用 Mastra 构建一个可调用 Tool 的 AI Agent，然后直接从 Mastra 的独立服务器调用该 Agent，将其连接到 React。

你将使用 AI SDK UI 和 AI Elements 创建美观的交互式聊天体验。

开始之前
开始之前的直接链接

  • 你需要受支持的模型 Provider所提供的 API 密钥。如果没有偏好，请使用 OpenAI。
  • 安装 Node.js v22.13.0 或更高版本

创建新的 React + Vite 应用（可选）
创建新的 React + Vite 应用（可选）的直接链接

如果已有使用 Tailwind 的 React + Vite 应用，请跳到下一步。

搭建项目
搭建项目的直接链接

运行以下命令以创建新的 React + Vite 应用：

npm create vite@latest mastra-react -- --template react-ts

这会创建名为 mastra-react 的项目，你也可以将其替换为任意名称。

进入项目目录：

cd mastra-react

Tailwind
Tailwind的直接链接

接下来安装 Tailwind：

npm install tailwindcss @tailwindcss/vite

配置 Vite 插件：

vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

将 src/index.css 的全部内容替换为以下代码：

src/index.css
@import 'tailwindcss';

将以下 compilerOptions 添加到 tsconfig.json：

tsconfig.json
{
  // ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
  },
}

编辑 tsconfig.app.json 以解析路径：

tsconfig.app.json
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
    // ...
  },
}

初始化 Mastra
初始化 Mastra的直接链接

运行 mastra init。出现提示时，选择 Provider（例如 OpenAI）并输入密钥：

npx mastra@latest init

这会创建一个 src/mastra 文件夹，其中包含示例天气 Agent 和以下文件：

  • index.ts - Mastra 配置，包括 memory
  • tools/weather-tool.ts - 获取指定位置天气的 Tool
  • agents/weather-agent.ts- 使用该 Tool 的天气 Agent 及其提示词

接下来，你会从聊天 UI 调用 weather-agent.ts。

安装 AI SDK UI 和 AI Elements
安装 AI SDK UI 和 AI Elements的直接链接

安装 AI SDK UI 和 Mastra adapter：

npm install @mastra/ai-sdk@latest @ai-sdk/react ai

接下来初始化 AI Elements。出现提示时请选择默认选项：

npx ai-elements@latest

这会将完整的 AI Elements UI 组件库下载到 @/components/ai-elements 文件夹。

创建聊天路由
创建聊天路由的直接链接

打开 src/mastra/index.ts，在配置中添加 ⁠chatRoute()。这会创建一个 React 前端可调用的 API 路由，用于返回兼容 AI SDK 的聊天响应；下一步会将它与 ⁠useChat() 配合使用。

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
// Existing imports...
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  // Existing config...
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat/:agentId',
      }),
    ],
  },
})

添加聊天 UI
添加聊天 UI的直接链接

替换 src/App.tsx 文件以创建聊天界面：

src/App.tsx
import * as React from 'react'
import { DefaultChatTransport, type ToolUIPart } from 'ai'
import { useChat } from '@ai-sdk/react'

import {
  PromptInput,
  PromptInputBody,
  PromptInputTextarea,
} from '@/components/ai-elements/prompt-input'

import {
  Conversation,
  ConversationContent,
  ConversationScrollButton,
} from '@/components/ai-elements/conversation'

import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message'

import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from '@/components/ai-elements/tool'

export default function App() {
  const [input, setInput] = React.useState<string>('')

  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: 'http://localhost:4111/chat/weather-agent',
    }),
  })

  const handleSubmit = async () => {
    if (!input.trim()) return

    sendMessage({ text: input })
    setInput('')
  }

  return (
    <div className="relative mx-auto size-full h-screen max-w-4xl p-6">
      <div className="flex h-full flex-col">
        <Conversation className="h-full">
          <ConversationContent>
            {messages.map(message => (
              <div key={message.id}>
                {message.parts?.map((part, i) => {
                  if (part.type === 'text') {
                    return (
                      <Message key={`${message.id}-${i}`} from={message.role}>
                        <MessageContent>
                          <MessageResponse>{part.text}</MessageResponse>
                        </MessageContent>
                      </Message>
                    )
                  }

                  if (part.type?.startsWith('tool-')) {
                    return (
                      <Tool key={`${message.id}-${i}`}>
                        <ToolHeader
                          type={(part as ToolUIPart).type}
                          state={(part as ToolUIPart).state || 'output-available'}
                          className="cursor-pointer"
                        />
                        <ToolContent>
                          <ToolInput input={(part as ToolUIPart).input || {}} />
                          <ToolOutput
                            output={(part as ToolUIPart).output}
                            errorText={(part as ToolUIPart).errorText}
                          />
                        </ToolContent>
                      </Tool>
                    )
                  }

                  return null
                })}
              </div>
            ))}
            <ConversationScrollButton />
          </ConversationContent>
        </Conversation>
        <PromptInput onSubmit={handleSubmit} className="mt-20">
          <PromptInputBody>
            <PromptInputTextarea
              onChange={e => setInput(e.target.value)}
              className="md:leading-10"
              value={input}
              placeholder="Ask about the weather..."
              disabled={status !== 'ready'}
            />
          </PromptInputBody>
        </PromptInput>
      </div>
    </div>
  )
}

此组件将 useChat() 连接到 chat/weather-agent 端点，把提示词发送到该端点，并分块流式返回响应。

它使用 <MessageResponse> 组件渲染响应文本，并使用 <Tool> 组件显示所有 Tool 调用。

测试 Agent
测试 Agent的直接链接

要通过聊天界面测试 Agent，请同时运行 Mastra 服务器和 Vite 开发服务器。

  1. 启动 Mastra 开发服务器：

    npx mastra dev

  2. 在另一个终端窗口中启动 Vite 开发服务器：

    npm run dev

  3. 打开应用：http://localhost:5173

  4. 尝试询问天气。如果 API 密钥配置正确，你会收到响应

后续步骤
后续步骤的直接链接

恭喜你使用 React 构建了 Mastra Agent！🎉

接下来，你可以使用自己的 Tool 和逻辑扩展项目：

  • 进一步了解 Agent
  • 为 Agent 添加自己的 Tool
  • 为 Agent 添加类似人类的 memory

准备就绪后，可进一步了解 Mastra 与 AI SDK UI 和 React 的集成方式，以及如何将 Agent 部署到任意位置：

On this page