본문으로 건너뛰기

NestJS 프로젝트에 Mastra 통합

이 가이드에서는 Mastra 및 NestJS를 사용하여 Tool 호출 AI Agent를 구축합니다. 그만큼NestJS server adapterMastra의 Agent 및 Workflow 경로를 NestJS 모듈로 등록하므로 기존 NestJS 애플리케이션 내에서 실행됩니다.

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

  • 지원되는 Model Provider의 API 키가 필요합니다. 선호하는 Provider가 없다면 OpenAI를 사용하세요.
  • Node.js v22.13.0 이상 설치
  • NestJS Express 플랫폼(@nestjs/platform-express)

새 NestJS 앱 만들기(선택 사항)
새 NestJS 앱 만들기(선택 사항)에 대한 직접 링크

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

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

npx @nestjs/cli new mastra-nest

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

마스트라 초기화
마스트라 초기화에 대한 직접 링크

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

cd mastra-nest

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

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

서버 어댑터 추가
서버 어댑터 추가에 대한 직접 링크

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

npm install @mastra/nestjs@latest

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

src/app.module.ts
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 테스트
Agent 테스트에 대한 직접 링크

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

npm run start

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

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를 사용하세요
자신의 서비스에 Mastra를 사용하세요에 대한 직접 링크

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

마스트라서비스
마스트라서비스에 대한 직접 링크

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

src/agent.service.ts
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으로 주입하세요.

src/memory.service.ts
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가 실행됩니다. 프로젝트를 확장하려면:

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

On this page