Mastra をインストール
Mastra を使い始めるには、大規模言語モデル（LLM）へのアクセスが必要です。既定では Mastra は OpenAI と連携するように設定されているため、利用を開始するには API キーが必要です。
Mastra は他の LLM プロバイダーにも対応しています。対応モデルの一覧とセットアップ手順は、Model Providers を参照してください。
前提条件
- Node.js
v20.0以上 - サポート対象のモデルプロバイダーの API キー
create mastra CLI でインストールする
CLI は Mastra を始める最速の方法です。create mastra はマシン上のどこからでも実行できます。
現在の CLI は ai-sdk v4 にのみ対応したプロジェクトを生成します。ai-sdk v5 を使用する場合は、ai-sdk v5 compatibility を参照してください。
CLI ウィザードを開始する
対話型セットアップを開始するには、次のコマンドを実行します：
npx create-mastra@latestCLI フラグでインストールする
必要なフラグをすべて渡すことで、Mastra CLI を非対話モードでも実行できます。例：
npx create-mastra@latest --project-name hello-mastra --example --components tools,agents,workflows --llm openaiテンプレートでインストールする
特定のユースケースを示すプリセットのテンプレートから始められます：
npx create-mastra@latest --template template-name利用可能なテンプレートの一覧や詳細は Templates を参照してください。
たとえば、text-to-SQL アプリケーションを作成するには：
npx create-mastra@latest --template text-to-sql利用可能な CLI オプションの一覧は create-mastra のドキュメントを参照してください。
API キーを追加する
.env ファイルに API キーを追加します：
OPENAI_API_KEY=<your-api-key>この例では OpenAI を使用しています。各 LLM プロバイダーで使用する環境変数名は異なります。詳細は Model Capabilities を参照してください。
Mastra Development Server を起動する
Mastra Development Server を起動し、Mastra Playground でエージェントをテストできます。
npm run dev手動でインストールする
以下の手順では、Mastra を手動でインストールする方法を順を追って説明します。
新規プロジェクトを作成
新規プロジェクトを作成し、ディレクトリへ移動します：
mkdir hello-mastra && cd hello-mastra@mastra/core パッケージを含む TypeScript プロジェクトを初期化する:
npm init -y
npm install typescript tsx @types/node mastra@latest --save-dev
npm install @mastra/core@latest zod@^3 @ai-sdk/openai@^1package.json に dev と build のスクリプトを追加します：
{
"scripts": {
// ...
"dev": "mastra dev",
"build": "mastra build"
}
}TypeScript の初期化
tsconfig.json ファイルを作成する：
touch tsconfig.json次の設定を追加する：
Mastra では、最新の Node.js バージョンに対応した module と moduleResolution の設定値が必要です。CommonJS や node といった古い設定は Mastra のパッケージと互換性がなく、モジュール解決エラーの原因になります。
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"strict": true,
"skipLibCheck": true,
"noEmit": true,
"outDir": "dist"
},
"include": [
"src/**/*"
]
}この TypeScript 設定は、最新のモジュール解決と厳格な型チェックを採用し、Mastra プロジェクト向けに最適化されています。
APIキーを設定
.env ファイルを作成する：
touch .envAPI キーを追加：
OPENAI_API_KEY=<あなたのAPIキー>この例では OpenAI を使用します。LLM プロバイダーごとにモデル名は異なります。詳細は Model Capabilities を参照してください。
ツールを作成
「weather-tool.ts」ファイルを作成する：
mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts次のコードを追加してください：
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
export const weatherTool = createTool({
id: "get-weather",
description: "指定した場所の現在の天気を取得する"
inputSchema: z.object({
location: z.string().describe("都市名")
}),
outputSchema: z.object({
output: z.string()
}),
execute: async () => {
return {
output: "天気は晴れです"
};
}
});weatherTool の完全な例は、Giving an Agent a Toolをご覧ください。
エージェントを作成
「weather-agent.ts」ファイルを作成する：
mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts次のコードを追加してください：
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";
export const weatherAgent = new Agent({
name: 'Weather Agent',
instructions: `
あなたは正確な気象情報を提供する、役に立つ天気アシスタントです。
主な役割は、ユーザーが特定の場所の天気情報を取得できるよう支援することです。応答時は次を守ってください:
- 場所が指定されていない場合は、必ず場所を確認する
- 場所名が英語でない場合は、英語に翻訳する
- 複数の要素を含む場所（例: "New York, NY"）が指定された場合は、最も関連性の高い部分（例: "New York"）を用いる
- 湿度、風況、降水などの関連情報を含める
- 簡潔でありながら有用な回答を心がける
現在の天気データを取得するには、weatherTool を使用する。
`,
model: openai('gpt-4o-mini'),
tools: { weatherTool }
});エージェントを登録
Mastra のエントリポイントを作成し、エージェントを登録する：
touch src/mastra/index.ts次のコードを追加してください：
import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";
export const mastra = new Mastra({
agents: { weatherAgent }
});Mastra Development Server を起動し、Mastra Playground でエージェントをテストできるようになりました。
既存のプロジェクトに追加する
Mastra は幅広いプロジェクトにインストールして統合できます。以下は、導入の手助けとなる統合ガイドへのリンクです：
mastra init
既存のプロジェクトに Mastra を導入するには、mastra init コマンドを使用します。
詳細は mastra init を参照してください。
ai-sdk v5 互換性
デフォルトでは、Mastra プロジェクトは ai-sdk v4 のみに対応しています。ai-sdk v5 を使用する場合は、生成されたプロジェクトに対して以下の変更を行ってください。
@ai-sdk/openai パッケージの最新バージョンをインストールします:
npm install @ai-sdk/openai@latestsrc/mastra/workflows/weather-workflow.ts の planActivities ステップを次のように更新します:
const response = await agent.stream([
const response = await agent.streamVNext([
{
role: 'user',
content: prompt,
},
]);