跳至主要內容

在你的 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 plugin：

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';

在 tsconfig.json 中加入下列 compilerOptions：

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 設定，包含記憶功能
  • 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()。這會建立一個 API 路由，讓 React 前端可以呼叫並取得與 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 加入類似人類的記憶

準備好後，進一步了解 Mastra 如何與 AI SDK UI 和 React 整合，以及如何將 Agent 部署至任何地方：

On this page