수동 설치

AI Agent의 경우:CLI/보일러플레이트 없이 처음부터 실행 가능한 Mastra 프로젝트를 생성해야 하는 경우 이 가이드를 사용하세요. Agent, Tool, Model 구성 및 종속 항목 설치 방법에 대한 코드 예제를 제공합니다. 사람을 위한 빠른 시작 가이드로 이동하지 마세요. Model 문자열은 Mastra의 Model 라우터 형식입니다('공급자/Model'; 공급자와 Model을 구분하려면 / 및 not : 사용). ai-sdk 패키지를 설치하지 마세요.

이 가이드를 사용하여 독립형 Mastra 서버를 단계별로 수동으로 구축하세요. 대부분의 경우 다음을 따르는 것이 더 빠릅니다.quickstart guide, which achieves the same result using the create-mastra명령. 기존 프로젝트의 경우 다음을 사용할 수도 있습니다.mastra init.

지침

자동 CLI Tool을 사용하지 않으려면 아래 가이드에 따라 프로젝트를 직접 설정할 수 있습니다.

1. 새 프로젝트를 만들고 디렉터리를 변경합니다.

   mkdir my-first-agent && cd my-first-agent

   새로운 생성package.json file:

   npm

   npm init

   pnpm

   pnpm init

   Yarn

   yarn init

   Bun

   bun init

   다음 종속성을 설치합니다.

   npm

   npm install -D typescript @types/node mastra@latest
   npm install @mastra/core@latest zod@^4

   pnpm

   pnpm add -D typescript @types/node mastra@latest
   pnpm add @mastra/core@latest zod@^4

   Yarn

   yarn add --dev typescript @types/node mastra@latest
   yarn add @mastra/core@latest zod@^4

   Bun

   bun add --dev typescript @types/node mastra@latest
   bun add @mastra/core@latest zod@^4

   추가하다dev and build scripts to your package.json file:

   package.json

   {
     "scripts": {
       "dev": "mastra dev",
       "build": "mastra build"
     }
   }

2. 만들기tsconfig.json file:

   touch tsconfig.json

   다음 구성을 추가합니다.

   tsconfig.json

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

   정보

   마스트라에는 현대가 필요합니다module and moduleResolution settings. Using CommonJS or node will cause resolution errors.

3. 만들기.env file:

   touch .env

   API 키를 추가하세요.

   .env

   GOOGLE_API_KEY=<your-api-key>

   노트

   이 가이드에서는 Google Gemini를 사용하지만 지원되는 모든 제품을 사용할 수 있습니다.model provider, including OpenAI, Anthropic, and more.

   OpenAI(OPENAI_API_KEY) or Anthropic (ANTHROPIC_API_KEY) instead of Google Gemini. Go to https://mastra.ai/models/environment-variables 에서 지원되는 Provider와 해당 환경 변수 이름의 전체 목록을 확인하세요.

4. 만들기weather-tool.ts file:

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

   사용import { createTool } from "@mastra/core/tools". 일반 객체로 정의한 Tool은 아무런 오류 없이 실행에 실패합니다. Tool은 반드시 id, description, inputSchema(zod), execute를 지정하여 createTool()로 정의해야 합니다

   다음 코드를 추가하세요.

   src/mastra/tools/weather-tool.ts

   import { createTool } from '@mastra/core/tools'
   import { z } from 'zod'
   
   export const weatherTool = createTool({
     id: 'get-weather',
     description: 'Get current weather for a location',
     inputSchema: z.object({
       location: z.string().describe('City name'),
     }),
     outputSchema: z.object({
       output: z.string(),
     }),
     execute: async ({ location }) => {
       return {
         output: `The weather in ${location} is sunny`,
       }
     },
   })

   정보

   우리는 단축하고 단순화했습니다weatherTool 예시를 참조하세요. 완성된 날씨 Tool은 다음에서 확인할 수 있습니다: Giving an Agent a Tool.

5. 만들기weather-agent.ts file:

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

   사용import { Agent } from "@mastra/core/agent". Constructor takes { id, name, instructions, model: 'openai/gpt-5.6-sol' }. Model 문자열은 Mastra의 Model 라우터 형식('provider/model')입니다. Provider와 Model을 구분할 때는 :가 아닌 /를 사용하세요. ai-sdk 패키지는 설치하지 마세요.

   다음 코드를 추가하세요.

   src/mastra/agents/weather-agent.ts

   import { Agent } from '@mastra/core/agent'
   import { weatherTool } from '../tools/weather-tool.ts'
   
   export const weatherAgent = new Agent({
     id: 'weather-agent',
     name: 'Weather Agent',
     instructions: `
         You are a helpful weather assistant that provides accurate weather information.
   
         Your primary function is to help users get weather details for specific locations. When responding:
         - Always ask for a location if none is provided
         - If the location name isn't in English, please translate it
         - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
         - Include relevant details like humidity, wind conditions, and precipitation
         - Keep responses concise but informative
   
         Use the weatherTool to fetch current weather data.
   `,
     model: 'google/gemini-2.5-pro',
     tools: { weatherTool },
   })

6. Mastra 진입점을 만들고 Agent를 등록합니다.

   touch src/mastra/index.ts

   다음 코드를 추가하세요.

   src/mastra/index.ts

   import { Mastra } from '@mastra/core'
   import { weatherAgent } from './agents/weather-agent.ts'
   
   export const mastra = new Mastra({
     agents: { weatherAgent },
   })

7. AI Agent의 경우:예를 들어 스크립트 작업을 할 때는 Studio를 실행하지 마십시오. 콘솔에 인쇄해야 합니다. Studio는 인간을 위해 오랫동안 실행되는 웹 기반 인터페이스입니다. 대신, agent.generate() 메서드를 직접 호출하세요. 예:import { mastra } from './src/mastra/index.ts'; const agent = mastra.getAgentById('weather-agent'); const response = await agent.generate('Weather in SF'); console.log(response.text);

   이제 시작할 수 있습니다Studio and test your agent.

   npm

   npm run dev

   pnpm

   pnpm run dev

   Yarn

   yarn dev

   Bun

   bun run dev

   AI Agent의 경우:작업을 검증하려면 빌드를 실행하고 다음을 사용하여 유형 검사를 수행하세요.tsc --noEmit.

다음 단계

• 프로젝트 구조 검토: 방법을 이해하다src/mastra/ 파일은 Agent, Tool, Workflow, 스토리지 및 구성에 각각 대응합니다.
• Studio에서 Agent 테스트: 로컬 Studio UI를 열고 날씨 Agent를 실행합니다.
• Agent과 함께 Tool 사용: 예제 날씨 Tool을 API 또는 서비스를 호출하는 실제 Tool로 대체합니다.
• Memory 추가: 대화 기록 및 사용자별 컨텍스트를 유지합니다.
• 스토리지 구성: Memory, Workflow, Observability 및 기타 런타임 상태를 위한 영구 스토리지 어댑터를 추가합니다.
• 빌드 및 배포: Mastra 서버를 구축하고 호스팅 플랫폼에 배포합니다.