Mastra 설치하기

Mastra를 시작하려면 대규모 언어 모델(LLM)에 대한 액세스가 필요합니다. 기본적으로 Mastra는 OpenAI와 함께 작동하도록 설정되어 있으므로, 시작하려면 API 키(API Key)가 필요합니다.

Mastra는 다른 LLM 제공업체자도 지원합니다. 지원되는 모델의 전체 목록과 설정 방법은 모델 제공업체(Model Providers)를 참조하세요.

사전 요구사항

• Node.js v20.0 이상

• 지원되는 모델 제공업체(Model Provider)의 API 키(API Key)

CLI를 사용한 설치

CLI는 Mastra를 시작하는 가장 빠른 방법입니다. 다음 명령어를 실행하여 대화형 설정을 시작하세요:

패키지 매니저별 설치 명령어

Copynpx create-mastra@latest

비대화형 설치

필요한 모든 플래그를 전달하여 Mastra CLI를 비대화형 모드로 실행할 수도 있습니다:

Copynpx create-mastra@latest --project-name hello-mastra --example --components tools,agents,workflows --llm openai

사용 가능한 CLI 옵션의 전체 목록은 create-mastra 문서를 참조하세요.

API 키 추가

.env 파일에 API 키를 추가하세요:

CopyOPENAI_API_KEY=<your-api-key>

이 예제는 OpenAI를 사용합니다. 각 LLM 제공업체는 고유한 이름을 사용합니다. 자세한 내용은 모델 기능을 참조하세요.

이제 Mastra 개발 서버를 시작하고 Mastra Playground를 사용하여 에이전트(Agent)를 테스트할 수 있습니다.

수동 설치

다음 단계는 Mastra를 수동으로 설치하는 과정을 안내합니다.

1. 새 프로젝트 생성

새 프로젝트를 생성하고 디렉토리를 변경하세요:

Copymkdir hello-mastra && cd hello-mastra

@mastra/core 패키지를 포함하여 TypeScript 프로젝트를 초기화하세요:

Copynpm init -y
npm install typescript tsx @types/node mastra@latest --save-dev
npm install @mastra/core@latest zod@^3 @ai-sdk/openai

package.json에 dev 및 build 스크립트를 추가하세요:

Copy{
  "scripts": {
    // ...
    "dev": "mastra dev",
    "build": "mastra build"
  }
}

2. TypeScript 초기화

tsconfig.json 파일을 생성하세요:

Copytouch tsconfig.json

다음 설정을 추가하세요:

Copy{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": [
    "src/**/*"
  ]
}

이 TypeScript 설정은 최신 모듈 해석과 엄격한 타입 검사를 사용하여 Mastra 프로젝트에 최적화되어 있습니다.

3. API 키 설정

.env 파일을 생성하세요:

Copytouch .env

API 키를 추가하세요:

CopyOPENAI_API_KEY=<your-api-key>

이 예제는 OpenAI를 사용합니다. 각 LLM 제공업체는 고유한 이름을 사용합니다. 자세한 내용은 모델 기능을 참조하세요.

4. 도구(Tool) 생성

weather-tool.ts 파일을 생성하세요:

Copymkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts

다음 코드를 추가하세요:

Copyimport { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "특정 위치의 현재 날씨 가져오기",
  inputSchema: z.object({
    location: z.string().describe("도시 이름")
  }),
  outputSchema: z.object({
    output: z.string()
  }),
  execute: async () => {
    return {
      output: "날씨가 맑습니다"
    };
  }
});

전체 weatherTool 예제는 에이전트에 도구 제공에서 확인하세요.

5. 에이전트(Agent) 생성

weather-agent.ts 파일을 생성하세요:

Copymkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts

다음 코드를 추가하세요:

Copyimport { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: `
      당신은 정확한 날씨 정보를 제공하는 유용한 날씨 도우미입니다.

      주요 기능은 특정 위치의 날씨 상세 정보를 사용자에게 제공하는 것입니다. 응답할 때:
      - 위치가 제공되지 않으면 항상 위치를 물어보세요
      - 위치 이름이 영어가 아닌 경우, 번역해 주세요
      - 여러 부분으로 구성된 위치(예: "뉴욕, NY")를 제공할 때는 가장 관련성 높은 부분(예: "뉴욕")을 사용하세요
      - 습도, 바람 상태, 강수량과 같은 관련 세부 정보를 포함하세요
      - 응답은 간결하되 정보가 풍부하게 유지하세요

      현재 날씨 데이터를 가져오려면 weatherTool을 사용하세요.
`,
  model: openai('gpt-4o-mini'),
  tools: { weatherTool }
});

6. 에이전트(Agent) 등록

Mastra 진입점을 생성하고 에이전트를 등록하세요:

Copytouch src/mastra/index.ts

다음 코드를 추가하세요:

Copyimport { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent }
});

이제 Mastra 개발 서버를 시작하고 Mastra Playground를 사용하여 에이전트를 테스트할 수 있습니다.

기존 프로젝트에 추가

Mastra는 다양한 프로젝트에 설치하고 통합할 수 있습니다. 시작하는 데 도움이 되는 통합 가이드 링크입니다:

• Next.js

• Vite + React

• Astro

• Express

mastra init

기존 프로젝트에 Mastra를 설치하려면 mastra init 명령어를 사용하세요.

자세한 내용은 mastra init을 참조하세요.

2025년 7월 26일 기준 번역
by dongne.lab@gmail.com