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

# NestJS 프로젝트에 Mastra 통합

이 가이드에서는 Mastra 및 NestJS를 사용하여 Tool 호출 AI Agent를 구축합니다. 그만큼[NestJS server adapter](https://mastra.zisheng.pro/ko/reference/server/nestjs-adapter)Mastra의 Agent 및 Workflow 경로를 NestJS 모듈로 등록하므로 기존 NestJS 애플리케이션 내에서 실행됩니다.

## 시작하기 전에

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

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

NestJS 앱이 이미 있는 경우 다음 단계로 건너뜁니다.

다음 명령을 실행하여 새 NestJS 앱을 만듭니다.

**npm**:

```bash
npx @nestjs/cli new mastra-nest
```

**pnpm**:

```bash
pnpm dlx @nestjs/cli new mastra-nest
```

**Yarn**:

```bash
yarn dlx @nestjs/cli new mastra-nest
```

**Bun**:

```bash
bun x @nestjs/cli new mastra-nest
```

이 명령은 `mastra-nest`라는 프로젝트를 생성하지만 원하는 이름으로 바꿀 수 있습니다.

## 마스트라 초기화

NestJS 프로젝트 디렉터리로 이동합니다.

```bash
cd mastra-nest
```

[`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가 있는 기상 요원

다음 단계에서 `src/mastra/index.ts` 파일을 NestJS 어댑터에 전달합니다.

## 서버 어댑터 추가

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

`src/app.module.ts`를 열고 `MastraModule`을 등록합니다.

```typescript
import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}
```

> **노트:** `MastraModule`은 포괄적인 컨트롤러(`@All('*')`)를 등록합니다. 앱 모듈보다 먼저 가져오면 관련 없는 라우트를 가로채 404를 반환할 수 있습니다. 충돌을 방지하려면 `MastraModule`을 마지막에 가져오거나 전용 접두사(예: `/api/v1/mastra`) 아래에 마운트하세요.

## Agent 테스트

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

**npm**:

```bash
npm run start
```

**pnpm**:

```bash
pnpm run start
```

**Yarn**:

```bash
yarn run start
```

**Bun**:

```bash
bun 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?\"}]}"
```

## 자신의 서비스에 Mastra를 사용하세요

이 모듈은 NestJS 서비스에서 Mastra에 접근하는 두 가지 방법인 `MastraService` 래퍼와 `MASTRA` injection token을 내보냅니다.

### 마스트라서비스

`MastraService`일반적인 작업을 위한 편리한 메서드가 포함된 주입 가능한 래퍼입니다.

```typescript
import { Injectable } from '@nestjs/common'
import { MastraService } from '@mastra/nestjs'

@Injectable()
export class AgentService {
  constructor(private readonly mastraService: MastraService) {}

  async chat(agentId: string, message: string) {
    const agent = this.mastraService.getAgent(agentId)
    return agent.generate({
      messages: [{ role: 'user', content: message }],
    })
  }

  async runWorkflow(workflowId: string, input: Record<string, unknown>) {
    const workflow = this.mastraService.getWorkflow(workflowId)
    return workflow.start({ inputData: input })
  }
}
```

`MastraService`노출:

- `getMastra()`: 기본 `Mastra` 인스턴스를 반환합니다.
- `getAgent(id)`: `mastra.getAgent(id)`의 단축 메서드입니다.
- `getWorkflow(id)`: `mastra.getWorkflow(id)`의 단축 메서드입니다.
- `getOptions()`: 모듈 구성을 반환합니다.
- `isShuttingDown`: graceful shutdown이 시작된 후 `true`입니다.

### 마스트라 토큰

`Mastra` 인스턴스에 직접 접근해야 하는 경우(예: 스토리지, Memory 또는 기타 핵심 API에 접근할 때) `MASTRA` token으로 주입하세요.

```typescript
import { Injectable, Inject } from '@nestjs/common'
import { MASTRA } from '@mastra/nestjs'
import type { Mastra } from '@mastra/core/mastra'

@Injectable()
export class MemoryService {
  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}

  async getThreadMessages(threadId: string) {
    const memory = this.mastra.getMemory()
    return memory?.getMessages({ threadId })
  }
}
```

두 접근 방식 모두 `MastraModule`이 등록한 동일한 싱글톤 `Mastra` 인스턴스를 사용합니다.

## 다음 단계

이제 NestJS 내에서 작동하는 Mastra Agent가 실행됩니다. 프로젝트를 확장하려면:

- [Agent 개요](https://mastra.zisheng.pro/ko/docs/agents/overview)
- [Tool 사용](https://mastra.zisheng.pro/ko/docs/agents/using-tools)
- [Agent Memory](https://mastra.zisheng.pro/ko/docs/memory/overview)

NestJS 통합에 대한 자세한 내용은 다음을 참조하세요.

- [NestJS 어댑터 참조](https://mastra.zisheng.pro/ko/reference/server/nestjs-adapter)