> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 시작하기 Mastra는 AI Agent 및 애플리케이션 구축을 위한 TypeScript 프레임워크입니다. 단일 명령으로 첫 번째 Agent를 만들고 구축을 시작하세요. **AI Agent의 경우:**Mastra 프로젝트를 처음부터 빌드해야 하는 경우 다음 제목까지 요약된 지침을 따르세요. Agent 및 Tool의 예제 코드를 필요에 맞게 조정하세요. 나중에 중요: 정의`model`문자열로`provider/model`예를 들어 형식`openai/gpt-5.6-sol`. OpenAI의 경우 다음을 사용하세요.`openai/`, 아니다`openai:`, 공급자 개체를 가져오거나 전달하지 마세요. `{ "type": "module" }`을 포함한 `package.json` 파일을 만드세요. 필요한 종속성을 설치하세요. `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest` tsconfig.json 파일을 만듭니다. ```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` 및 기타 실행 메타데이터를 포함하는 선택적 실행 컨텍스트 객체입니다. 예: ```ts // 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/`에는 `OPENAI_API_KEY` 환경 변수가 필요합니다. 지원되는 Provider와 해당 환경 변수 이름의 전체 목록은 에서 확인하세요. 알려진 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의 전체 목록은 에서 확인하세요. Tool을 가져와 Tool 개체로 Agent 생성자에 전달하여 Tool을 Agent에 추가합니다. 예: ```ts // 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를 등록합니다. ```ts 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 파일을 직접 실행할 수 있습니다. 로컬 파일을 가져올 때 파일 확장자를 추가해야 합니다. 예: ```ts // 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) ``` ## 빠른 시작 로컬 작업 영역, 셸 Tool, Memory, 작업 추적, 웹 액세스 및 반복 일정이 포함된 범용 Agent 하네스를 생성하려면 이 명령을 실행하세요. 또한 설치된 코딩 Agent에 대한 Mastra 기술을 설치하므로 메시지 표시 및 편집을 시작할 수 있습니다. **npm**: ```bash npm create mastra@latest ``` **pnpm**: ```bash pnpm create mastra@latest ``` **Yarn**: ```bash yarn create mastra ``` **Bun**: ```bash bunx create-mastra ``` 당신은 열 수 있습니다[Studio](https://mastra.zisheng.pro/ko/docs/studio/overview) 즉시 실행하면 Mastra 프로젝트용 대화형 UI가 열립니다. 다음을 참조하세요: [quickstart guide](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart) for a full walkthrough. ## 프레임워크와 통합 기존 프로젝트에 Mastra를 추가하거나 원하는 프레임워크로 새 앱을 만듭니다. - [Next.js](https://mastra.ai/ko/guides/getting-started/next-js) - [React](https://mastra.ai/ko/guides/getting-started/vite-react) - [Astro](https://mastra.ai/ko/guides/getting-started/astro) - [Express](https://mastra.ai/ko/guides/getting-started/express) - [SvelteKit](https://mastra.ai/ko/guides/getting-started/sveltekit) - [Hono](https://mastra.ai/ko/guides/getting-started/hono) 다른 프레임워크에 대해서는 다음을 참조하세요.[framework integration guides](https://mastra.zisheng.pro/ko/guides/getting-started/next-js). ## 템플릿 먹다[templates](https://mastra.ai/templates) 복제하여 수정할 수 있는 완전한 Mastra 프로젝트를 확인하세요. ## 사용 사례
**제품에 Agent 포함** 사용자가 Agent를 구축하거나 Agent와 상호 작용할 수 있도록 플랫폼에 AI 기능을 추가하세요. 사용처[Replit](https://mastra.zisheng.pro/blog/replitagent3), [Fireworks](https://mastra.zisheng.pro/blog/fireworks-xml-prompting), [Medusa](https://mastra.zisheng.pro/blog/medusa-ecommerce)
**고객 대면 도우미** 채팅, WhatsApp 또는 음성을 통해 문의를 처리하고, 약속을 예약하고, 미리 알림을 보내고, 질문에 답변하는 Agent를 구축하세요. 사용처[Vetnio](https://mastra.zisheng.pro/blog/vetnio), [Lua](https://mastra.zisheng.pro/blog/lua-scaling) 템플릿:[Docs Chatbot](https://mastra.zisheng.pro/templates/docs-chatbot), [Slack Agent](https://mastra.zisheng.pro/templates/slack-agent)
**내부 부조종사** HR 쿼리, 임상 문서, 영업 준비, 문서 생성 등 도메인을 이해하는 AI를 통해 직원들이 더 빠르게 작업할 수 있도록 지원하세요. 사용처[Factorial](https://mastra.zisheng.pro/blog/factorial-case-study), [Counsel Health](https://mastra.zisheng.pro/blog/counsel-health), [Cedar](https://mastra.zisheng.pro/blog/cedar-case-study), [SoftBank](https://mastra.zisheng.pro/blog/softbank-productivity-mastra-2025-08-20) 템플릿:[Chat with PDF](https://mastra.zisheng.pro/templates/chat-with-pdf), [Google Sheet Analysis](https://mastra.zisheng.pro/templates/google-sheets-analysis)
**데이터 분석 Agent** 사용자가 자연어로 데이터베이스와 대시보드를 쿼리할 수 있습니다. 데이터 소스에 연결하고 답변, 차트 또는 보고서를 반환합니다. 사용처[Index](https://mastra.zisheng.pro/blog/index-case-study), [PLAID Japan](https://mastra.zisheng.pro/blog/plaid-jpn-gcp-agents) 템플릿:[Chat with Database](https://mastra.zisheng.pro/templates/text-to-sql), [CSV to Questions](https://mastra.zisheng.pro/templates/csv-to-questions)
**콘텐츠 자동화** 콘텐츠 관리 시스템, 지식 기반 또는 문서 시스템에 맞게 구조화된 콘텐츠를 대규모로 생성, 변환 및 관리합니다. 사용처[Sanity](https://mastra.zisheng.pro/blog/sanity) 템플릿:[Chat with YouTube](https://mastra.zisheng.pro/templates/chat-with-youtube), [Flash Cards from PDF](https://mastra.zisheng.pro/templates/flash-cards-from-pdf)
**DevOps 및 엔지니어링 자동화** 배포를 자동화하고, 생산 문제를 디버그하고, 인프라를 관리하고, 대기 중인 Workflow를 처리합니다. 사용처[StarSling](https://mastra.zisheng.pro/blog/starsling) 템플릿:[GitHub PR Code Review](https://mastra.zisheng.pro/templates/github-pr-code-review-agent), [Browser Agent](https://mastra.zisheng.pro/templates/browsing-agent)
**영업 및 시장 진출 Workflow** 고객 대화를 구조화된 작업으로 전환하고, 투자 메모를 생성하거나, 지원 절차를 자동화하세요. 사용처[Kestral](https://mastra.zisheng.pro/blog/kestral), [Orange Collective](https://mastra.zisheng.pro/blog/orange-collective-vc-operating-system), [WorkOS](https://mastra.zisheng.pro/blog/workos-teaching-mastra) 템플릿:[Customer Feedback Summarization](https://mastra.zisheng.pro/templates/customer-feedback-summarization)
:::tip\[동영상] [Mastra 플랫폼 둘러보기](https://www.youtube.com/watch?v=NosES9aJxCc)조각들이 어떻게 조화를 이루는지 보여줍니다. :::