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

# React + Vite 프로젝트에 Mastra 통합

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

[AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview)와 [AI Elements](https://ai-sdk.dev/elements)를 사용하여 아름다운 대화형 채팅 환경을 만듭니다.

## 시작하기 전에

- 지원되는 [Model Provider](https://mastra.zisheng.pro/ko/models)의 API 키가 필요합니다. 선호하는 Provider가 없다면 [OpenAI](https://mastra.zisheng.pro/ko/models/providers/openai)를 사용하세요.
- Node.js `v22.13.0` 이상 설치

## 새로운 React + Vite 앱 만들기(선택 사항)

Tailwind를 사용하는 React + Vite 앱이 이미 있다면 다음 단계로 건너뛰세요.

### 프로젝트 비계

다음 명령을 실행하여 [새 React + Vite 앱을 생성](https://vite.dev/guide/#scaffolding-your-first-vite-project)합니다.

**npm**:

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

**pnpm**:

```bash
pnpm create vite mastra-react --template react-ts
```

**Yarn**:

```bash
yarn create vite mastra-react --template react-ts
```

**Bun**:

```bash
bunx create-vite mastra-react --template react-ts
```

이 명령은 `mastra-react`라는 프로젝트를 생성하지만 원하는 이름으로 바꿀 수 있습니다. 프로젝트 디렉터리로 이동합니다.

```bash
cd mastra-react
```

### 순풍

다음으로 Tailwind를 설치합니다.

**npm**:

```bash
npm install tailwindcss @tailwindcss/vite
```

**pnpm**:

```bash
pnpm add tailwindcss @tailwindcss/vite
```

**Yarn**:

```bash
yarn add tailwindcss @tailwindcss/vite
```

**Bun**:

```bash
bun add tailwindcss @tailwindcss/vite
```

Vite 플러그인 구성:

```typescript
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`의 전체 내용을 다음으로 교체합니다.

```css
@import 'tailwindcss';
```

다음 `compilerOptions`를 `tsconfig.json`에 추가합니다.

```jsonc
{
  // ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
  },
}
```

경로를 해석할 수 있도록 `tsconfig.app.json`을 편집합니다.

```jsonc
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
    },
    // ...
  },
}
```

## 마스트라 초기화

[`mastra init`](https://mastra.zisheng.pro/ko/reference/cli/mastra)을 실행합니다. 메시지가 표시되면 Provider(예: OpenAI)를 선택하고 키를 입력합니다.

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x 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 요소 설치

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

**npm**:

```bash
npx ai-elements@latest
```

**pnpm**:

```bash
pnpm dlx ai-elements@latest
```

**Yarn**:

```bash
yarn dlx ai-elements@latest
```

**Bun**:

```bash
bun x ai-elements@latest
```

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

## 채팅 경로 만들기

⁠`src/mastra/index.ts`를 열고 구성에 [⁠chatRoute()](https://mastra.zisheng.pro/ko/reference/ai-sdk/chat-route)를 추가합니다. 그러면 React 프런트엔드가 AI SDK 호환 채팅 응답을 위해 호출할 수 있는 API 라우트가 생성되며, 다음 단계에서 이를 ⁠useChat()과 함께 사용합니다.

```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 추가

채팅 인터페이스를 생성하도록 `src/App.tsx` 파일을 교체합니다.

```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()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat)을 `chat/weather-agent` 엔드포인트에 연결하여 Prompt를 전송하고 응답을 청크 단위로 스트리밍합니다. [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) 컴포넌트로 응답 텍스트를 렌더링하고, [`<Tool>`](https://ai-sdk.dev/elements/components/tool) 컴포넌트로 Tool 호출을 표시합니다.

## Agent 테스트

채팅 인터페이스로 Agent를 테스트하려면 Mastra 서버와 Vite 개발 서버를 모두 실행하세요.

1. Mastra 개발 서버를 시작합니다.

   **npm**:

   ```bash
   npx mastra dev
   ```

   **pnpm**:

   ```bash
   pnpm dlx mastra dev
   ```

   **Yarn**:

   ```bash
   yarn dlx mastra dev
   ```

   **Bun**:

   ```bash
   bun x mastra dev
   ```

2. 별도의 터미널 창에서 Vite 개발 서버를 시작합니다.

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

3. 다음에서 신청서를 엽니다.<http://localhost:5173>

4. 날씨에 대해 물어보세요. API 키가 올바르게 설정되면 응답을 받게 됩니다.

## 다음 단계

React를 사용하여 Mastra Agent를 구축한 것을 축하합니다! 🎉

여기에서 자신만의 Tool와 논리를 사용하여 프로젝트를 확장할 수 있습니다.

- [Agent](https://mastra.zisheng.pro/ko/docs/agents/overview)에 관해 자세히 알아보기

- Agent에 고유한 기능을 제공하는 [Tool](https://mastra.zisheng.pro/ko/docs/agents/using-tools) 추가하기

- Agent에 사람과 같은 [Memory](https://mastra.zisheng.pro/ko/docs/memory/overview) 추가하기 준비가 되면 Mastra가 AI SDK UI 및 React와 통합되는 방법과 Agent를 어디에나 배포하는 방법에 대해 자세히 알아보세요.

- Mastra를 다음과 통합하세요.[AI SDK UI](https://mastra.zisheng.pro/ko/guides/build-your-ui/ai-sdk-ui)

- Agent 배포[anywhere](https://mastra.zisheng.pro/ko/docs/deployment/overview)