개발하다

Mastra 프로젝트가 있으면 Agent를 개발, 실행 및 테스트할 준비가 된 것입니다.

로컬에서 Mastra 실행

Agent가 작동하는 모습을 확인하는 가장 빠른 방법은 Mastra Studio를 사용하는 것입니다. 프로젝트 루트에서 mastra dev를 실행해 Studio와 로컬 개발 서버를 시작합니다.

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

http://localhost:4111에서 Studio를 열어 Agent를 테스트하고 실행 내역을 살펴보세요. 개발 서버는 Agent, Tool, Workflow용 API도 제공합니다. http://localhost:4111/api를 열어 사용 가능한 항목을 살펴본 다음, Mastra Client를 사용해 프런트엔드를 연결하세요. src/mastra/ 디렉터리의 변경 사항은 개발 서버를 자동으로 다시 시작하므로, 개발하면서 서버를 수동으로 다시 시작할 필요가 없습니다.

AI로 구축

Mastra는 코딩 Agent가 고품질 Mastra 코드를 작성하는 데 도움이 되는 기술과 CLI를 제공합니다.

마스트라 스킬

AI Model에는 Mastra API에 관한 최신 지식이 없을 수 있습니다. Mastra Skill을 사용해 코딩 Agent에 구현 지침, 모범 사례, 최신 Mastra 문서를 가져오는 방법을 제공하세요. 다음을 사용하여 스킬을 수동으로 설치하십시오.

npm

npx skills add mastra-ai/skills

pnpm

pnpm dlx skills add mastra-ai/skills

Yarn

yarn dlx skills add mastra-ai/skills

Bun

bun x skills add mastra-ai/skills

최신 지침을 얻으려면 정기적으로 기술을 업데이트하십시오.

npm

npx skills update mastra

pnpm

pnpm dlx skills update mastra

Yarn

yarn dlx skills update mastra

Bun

bun x skills update mastra

노트

create mastra로 프로젝트를 생성하면 명령이 Mastra Skill을 자동으로 설치하므로 코딩 Agent가 이를 찾아 사용할 수 있습니다.

Mastra CLI

mastra CLI를 사용해 코딩 Agent가 업데이트를 테스트하고 결과를 검사할 수 있는 피드백 루프를 제공하세요. CLI를 통해 Agent, Workflow, Tool, Memory, Evals, Trace, 로그에 접근할 수 있습니다. 예를 들어 코딩 Agent는 Agent를 실행한 후 추적을 가져와 결과를 검사할 수 있습니다.

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을 설치해야 합니다.

프로젝트 구조

프레임워크를 도입할 때 가장 먼저 내려야 하는 결정 중 하나는 프로젝트를 구성하는 방법입니다. 프레임워크 코드는 src/mastra/에 두고 관련 프리미티브는 각각의 파일이나 폴더로 그룹화하는 것이 좋습니다. src/mastra/index.ts를 프리미티브를 구성하고 등록하는 중앙 위치로 사용하세요. 최소 프로젝트는 다음과 같습니다.

src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts

기본 레이아웃과 권장 규칙은 프로젝트 구조 레퍼런스를 참조하세요.

파일 기반 Agent

:::실험적

파일 기반 Agent는 베타 버전이며 안정화되기 전에 변경될 수 있습니다.

파일 기반 검색은 mastra dev 또는 mastra build를 통해서만 실행됩니다. 웹 프레임워크나 서버 어댑터를 통하는 경우를 포함해 앱에서 mastra를 직접 가져오면 파일 기반 Agent가 검색되지 않습니다. 해당 Agent를 코드에서 등록하거나 Mastra를 별도의 서버로 실행하세요. :::

:::tip[📹 보기]

첫 번째 파일 기반 Agent를 만드는 방법

:::

파일 기반 Agent를 사용하면 Mastra가 src/mastra/ 아래의 지원되는 파일에서 Agent와 관련 프리미티브를 자동으로 검색합니다. 각 프리미티브를 Mastra 인스턴스로 가져와 등록하는 대신 규칙에 따라 파일을 구성합니다. 파일 시스템은 프로젝트 구조를 직접적으로 나타내므로 귀하와 귀하의 코딩 Agent는 모든 것이 코드에서 어떻게 연결되어 있는지 추적하지 않고도 프로젝트가 어떻게 조화되는지 이해할 수 있습니다.

프로젝트 전반에 걸쳐 파일 기반 Agent를 사용하거나 코드에 정의된 기본 요소와 함께 점진적으로 채택할 수 있습니다. 모든 Mastra 기능이나 사용 사례가 아직 지원되는 것은 아닙니다.

첫 번째 Agent 만들기

파일 기반 Agent는 src/mastra/agents/ 아래의 자체 디렉터리에 있습니다. 작동하는 Agent를 만들려면 Model과 런타임 옵션을 위한 config.ts 파일과 항상 적용되는 Prompt를 위한 instructions.md 파일을 추가하세요.

src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md

디렉터리 이름이 Agent의 기본 id와 name이 됩니다. 이 예시에서 Mastra는 Agent를 writing-assistant로 등록합니다.

src/mastra/agents/writing-assistant/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/writing-assistant/instructions.md

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/<tool-name>.ts	Model이 호출할 수 있는 함수
skills/<skill-name>.md	관련 상황에서 Agent가 불러오는 상세 지침
memory.ts	대화 기록과 작업 컨텍스트
workspace.ts and workspace/	파일 시스템 및 셸 접근 권한
subagents/<agent-id>/	상위 Agent가 위임할 수 있는 전문 Agent
각 기능을 사용하는 Agent 옆에 해당 기능을 보관하세요. Mastra는 개발 서버가 시작되거나 다시 시작될 때 이러한 파일을 검색하고 등록합니다.
지원되는 모든 파일 규칙과 구성 옵션은 파일 기반 Agent 레퍼런스를 참조하세요.