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

# Express 프로젝트에 Mastra 통합

이 가이드에서는 Mastra 및 Express를 사용하여 Tool 호출 AI Agent를 구축합니다. 사용하여[Express server adapter](https://mastra.zisheng.pro/ko/reference/server/express-adapter), 라우팅을 직접 작성하거나 별도의 Mastra 서버를 실행하지 않고도 Agent를 HTTP 엔드포인트로 노출할 수 있습니다.

## 시작하기 전에

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

## 새 Express 앱 만들기(선택 사항)

이미 Express 앱이 있는 경우 다음 단계로 건너뛰세요.

이 [보일러플레이트 저장소](https://github.com/mastra-ai/express-ts-boilerplate)를 복제하고 종속성을 설치합니다.

**HTTPS**:

**npm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**SSH**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 3**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 4**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 5**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 6**:

**npm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 7**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 8**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 9**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 10**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

## 마스트라 초기화

Express 프로젝트 디렉터리 내에서 다음을 실행하세요.[`mastra init`](https://mastra.zisheng.pro/ko/reference/cli/mastra).

메시지가 표시되면 공급자(예: OpenAI)를 선택하고 키를 입력합니다.

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

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

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

나중에 `src/mastra/index.ts` 파일을 Express 서버 어댑터에 전달합니다.

## 서버 어댑터 추가

Express 서버 어댑터 패키지를 설치합니다.

**npm**:

```bash
npm install @mastra/express@latest
```

**pnpm**:

```bash
pnpm add @mastra/express@latest
```

**Yarn**:

```bash
yarn add @mastra/express@latest
```

**Bun**:

```bash
bun add @mastra/express@latest
```

`src/index.ts`에서 Express 진입점 파일을 열고 필요한 import 및 초기화 코드를 추가합니다.

```typescript
import express, { type Request, type Response } from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
const PORT = process.env.PORT || 3000

// Middleware
app.use(express.json())

const server = new MastraServer({ app, mastra })
await server.init()

// Routes
app.get('/', (_req: Request, res: Response) => {
  res.json({ message: 'Hello, World!' })
})

// Start server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`)
})
```

⁠`MastraServer`는 기존 Express `app`과 루트 ⁠`mastra` 인스턴스로 초기화됩니다. `⁠init()`을 호출하면 Mastra 미들웨어가 등록되고 사용 가능한 모든 Mastra 엔드포인트가 노출됩니다.

## Agent 테스트

기본적으로 Mastra 엔드포인트는 `/api` 하위 경로에 위치하며 Agent/Workflow ID를 사용합니다. `mastra init`으로 생성된 기본 `weather-agent`는 `/api/agents/weather-agent`에서 사용할 수 있습니다. Express 서버를 시작하십시오.

```bash
npm run start
```

별도의 터미널 창에서 `curl`을 사용하여 날씨 Agent에게 질문합니다.

```bash
curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
```

## 다음 단계

Express를 사용하여 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가 Express와 통합되는 방법에 대해 자세히 읽어보세요.

- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)