본문으로 건너뛰기

Mastra v1로 업그레이드

:::info[최신 0.x 버전으로 업데이트] v1로 업그레이드하기 전에 Mastra를 최신 0.x 버전으로 업데이트했는지 확인하세요. 먼저 최신 0.x로 업그레이드 가이드를 따른 다음 여기로 돌아와 v1 마이그레이션을 완료하세요. ::: Mastra v1은 2026년 1월에 출시되었습니다. Mastra v1을 사용하여 새 프로젝트를 시작하거나 기존 프로젝트를 업그레이드하여 계속 업데이트와 지원을 받는 것이 좋습니다.

이 가이드에서는 Mastra 0.x에서 v1.0으로 업그레이드할 때의 주요 변경 사항을 다룹니다. 마이그레이션은 코드베이스를 체계적으로 업데이트하는 데 도움이 되도록 패키지 및 기능 영역별로 구성됩니다.

:::tip[도움이 필요하신가요?] 마이그레이션에 도움이 필요하신가요? Discord 커뮤니티에서 질문하세요. ::: :::warning[Mastra Cloud에서 이전하시나요?] 레거시 Mastra Cloud 제품은 Mastra 플랫폼으로 대체되었으며, 호스팅은 Studio(시각적 환경, Observability)와 Server(프로덕션 API)라는 두 가지 제품으로 분리되었습니다. 기존 Mastra Cloud 액세스 토큰은 Mastra 플랫폼에서 작동하지 않습니다. mastra auth tokens create로 새 토큰을 생성하세요. telemetry: 구성을 observability:로 마이그레이션하고 Studio 프로젝트를 생성하지 않은 채 v1 패키지로 업그레이드하면 Observability 데이터 전송이 중단됩니다. Mastra Cloud 마이그레이션 가이드를 처음부터 끝까지 따르세요. :::

마이그레이션 전략
마이그레이션 전략에 대한 직접 링크

모든 Mastra 패키지를 다음으로 업데이트하세요.latest tag
update-all-mastra-packages-to-latest-tag에 대한 직접 링크

패키지 관리자를 사용하여 프로젝트 버전을 업데이트하세요. 호환성을 보장하려면 모든 Mastra 패키지(모든 @mastra/* 패키지와 mastra)를 함께 업데이트하세요. 가장 일반적으로 사용되는 패키지를 업데이트하는 방법은 다음과 같습니다.

npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest

다른 Mastra 패키지를 설치할 때 @latest 태그를 사용하면 사용 가능한 최신 v1 버전을 받게 됩니다. 버전 불일치를 방지하려면 모든 Mastra 패키지를 업데이트해야 합니다. 특히 모노레포에서는 더욱 주의하세요.

Node.js 버전 업데이트
Node.js 버전 업데이트에 대한 직접 링크

Mastra v1에는 Node.js 22.13.0 이상이 필요합니다. 개발 및 프로덕션 환경을 그에 맞게 업데이트하세요.

마이그레이션 체크리스트 살펴보기
마이그레이션 체크리스트 살펴보기에 대한 직접 링크

아래의 마이그레이션 체크리스트를 따라 코드베이스를 업데이트하세요. 각 항목은 해당 변경 사항을 자세히 설명하는 가이드로 연결됩니다. :::info[코드수정]

자동화를 위한 codemod를 준비했습니다. 원하는 경우 모든 v1 codemod를 한 번에 실행할 수 있습니다.

npx @mastra/codemod@latest v1

:::

:::note[데이터베이스 마이그레이션 필요]

PostgreSQL 또는 LibSQL 스토리지를 사용하는 경우 데이터베이스 마이그레이션을 실행해야 합니다. 자세한 내용은 스토리지 마이그레이션 가이드를 참조하세요. :::

영역별 주요 변경 사항
영역별 주요 변경 사항에 대한 직접 링크

  • 마스트라 클래스- 구조 조정 및 자산 접근 변경 사항을 가져옵니다.
  • Agent 클래스- 음성 메소드가 네임스페이스로 이동되었으며 스트리밍 API가 업데이트되었습니다.
  • Tool- CreateTool 실행 서명이 입력과 컨텍스트를 분리하도록 변경되었습니다.
  • Workflow- 기능 이름 변경 및 레거시 기능이 제거되었습니다.
  • Memory- 구성에는 이제 명시적인 매개변수가 필요하며 기본값이 변경되었습니다.
  • 저장- 페이지 매김이 표준화되고 메소드 이름이 목록 패턴으로 변경되었습니다.
  • 벡터- 벡터 저장 메소드의 이름이 목록 패턴으로 변경되었습니다.
  • 조각- 명확성을 위해 매개변수 이름이 업데이트되었습니다.
  • MCP- Tool 컨텍스트가 재구성되고 더 이상 사용되지 않는 클라이언트 클래스가 제거되었습니다.
  • 트레이싱- OTEL 원격 측정은 전용 관찰 패키지 및 내보내기로 대체되었습니다.
  • 평가 및 득점자- Scorers API가 새로운 명명 규칙으로 통합되었습니다.
  • CLI- 더 간단한 인터페이스를 위해 명령과 플래그가 제거되었습니다.
  • 전개- 표준 wrangler.json 속성 이름을 사용하도록 CloudflareDeployer 구성이 업데이트되었습니다.
  • 클라이언트 SDK- 일관성을 위해 유형 및 유틸리티 이름이 변경되었습니다.
  • 음성 패키지- 패키지 이름이 음성에서 음성으로 변경되었습니다.

마이그레이션 체크리스트
마이그레이션 체크리스트에 대한 직접 링크

대부분의 애플리케이션에 영향을 미치는 큰 영향을 미치는 변경 사항부터 시작하여 이 체크리스트를 순서대로 진행하세요.

:::info[코드수정]

자동화를 위한 codemod를 준비했습니다. 마이그레이션 가이드 전반에서 특정 변경에 이를 사용하는 방법을 확인할 수 있습니다. 원하는 경우 모든 v1 codemod를 한 번에 실행할 수 있습니다.

npx @mastra/codemod@latest v1

:::

큰 영향을 미치는 변경 사항
큰 영향을 미치는 변경 사항에 대한 직접 링크

  • createTool Tool 시그니처를 (inputData, context) 형식으로 업데이트 - Tool
  • 하위 경로 가져오기를 사용하도록 @mastra/core 가져오기 재구성 - Mastra 클래스
  • 페이지네이션을 offset/limit에서 page/perPage로 업데이트 - 스토리지
  • @mastra/observability를 설치하고 구성을 new Observability()로 래핑 - 추적
  • telemetry:에서 observability: 구성으로 마이그레이션(0.x OTEL에서 업그레이드하는 경우) - 추적

중간 영향 변경
중간 영향 변경에 대한 직접 링크

  • 코드베이스 전반에서 RuntimeContext를 RequestContext로 이름 변경 - Agent 클래스, Tool, Workflow
  • 스토리지 메서드를 get*에서 list* 패턴으로 업데이트 - 스토리지
  • 직접 속성 접근을 getter 메서드로 대체 - Mastra 클래스, Agent 클래스
  • 기본 thread 범위를 사용한다면 Memory 범위 업데이트 - Memory
  • 명명된 인수를 사용하도록 벡터 저장소 호출 업데이트 - 스토리지
  • Agent 메서드에서 format 매개변수 제거 - Agent 클래스
  • agent.voice 네임스페이스를 사용하도록 음성 메서드 업데이트 - Agent 클래스
  • 구성 속성 이름을 processors에서 spanOutputProcessors로 변경(사용자 지정 프로세서를 사용하는 경우) - 추적

영향이 적은 변경 사항
영향이 적은 변경 사항에 대한 직접 링크

  • 청크 옵션에서 keepSeparator를 separatorPosition으로 이름 변경 - RAG
  • createRunAsync를 createRun으로 이름 변경 - Workflow
  • 음성 패키지 이름을 @mastra/speech-*에서 @mastra/voice-*로 업데이트 - 음성 패키지
  • 채점 메서드 업데이트: runExperiment → runEvals, getScorerByName → getScorerById - Evals 및 채점기
  • 더 이상 사용되지 않는 CLI 플래그 제거 - CLI
  • 클라이언트 SDK 타입을 Get*에서 List*로 업데이트 - 클라이언트 SDK
  • runCount를 retryCount로 변경 - Workflow
  • 사용자 지정 내보내기 메서드를 exportEvent에서 exportTracingEvent로 업데이트(사용자 지정 내보내기를 사용하는 경우) - 추적
On this page