본문으로 건너뛰기

React + Vite 프로젝트에 Mastra 통합

이 가이드에서는 Mastra를 사용하여 Tool 호출 AI Agent를 구축한 다음 Mastra의 독립 실행형 서버에서 직접 Agent를 호출하여 이를 React에 연결합니다.

AI SDK UI와 AI Elements를 사용하여 아름다운 대화형 채팅 환경을 만듭니다.

시작하기 전에
시작하기 전에에 대한 직접 링크

  • 지원되는 Model Provider의 API 키가 필요합니다. 선호하는 Provider가 없다면 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를 설치합니다.

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 init을 실행합니다. 메시지가 표시되면 Provider(예: OpenAI)를 선택하고 키를 입력합니다.

npx mastra@latest init

그러면 예제 날씨 Agent와 다음 파일을 포함하는 src/mastra 폴더가 생성됩니다.

  • index.ts- Memory를 포함한 마스트라 구성
  • tools/weather-tool.ts- 특정 위치의 날씨를 가져오는 Tool
  • agents/weather-agent.ts- Tool을 사용하는 Prompt가 있는 기상 요원

다음 단계에서는 채팅 UI에서 weather-agent.ts를 호출합니다.

AI SDK UI 및 AI 요소 설치
AI SDK UI 및 AI 요소 설치에 대한 직접 링크

Mastra 어댑터와 함께 AI SDK UI를 설치합니다.

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

다음으로 AI 요소를 초기화합니다. 메시지가 표시되면 기본 옵션을 선택합니다.

npx ai-elements@latest

그러면 전체 AI Elements UI 구성 요소 라이브러리가@/components/ai-elements folder.

채팅 경로 만들기
채팅 경로 만들기에 대한 직접 링크

⁠src/mastra/index.ts를 열고 구성에 ⁠chatRoute()를 추가합니다. 그러면 React 프런트엔드가 AI SDK 호환 채팅 응답을 위해 호출할 수 있는 API 라우트가 생성되며, 다음 단계에서 이를 ⁠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 엔드포인트에 연결하여 Prompt를 전송하고 응답을 청크 단위로 스트리밍합니다. <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를 어디에나 배포하는 방법에 대해 자세히 알아보세요.

  • Mastra를 다음과 통합하세요.AI SDK UI

  • Agent 배포anywhere

On this page