> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # Mastra v1로 업그레이드 :::info\[최신 0.x 버전으로 업데이트] v1로 업그레이드하기 전에 Mastra를 최신 0.x 버전으로 업데이트했는지 확인하세요. 먼저 [최신 0.x로 업그레이드 가이드](https://mastra.ai/guides/v0/migrations/upgrade-to-latest-0x)를 따른 다음 여기로 돌아와 v1 마이그레이션을 완료하세요. ::: Mastra v1은 2026년 1월에 출시되었습니다. Mastra v1을 사용하여 새 프로젝트를 시작하거나 기존 프로젝트를 업그레이드하여 계속 업데이트와 지원을 받는 것이 좋습니다. 이 가이드에서는 Mastra 0.x에서 v1.0으로 업그레이드할 때의 주요 변경 사항을 다룹니다. 마이그레이션은 코드베이스를 체계적으로 업데이트하는 데 도움이 되도록 패키지 및 기능 영역별로 구성됩니다. :::tip\[도움이 필요하신가요?] 마이그레이션에 도움이 필요하신가요? [Discord 커뮤니티](https://discord.gg/BTYqqHKUrf)에서 질문하세요. ::: :::warning\[Mastra Cloud에서 이전하시나요?] 레거시 Mastra Cloud 제품은 [Mastra 플랫폼](https://mastra.zisheng.pro/ko/docs/mastra-platform/overview)으로 대체되었으며, 호스팅은 **Studio**(시각적 환경, Observability)와 **Server**(프로덕션 API)라는 두 가지 제품으로 분리되었습니다. 기존 Mastra Cloud 액세스 토큰은 Mastra 플랫폼에서 작동하지 않습니다. `mastra auth tokens create`로 새 토큰을 생성하세요. `telemetry:` 구성을 `observability:`로 마이그레이션하고 Studio 프로젝트를 생성하지 않은 채 v1 패키지로 업그레이드하면 Observability 데이터 전송이 중단됩니다. [Mastra Cloud 마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/mastra-cloud)를 처음부터 끝까지 따르세요. ::: ## 마이그레이션 전략 ### 모든 Mastra 패키지를 다음으로 업데이트하세요.`latest` tag 패키지 관리자를 사용하여 프로젝트 버전을 업데이트하세요. 호환성을 보장하려면 **모든** Mastra 패키지(모든 `@mastra/*` 패키지와 `mastra`)를 함께 업데이트하세요. 가장 일반적으로 사용되는 패키지를 업데이트하는 방법은 다음과 같습니다. **npm**: ```bash npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **pnpm**: ```bash pnpm add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **Yarn**: ```bash yarn add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **Bun**: ```bash bun add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` 다른 Mastra 패키지를 설치할 때 `@latest` 태그를 사용하면 사용 가능한 최신 v1 버전을 받게 됩니다. 버전 불일치를 방지하려면 모든 Mastra 패키지를 업데이트해야 합니다. 특히 모노레포에서는 더욱 주의하세요. ### Node.js 버전 업데이트 Mastra v1에는 Node.js **22.13.0** 이상이 필요합니다. 개발 및 프로덕션 환경을 그에 맞게 업데이트하세요. ### 마이그레이션 체크리스트 살펴보기 아래의 [마이그레이션 체크리스트](#migration-checklist)를 따라 코드베이스를 업데이트하세요. 각 항목은 해당 변경 사항을 자세히 설명하는 가이드로 연결됩니다. :::info\[코드수정] 자동화를 위한 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)를 준비했습니다. 원하는 경우 모든 v1 codemod를 한 번에 실행할 수 있습니다. ```bash npx @mastra/codemod@latest v1 ``` ::: :::note\[데이터베이스 마이그레이션 필요] PostgreSQL 또는 LibSQL 스토리지를 사용하는 경우 데이터베이스 마이그레이션을 실행해야 합니다. 자세한 내용은 [스토리지 마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage)를 참조하세요. ::: ## 영역별 주요 변경 사항 - **[마스트라 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/mastra)**- 구조 조정 및 자산 접근 변경 사항을 가져옵니다. - **[Agent 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/agent)**- 음성 메소드가 네임스페이스로 이동되었으며 스트리밍 API가 업데이트되었습니다. - **[Tool](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tools)**- CreateTool 실행 서명이 입력과 컨텍스트를 분리하도록 변경되었습니다. - **[Workflow](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/workflows)**- 기능 이름 변경 및 레거시 기능이 제거되었습니다. - **[Memory](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/memory)**- 구성에는 이제 명시적인 매개변수가 필요하며 기본값이 변경되었습니다. - **[저장](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage)**- 페이지 매김이 표준화되고 메소드 이름이 목록 패턴으로 변경되었습니다. - **[벡터](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/vectors)**- 벡터 저장 메소드의 이름이 목록 패턴으로 변경되었습니다. - **[조각](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/rag)**- 명확성을 위해 매개변수 이름이 업데이트되었습니다. - **[MCP](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/mcp)**- Tool 컨텍스트가 재구성되고 더 이상 사용되지 않는 클라이언트 클래스가 제거되었습니다. - **[트레이싱](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tracing)**- OTEL 원격 측정은 전용 관찰 패키지 및 내보내기로 대체되었습니다. - **[평가 및 득점자](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/evals)**- Scorers API가 새로운 명명 규칙으로 통합되었습니다. - **[CLI](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/cli)**- 더 간단한 인터페이스를 위해 명령과 플래그가 제거되었습니다. - **[전개](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/deployment)**- 표준 wrangler.json 속성 이름을 사용하도록 CloudflareDeployer 구성이 업데이트되었습니다. - **[클라이언트 SDK](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/client)**- 일관성을 위해 유형 및 유틸리티 이름이 변경되었습니다. - **[음성 패키지](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/voice)**- 패키지 이름이 음성에서 음성으로 변경되었습니다. ## 마이그레이션 체크리스트 대부분의 애플리케이션에 영향을 미치는 큰 영향을 미치는 변경 사항부터 시작하여 이 체크리스트를 순서대로 진행하세요. :::info\[코드수정] 자동화를 위한 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)를 준비했습니다. 마이그레이션 가이드 전반에서 특정 변경에 이를 사용하는 방법을 확인할 수 있습니다. 원하는 경우 모든 v1 codemod를 한 번에 실행할 수 있습니다. ```bash npx @mastra/codemod@latest v1 ``` ::: ### 큰 영향을 미치는 변경 사항 - `createTool` Tool 시그니처를 `(inputData, context)` 형식으로 업데이트 - [Tool](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tools) - 하위 경로 가져오기를 사용하도록 `@mastra/core` 가져오기 재구성 - [Mastra 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/mastra) - 페이지네이션을 `offset/limit`에서 `page/perPage`로 업데이트 - [스토리지](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage) - `@mastra/observability`를 설치하고 구성을 `new Observability()`로 래핑 - [추적](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tracing) - `telemetry:`에서 `observability:` 구성으로 마이그레이션(0.x OTEL에서 업그레이드하는 경우) - [추적](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tracing) ### 중간 영향 변경 - 코드베이스 전반에서 `RuntimeContext`를 `RequestContext`로 이름 변경 - [Agent 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/agent), [Tool](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tools), [Workflow](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/workflows) - 스토리지 메서드를 `get*`에서 `list*` 패턴으로 업데이트 - [스토리지](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage) - 직접 속성 접근을 getter 메서드로 대체 - [Mastra 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/mastra), [Agent 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/agent) - 기본 `thread` 범위를 사용한다면 Memory 범위 업데이트 - [Memory](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/memory) - 명명된 인수를 사용하도록 벡터 저장소 호출 업데이트 - [스토리지](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/storage) - Agent 메서드에서 `format` 매개변수 제거 - [Agent 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/agent) - `agent.voice` 네임스페이스를 사용하도록 음성 메서드 업데이트 - [Agent 클래스](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/agent) - 구성 속성 이름을 `processors`에서 `spanOutputProcessors`로 변경(사용자 지정 프로세서를 사용하는 경우) - [추적](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tracing) ### 영향이 적은 변경 사항 - 청크 옵션에서 `keepSeparator`를 `separatorPosition`으로 이름 변경 - [RAG](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/rag) - `createRunAsync`를 `createRun`으로 이름 변경 - [Workflow](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/workflows) - 음성 패키지 이름을 `@mastra/speech-*`에서 `@mastra/voice-*`로 업데이트 - [음성 패키지](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/voice) - 채점 메서드 업데이트: `runExperiment` → `runEvals`, `getScorerByName` → `getScorerById` - [Evals 및 채점기](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/evals) - 더 이상 사용되지 않는 CLI 플래그 제거 - [CLI](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/cli) - 클라이언트 SDK 타입을 `Get*`에서 `List*`로 업데이트 - [클라이언트 SDK](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/client) - `runCount`를 `retryCount`로 변경 - [Workflow](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/workflows) - 사용자 지정 내보내기 메서드를 `exportEvent`에서 `exportTracingEvent`로 업데이트(사용자 지정 내보내기를 사용하는 경우) - [추적](https://mastra.zisheng.pro/ko/guides/migrations/upgrade-to-v1/tracing)