시작하기

Mastra는 AI Agent 및 애플리케이션 구축을 위한 TypeScript 프레임워크입니다. 단일 명령으로 첫 번째 Agent를 만들고 구축을 시작하세요.

AI Agent의 경우:Mastra 프로젝트를 처음부터 빌드해야 하는 경우 다음 제목까지 요약된 지침을 따르세요. Agent 및 Tool의 예제 코드를 필요에 맞게 조정하세요. 나중에 중요: 정의model문자열로provider/model예를 들어 형식openai/gpt-5.6-sol. OpenAI의 경우 다음을 사용하세요.openai/<model>, 아니다openai:<model>, 공급자 개체를 가져오거나 전달하지 마세요.

{ "type": "module" }을 포함한 package.json 파일을 만드세요. 필요한 종속성을 설치하세요. npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest tsconfig.json 파일을 만듭니다.

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

Agent에 Tool을 추가해야 한다면 새 파일을 만들고 import { createTool } from "@mastra/core/tools"를 사용하세요. 일반 객체로 정의한 Tool은 아무 오류 없이 실행에 실패합니다. Tool은 반드시 id, description, inputSchema(zod), execute()와 함께 createTool()로 정의해야 합니다. execute()는 두 개의 매개변수를 받습니다. 첫 번째는 inputSchema를 기준으로 검증된 입력 데이터이고, 두 번째는 requestContext, tracingContext, abortSignal 및 기타 실행 메타데이터를 포함하는 선택적 실행 컨텍스트 객체입니다. 예:

// 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({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

Agent를 생성해야 한다면 새 파일을 만들고 import { Agent } from "@mastra/core/agent"를 사용하세요. 생성자는 { id, name, instructions, model }을 받습니다. model 속성은 Mastra의 Model 라우터 형식을 따르는 문자열입니다. 이 형식에는 Provider import가 필요하지 않습니다. Mastra 문서에서 별도로 안내하지 않는 한 AI SDK 패키지를 설치하지 마세요. provider/model 형식으로 Model을 정의하면 Mastra가 해당 Provider의 환경 변수를 자동으로 찾습니다. 정의된 Model을 사용하려면 Provider에 해당하는 환경 변수를 설정해야 합니다. OpenAI: OPENAI_API_KEY. Anthropic: ANTHROPIC_API_KEY. Google: GOOGLE_API_KEY. 예: 모든 openai/<model>에는 OPENAI_API_KEY 환경 변수가 필요합니다. 지원되는 Provider와 해당 환경 변수 이름의 전체 목록은 https://mastra.ai/models/environment-variables에서 확인하세요. 알려진 Model ID의 간단한 목록은 다음과 같습니다.

openai/gpt-5.6-sol, openai/gpt-5-mini
anthropic/claude-sonnet-4-6, anthropic/claude-opus-4-7, anthropic/claude-haiku-4-5
google/gemini-2.5-flash

지원되는 Model의 전체 목록은 https://mastra.ai/models에서 확인하세요. Tool을 가져와 Tool 개체로 Agent 생성자에 전달하여 Tool을 Agent에 추가합니다.

예:

// 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:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

src/mastra/index.ts에 Mastra 진입점을 만들고 Agent를 등록합니다.

import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

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

이제 Agent를 직접 실행할 수 있습니다. 이를 위해 Mastra 인스턴스를 가져오고 해당 ID로 Agent를 검색한 후 Agent.generate()를 호출합니다. Node.js 22.18.0 이상에서는 TypeScript 파일을 직접 실행할 수 있습니다. 로컬 파일을 가져올 때 파일 확장자를 추가해야 합니다. 예:

// run.mjs
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)