> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 개발하다 Mastra 프로젝트가 있으면 Agent를 개발, 실행 및 테스트할 준비가 된 것입니다. ## 로컬에서 Mastra 실행 Agent가 작동하는 모습을 확인하는 가장 빠른 방법은 [Mastra Studio](https://mastra.zisheng.pro/ko/docs/studio/overview)를 사용하는 것입니다. 프로젝트 루트에서 [`mastra dev`](https://mastra.zisheng.pro/ko/reference/cli/mastra)를 실행해 Studio와 로컬 개발 서버를 시작합니다. **npm**: ```bash npx mastra dev ``` **pnpm**: ```bash pnpm dlx mastra dev ``` **Yarn**: ```bash yarn dlx mastra dev ``` **Bun**: ```bash bun x mastra dev ``` [`http://localhost:4111`](http://localhost:4111)에서 Studio를 열어 Agent를 테스트하고 실행 내역을 살펴보세요. 개발 서버는 Agent, Tool, Workflow용 API도 제공합니다. [`http://localhost:4111/api`](http://localhost:4111/api)를 열어 사용 가능한 항목을 살펴본 다음, [Mastra Client](https://mastra.zisheng.pro/ko/docs/server/mastra-client)를 사용해 프런트엔드를 연결하세요. `src/mastra/` 디렉터리의 변경 사항은 개발 서버를 자동으로 다시 시작하므로, 개발하면서 서버를 수동으로 다시 시작할 필요가 없습니다. ## AI로 구축 Mastra는 코딩 Agent가 고품질 Mastra 코드를 작성하는 데 도움이 되는 기술과 CLI를 제공합니다. ### 마스트라 스킬 AI Model에는 Mastra API에 관한 최신 지식이 없을 수 있습니다. [Mastra Skill](https://github.com/mastra-ai/skills)을 사용해 코딩 Agent에 구현 지침, 모범 사례, 최신 Mastra 문서를 가져오는 방법을 제공하세요. 다음을 사용하여 스킬을 수동으로 설치하십시오. **npm**: ```bash npx skills add mastra-ai/skills ``` **pnpm**: ```bash pnpm dlx skills add mastra-ai/skills ``` **Yarn**: ```bash yarn dlx skills add mastra-ai/skills ``` **Bun**: ```bash bun x skills add mastra-ai/skills ``` 최신 지침을 얻으려면 정기적으로 기술을 업데이트하십시오. **npm**: ```bash npx skills update mastra ``` **pnpm**: ```bash pnpm dlx skills update mastra ``` **Yarn**: ```bash yarn dlx skills update mastra ``` **Bun**: ```bash bun x skills update mastra ``` > **노트:** [create mastra](https://mastra.zisheng.pro/ko/docs)로 프로젝트를 생성하면 명령이 Mastra Skill을 자동으로 설치하므로 코딩 Agent가 이를 찾아 사용할 수 있습니다. ### Mastra CLI [`mastra` CLI](https://mastra.zisheng.pro/ko/reference/cli/mastra)를 사용해 코딩 Agent가 업데이트를 테스트하고 결과를 검사할 수 있는 피드백 루프를 제공하세요. CLI를 통해 Agent, Workflow, Tool, Memory, Evals, Trace, 로그에 접근할 수 있습니다. 예를 들어 코딩 Agent는 Agent를 실행한 후 추적을 가져와 결과를 검사할 수 있습니다. ```bash npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}' npx mastra api --url http://localhost:4111 trace list ``` 코딩 Agent에 CLI 사용법을 알려 주려면 [Mastra Skill](#mastra-skill)을 설치해야 합니다. ## 프로젝트 구조 프레임워크를 도입할 때 가장 먼저 내려야 하는 결정 중 하나는 프로젝트를 구성하는 방법입니다. 프레임워크 코드는 `src/mastra/`에 두고 관련 프리미티브는 각각의 파일이나 폴더로 그룹화하는 것이 좋습니다. `src/mastra/index.ts`를 프리미티브를 구성하고 등록하는 중앙 위치로 사용하세요. 최소 프로젝트는 다음과 같습니다. ```text src/ mastra/ agents/ agent.ts tools/ tool.ts workflows/ workflow.ts scorers/ scorer.ts skills.ts index.ts ``` 기본 레이아웃과 권장 규칙은 [프로젝트 구조 레퍼런스](https://mastra.zisheng.pro/ko/reference/project-structure)를 참조하세요. ## 파일 기반 Agent :::실험적 파일 기반 Agent는 베타 버전이며 안정화되기 전에 변경될 수 있습니다. 파일 기반 검색은 `mastra dev` 또는 `mastra build`를 통해서만 실행됩니다. 웹 프레임워크나 서버 어댑터를 통하는 경우를 포함해 앱에서 `mastra`를 직접 가져오면 파일 기반 Agent가 검색되지 않습니다. 해당 Agent를 코드에서 등록하거나 Mastra를 별도의 서버로 실행하세요. ::: :::tip\[📹 보기] [첫 번째 파일 기반 Agent를 만드는 방법](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s) ::: 파일 기반 Agent를 사용하면 Mastra가 `src/mastra/` 아래의 지원되는 파일에서 Agent와 관련 프리미티브를 자동으로 [검색합니다](https://mastra.zisheng.pro/ko/reference/file-based-agents/config). 각 프리미티브를 [`Mastra`](https://mastra.zisheng.pro/ko/reference/core/mastra-class) 인스턴스로 가져와 등록하는 대신 규칙에 따라 파일을 구성합니다. 파일 시스템은 프로젝트 구조를 직접적으로 나타내므로 귀하와 귀하의 코딩 Agent는 모든 것이 코드에서 어떻게 연결되어 있는지 추적하지 않고도 프로젝트가 어떻게 조화되는지 이해할 수 있습니다. 프로젝트 전반에 걸쳐 파일 기반 Agent를 사용하거나 코드에 정의된 기본 요소와 함께 점진적으로 채택할 수 있습니다. 모든 Mastra 기능이나 사용 사례가 아직 지원되는 것은 아닙니다. ### 첫 번째 Agent 만들기 파일 기반 Agent는 `src/mastra/agents/` 아래의 자체 디렉터리에 있습니다. 작동하는 Agent를 만들려면 Model과 런타임 옵션을 위한 `config.ts` 파일과 항상 적용되는 Prompt를 위한 `instructions.md` 파일을 추가하세요. ```text src/mastra/agents/ writing-assistant/ config.ts instructions.md ``` 디렉터리 이름이 Agent의 기본 `id`와 `name`이 됩니다. 이 예시에서 Mastra는 Agent를 `writing-assistant`로 등록합니다. ```typescript import { agentConfig } from '@mastra/core/agent' export default agentConfig({ model: 'openai/gpt-5.6-sol', }) ``` ```markdown Rewrite text clearly and concisely. ``` `npx mastra dev`를 실행하고 Studio를 연 다음 `writing-assistant`를 선택해 테스트하세요. ### 검색 작동 방식 Mastra는 경로를 사용해 파일 기반 기능을 검색하고 이름을 지정합니다. Agent 디렉터리는 기본 Agent `id`와 `name`을 제공합니다. 예를 들어 `tools/search_docs.ts`는 Tool을 `search_docs`로 등록하고, `skills/style-guide.md`는 Skill을 `style-guide`로 등록합니다. 아래에서 확장 경로를 확인하세요. ### Agent 확장 Agent에 더 많은 기능이 필요할 때 파일이나 디렉터리를 추가하세요. | 경로 | 추가되는 항목 | | ------------------------------------------------------------------------------------------------------------------ | --------------------------- | | [`tools/.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools) | Model이 호출할 수 있는 함수 | | [`skills/.md`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills) | 관련 상황에서 Agent가 불러오는 상세 지침 | | [`memory.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/memory) | 대화 기록과 작업 컨텍스트 | | [`workspace.ts` and `workspace/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/workspace) | 파일 시스템 및 셸 접근 권한 | | [`subagents//`](https://mastra.zisheng.pro/ko/reference/file-based-agents/subagents) | 상위 Agent가 위임할 수 있는 전문 Agent | | 각 기능을 사용하는 Agent 옆에 해당 기능을 보관하세요. Mastra는 개발 서버가 시작되거나 다시 시작될 때 이러한 파일을 검색하고 등록합니다. | | | 지원되는 모든 파일 규칙과 구성 옵션은 [파일 기반 Agent 레퍼런스](https://mastra.zisheng.pro/ko/reference/file-based-agents/config)를 참조하세요. | |