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 の互換性を参照してください。
CLI ウィザードを開始
対話型セットアップを開始するには、次のコマンドを実行します:
npx create-mastra@latest
CLI フラグを使用してインストール
必須フラグをすべて指定すれば、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@^1
package.json
に dev
と build
スクリプトを追加します:
{
"scripts": {
// ...
"dev": "mastra dev",
"build": "mastra build"
}
}
TypeScript を初期化する
tsconfig.json
ファイルを作成します:
touch tsconfig.json
次の設定を追加します:
{
"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 .env
API キーを追加します:
OPENAI_API_KEY=<your-api-key>
この例では 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: "Get current weather for a location",
inputSchema: z.object({
location: z.string().describe("City name")
}),
outputSchema: z.object({
output: z.string()
}),
execute: async () => {
return {
output: "The weather is sunny"
};
}
});
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@latest
src/mastra/workflows/weather-workflow.ts
の planActivities
ステップを次のように更新します:
const response = await agent.stream([
const response = await agent.streamVNext([
{
role: 'user',
content: prompt,
},
]);