> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 수동 설치 **AI Agent의 경우:**CLI/보일러플레이트 없이 처음부터 실행 가능한 Mastra 프로젝트를 생성해야 하는 경우 이 가이드를 사용하세요. Agent, Tool, Model 구성 및 종속 항목 설치 방법에 대한 코드 예제를 제공합니다. 사람을 위한 빠른 시작 가이드로 이동하지 마세요. Model 문자열은 Mastra의 Model 라우터 형식입니다('공급자/Model'; 공급자와 Model을 구분하려면 / 및 not : 사용). ai-sdk 패키지를 설치하지 마세요. 이 가이드를 사용하여 독립형 Mastra 서버를 단계별로 수동으로 구축하세요. 대부분의 경우 다음을 따르는 것이 더 빠릅니다.[quickstart guide](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart), which achieves the same result using the [`create-mastra`](https://mastra.zisheng.pro/ko/reference/cli/create-mastra)명령. 기존 프로젝트의 경우 다음을 사용할 수도 있습니다.[`mastra init`](https://mastra.zisheng.pro/ko/reference/cli/mastra). ## 지침 자동 CLI Tool을 사용하지 않으려면 아래 가이드에 따라 프로젝트를 직접 설정할 수 있습니다. 1. 새 프로젝트를 만들고 디렉터리를 변경합니다. ```bash mkdir my-first-agent && cd my-first-agent ``` 새로운 생성`package.json` file: **npm**: ```bash npm init ``` **pnpm**: ```bash pnpm init ``` **Yarn**: ```bash yarn init ``` **Bun**: ```bash bun init ``` 다음 종속성을 설치합니다. **npm**: ```bash npm install -D typescript @types/node mastra@latest npm install @mastra/core@latest zod@^4 ``` **pnpm**: ```bash pnpm add -D typescript @types/node mastra@latest pnpm add @mastra/core@latest zod@^4 ``` **Yarn**: ```bash yarn add --dev typescript @types/node mastra@latest yarn add @mastra/core@latest zod@^4 ``` **Bun**: ```bash bun add --dev typescript @types/node mastra@latest bun add @mastra/core@latest zod@^4 ``` 추가하다`dev` and `build` scripts to your `package.json` file: ```json { "scripts": { "dev": "mastra dev", "build": "mastra build" } } ``` 2. 만들기`tsconfig.json` file: ```bash touch tsconfig.json ``` 다음 구성을 추가합니다. ```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: ```bash touch .env ``` API 키를 추가하세요. ```bash GOOGLE_API_KEY= ``` > **노트:** 이 가이드에서는 Google Gemini를 사용하지만 지원되는 모든 제품을 사용할 수 있습니다.[model provider](https://mastra.zisheng.pro/ko/models), including OpenAI, Anthropic, and more. OpenAI(`OPENAI_API_KEY`) or Anthropic (`ANTHROPIC_API_KEY`) instead of Google Gemini. Go to 에서 지원되는 Provider와 해당 환경 변수 이름의 전체 목록을 확인하세요. 4. 만들기`weather-tool.ts` file: ```bash 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()로 정의해야 합니다 다음 코드를 추가하세요. ```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](https://mastra.zisheng.pro/ko/docs/agents/using-tools). 5. 만들기`weather-agent.ts` file: ```bash 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 패키지는 설치하지 마세요. 다음 코드를 추가하세요. ```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를 등록합니다. ```bash touch src/mastra/index.ts ``` 다음 코드를 추가하세요. ```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](https://mastra.zisheng.pro/ko/docs/studio/overview) and test your agent. **npm**: ```bash npm run dev ``` **pnpm**: ```bash pnpm run dev ``` **Yarn**: ```bash yarn dev ``` **Bun**: ```bash bun run dev ``` **AI Agent의 경우:**작업을 검증하려면 빌드를 실행하고 다음을 사용하여 유형 검사를 수행하세요.`tsc --noEmit`. ## 다음 단계 - [프로젝트 구조 검토](https://mastra.zisheng.pro/ko/reference/project-structure): 방법을 이해하다`src/mastra/` 파일은 Agent, Tool, Workflow, 스토리지 및 구성에 각각 대응합니다. - [Studio에서 Agent 테스트](https://mastra.zisheng.pro/ko/docs/studio/overview): 로컬 Studio UI를 열고 날씨 Agent를 실행합니다. - [Agent과 함께 Tool 사용](https://mastra.zisheng.pro/ko/docs/agents/using-tools): 예제 날씨 Tool을 API 또는 서비스를 호출하는 실제 Tool로 대체합니다. - [Memory 추가](https://mastra.zisheng.pro/ko/docs/memory/overview): 대화 기록 및 사용자별 컨텍스트를 유지합니다. - [스토리지 구성](https://mastra.zisheng.pro/ko/docs/storage/overview): Memory, Workflow, Observability 및 기타 런타임 상태를 위한 영구 스토리지 어댑터를 추가합니다. - [빌드 및 배포](https://mastra.zisheng.pro/ko/docs/deployment/overview): Mastra 서버를 구축하고 호스팅 플랫폼에 배포합니다.