Mastra AIエージェント開発手順【2026年最新マルチLLM・RAG】

2026年6月21日

Contents

1 1. 開発環境の準備と Mastra CLI のインストール
2 2. Mastra プロジェクトの作成とディレクトリ構造
- 2.1 2‑1. mastra init によるプロジェクト雛形生成
  - 2.1.1 生成結果（概要）
- 2.2 2‑2. 各ディレクトリの役割とベストプラクティス
3 3. マルチ LLM プロバイダー設定と Assistants の実装
4 4. ワークフロー、RAG／Memory／Observability の構築
5 5. テスト・コンテナ化・本番デプロイパターン
6 6. ライセンス・利用規約・法的留意点
7 7. 総括と次のステップ
- 7.1 次にやるべきこと
- 7.2 付録：リンク集

スポンサードリンク

1. 開発環境の準備と Mastra CLI のインストール

このセクションでは、Node.js とパッケージマネージャ、TypeScript の基本設定に加えて、Mastra CLI を安全かつ確実に導入する手順を示します。開発基盤が整っていないと、後続のビルドやデプロイで多くの手戻りが発生するため、まずはここで環境を固めましょう。

1‑1. Node.js とパッケージマネージャ (npm / Yarn) のセットアップ

Node.js は LTS（v20 系） を使用します。公式サイトからインストーラを取得し、以下のコマンドでバージョンを確認してください。

node -v   # 例: v20.12.0
npm -v    # npm は Node に同梱されています

node -v # 例: v20.12.0

npm -v # npm は Node に同梱されています

Yarn のインストール（任意）

Yarn を利用したい場合は、次のコマンドでグローバルインストールします。Yarn は ワークスペース機能 が強力なため、大規模モノレポでも便利です。

npm install --global yarn   # npm 7+ では `--location=global` 推奨
yarn -v                      # バージョン確認

npm install --global yarn # npm 7+ では `--location=global` 推奨

yarn -v # バージョン確認

※ 注意: グローバルインストールは sudo が不要な環境で行うか、nvm/Volta 等のバージョンマネージャと併用してください。

1‑2. TypeScript プロジェクトの初期化

以下の手順で作業ディレクトリを作成し、TypeScript の開発環境を整えます。tsconfig.json は公式推奨設定にカスタマイズしています。

mkdir my-mastra-app &amp;&amp; cd my-mastra-app
yarn init -y                         # package.json を生成
yarn add --dev typescript @types/node
npx tsc --init                        # tsconfig.json の雛形作成

mkdir my-mastra-app && cd my-mastra-app

yarn init -y # package.json を生成

yarn add --dev typescript @types/node

npx tsc --init # tsconfig.json の雛形作成

推奨 `tsconfig.json` 設定

設定項目	推奨値	解説
`"target"`	`"ES2022"`	最新ランタイムの最適化
`"moduleResolution"`	`"node"`	Node.js 互換性確保
`"strict"`	`true`	型安全を徹底
`"outDir"`	`"dist"`	ビルド成果物の分離
`"sourceMap"`	`true`	デバッグ用ソースマップ生成

1‑3. Mastra CLI のインストール（グローバル vs ローカル）

Mastra CLI は公式 npm パッケージ @mastra/cli として配布されています。プロジェクトごとにバージョンを固定したい場合はローカルインストール、CLI を頻繁に利用する開発者はグローバルインストールがおすすめです。

1‑3‑a. グローバルインストール（推奨バージョン確認付き）

npm install -g @mastra/cli@latest   # 常に最新を取得
mastra --version                     # → 2.5.0 （2026‑06‑21 時点）

npm install -g @mastra/cli@latest # 常に最新を取得

mastra --version # → 2.5.0 （2026‑06‑21 時点）

バージョン確認のベストプラクティス
npm view @mastra/cli version または公式 GitHub Releases ページで、リリースノートと互換性情報を必ずチェックしてください。

1‑3‑b. プロジェクトごとのローカルインストール

yarn add -D @mastra/cli@2.5.0
npx mastra init   # テンプレート生成コマンド（後述）

yarn add -D @mastra/cli@2.5.0

npx mastra init # テンプレート生成コマンド（後述）

1‑4. 公式ドキュメントと外部リソースへのリンク集

リンク先	内容
Mastra 公式サイト	https://mastra.ai （トップページ、バージョン情報）
CLI API リファレンス	https://docs.mastra.ai/cli
Zenn 記事（実装ガイド）	https://zenn.dev/machamu/articles/mastra-ai-agent-framework
Aigent Lab 完全ガイド（2026 年版）	https://aigentlab.tech/articles/mastra-typescript-ai-agent-framework-complete-guide-2026/

2. Mastra プロジェクトの作成とディレクトリ構造

この章では mastra init コマンドで生成されるテンプレートを元に、役割別フォルダ設計を解説します。明確な階層構造はコードの可読性・保守性を高め、チーム開発でも衝突を防止できます。

2‑1. `mastra init` によるプロジェクト雛形生成

以下コマンドで my-agent ディレクトリが自動作成されます。実行後はディレクトリ構造と主要ファイルを確認してください。

npx mastra init my-agent

1 2	npx mastra init my-agent

生成結果（概要）

my-agent/
├─ src/
│  ├─ agents/      # エージェント実装
│  ├─ workflows/   # ワークフロー定義
│  ├─ config/      # LLM・シークレット設定
│  └─ tests/       # ユニット / 統合テスト
├─ .env.example    # 環境変数テンプレート（Git 管理対象）
└─ mastra.config.ts

my-agent/

├─ src/

│ ├─ agents/ # エージェント実装

│ ├─ workflows/ # ワークフロー定義

│ ├─ config/ # LLM・シークレット設定

│ └─ tests/ # ユニット / 統合テスト

├─ .env.example # 環境変数テンプレート（Git 管理対象）

└─ mastra.config.ts

2‑2. 各ディレクトリの役割とベストプラクティス

ディレクトリ	主な内容	実装上のポイント
`src/agents`	ビジネスロジックを持つエージェントクラス / 関数	1 ファイル＝1 エージェント、テストは同名 `.test.ts` に分離
`src/workflows`	複数プラグインやツールチェーンの組み合わせ定義	再利用可能な Toolkit を作成し、DI（依存性注入）で注入
`src/config`	LLM プロバイダー設定・環境変数ロードユーティリティ	`dotenv-flow` で複数環境（dev / prod）を管理
`src/tests`	Jest / Playwright テストコード	カバレッジは最低 80%、CI に必ず組み込む

公式ガイド参照：https://docs.mastra.ai/guide/project-structure

3. マルチ LLM プロバイダー設定と Assistants の実装

本章では、OpenAI・Claude・Gemini・Llama といった主要モデルを ProviderFactory 経由で切り替える方法と、安全な認証情報管理手順を示します。マルチプロバイダー構成は、ベンダーロックイン防止に有効です。

3‑1. プロバイダー設定ファイル (`src/config/providers.ts`)

以下コードは公式ドキュメントのサンプルをベースに、環境変数と型安全を両立させた実装例です。

// src/config/providers.ts
import { ProviderFactory } from '@mastra/core';
import {
  OpenAIProvider,
  ClaudeProvider,
  GeminiProvider,
  LlamaProvider,
} from '@mastra/providers';

export const providers = {
  openai: new OpenAIProvider({
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  }),
  claude: new ClaudeProvider({
    apiKey: process.env.CLAUDE_API_KEY!,
    model: 'claude-3-5-sonnet',
  }),
  gemini: new GeminiProvider({
    apiKey: process.env.GEMINI_API_KEY!,
    model: 'gemini-1.5-pro',
  }),
  llama: new LlamaProvider({
    endpoint: process.env.LLAMA_ENDPOINT!,
    model: 'llama2-70b',
  }),
};

export const providerFactory = new ProviderFactory(providers);

// src/config/providers.ts

import { ProviderFactory } from '@mastra/core';

import {

OpenAIProvider,

ClaudeProvider,

GeminiProvider,

LlamaProvider,

} from '@mastra/providers';

export const providers = {

openai: new OpenAIProvider({

apiKey: process.env.OPENAI_API_KEY!,

model: 'gpt-4o',

}),

claude: new ClaudeProvider({

apiKey: process.env.CLAUDE_API_KEY!,

model: 'claude-3-5-sonnet',

}),

gemini: new GeminiProvider({

apiKey: process.env.GEMINI_API_KEY!,

model: 'gemini-1.5-pro',

}),

llama: new LlamaProvider({

endpoint: process.env.LLAMA_ENDPOINT!,

model: 'llama2-70b',

}),

};

export const providerFactory = new ProviderFactory(providers);

ポイント
- process.env.*! の使用は「必ず設定されている」ことを TypeScript に示すためですが、実運用では dotenv-flow と併せて バリデーションロジック（例: zod）で欠損を検知してください。

3‑2. 安全なシークレット管理

手法	特徴	推奨利用シーン
`.env` ファイル	開発時の手軽さ	ローカル / CI のテスト環境
Google Secret Manager	IAM ベースのアクセス制御、ローテーション API	GCP デプロイ
AWS Secrets Manager	自動ローテーション・バージョニング	AWS 環境
HashiCorp Vault	エンタープライズ向け高度なポリシー	大規模組織

Secret Loader の実装例

// src/config/secretLoader.ts
import { loadSecrets } from '@mastra/utils';

export async function initSecrets() {
  await loadSecrets([
    'OPENAI_API_KEY',
    'CLAUDE_API_KEY',
    'GEMINI_API_KEY',
    'LLAMA_ENDPOINT',
  ]);
}

// src/config/secretLoader.ts

import { loadSecrets } from '@mastra/utils';

export async function initSecrets() {

await loadSecrets([

'OPENAI_API_KEY',

'CLAUDE_API_KEY',

'GEMINI_API_KEY',

'LLAMA_ENDPOINT',

]);

}

initSecrets() はアプリ起動時（src/index.ts）で呼び出すだけで、バックエンドとフロントエンドの両方でシークレットが自動ロードされます。

3‑3. Assistants の実装例

(a) クラスベース（汎用チャット）

// src/agents/ChatAssistant.ts
import { Assistant } from '@mastra/core';
import { providerFactory } from '../config/providers';

export class ChatAssistant extends Assistant {
  constructor() {
    super({
      name: 'ChatAssistant',
      description: '汎用会話エージェント',
      defaultProvider: providerFactory.get('openai'), // デフォルトは OpenAI
    });
  }

  async handle(message: string) {
    const response = await this.provider.generate({
      prompt: `ユーザー: ${message}\nアシスタント:`,
      maxTokens: 512,
    });
    return response.text.trim();
  }
}

// src/agents/ChatAssistant.ts

import { Assistant } from '@mastra/core';

import { providerFactory } from '../config/providers';

export class ChatAssistant extends Assistant {

constructor() {

super({

description: '汎用会話エージェント',

defaultProvider: providerFactory.get('openai'), // デフォルトは OpenAI

});

}

async handle(message: string) {

const response = await this.provider.generate({

prompt: `ユーザー: ${message}\nアシスタント:`,

maxTokens: 512,

});

return response.text.trim();

}

(b) 関数ベース（軽量ユースケース）

// src/agents/simpleAssistant.ts
import { createAssistant } from '@mastra/core';
import { providerFactory } from '../config/providers';

export const simpleAssistant = createAssistant({
  name: 'Simple',
  provider: providerFactory.get('gemini'),
  async run(input) {
    const res = await this.provider.generate({ prompt: input });
    return res.text;
  },
});

// src/agents/simpleAssistant.ts

import { createAssistant } from '@mastra/core';

import { providerFactory } from '../config/providers';

export const simpleAssistant = createAssistant({

provider: providerFactory.get('gemini'),

async run(input) {

const res = await this.provider.generate({ prompt: input });

return res.text;

});

どちらの形でも providerFactory.get('<key>') によって任意プロバイダーへ切り替え可能です。コードベースが大きくなるほどクラスベース、軽量スクリプトは関数ベースを選択してください。

4. ワークフロー、RAG／Memory／Observability の構築

この章では、Toolkit と Plugins によるツールチェーンの組み立て方、ベクトルストア選定とインデックス作成、対話メモリの永続化戦略、そして本番環境で欠かせない Observability（ログ・メトリクス）設定を具体例とともに解説します。

4‑1. Toolkit と Plugins の組み立て

Toolkit はプラグイン集合体です。以下は検索プラグインと JSON パーサープラグインを組み合わせた例です。

// src/toolkit.ts
import { Toolkit } from '@mastra/core';
import { SearchPlugin } from '@mastra/plugins/search';
import { JsonParsePlugin } from '@mastra/plugins/json';
import { providerFactory } from './config/providers';

export const defaultToolkit = new Toolkit([
  new SearchPlugin({ provider: providerFactory.get('openai') }),
  new JsonParsePlugin(),
]);

// src/toolkit.ts

import { Toolkit } from '@mastra/core';

import { SearchPlugin } from '@mastra/plugins/search';

import { JsonParsePlugin } from '@mastra/plugins/json';

import { providerFactory } from './config/providers';

export const defaultToolkit = new Toolkit([

new SearchPlugin({ provider: providerFactory.get('openai') }),

new JsonParsePlugin(),

]);

ポイント：プラグインは DI（依存性注入） で提供することで、テスト時にモックしやすくなります。

4‑2. ベクトルストア選定とインデックス作成

2026 年現在、主流のベクトルストアは以下です。選択基準はスケール要件・コスト・運用体制です。

ストア	主な特徴	推奨ユースケース
Pinecone	完全マネージド、リアルタイム検索、グローバルレプリカ	大規模商用向け
Weaviate	オープンソース・オンプレミス可、GraphQL API	データ主権が必要な組織
Chroma	ローカル開発・プロトタイプ向け、軽量	PoC / 小規模実験

インデックス作成サンプル（Pinecone）

// src/workflows/createIndex.ts
import { VectorStore } from '@mastra/vector';
import { loadDocuments } from '../utils/docLoader';

export async function createIndex() {
  const store = new VectorStore({
    provider: 'pinecone',
    indexName: 'my-docs',
  });

  const docs = await loadDocuments('./data');
  for (const doc of docs) {
    await store.upsert({
      id: doc.id,
      vector: await store.embed(doc.text),
      metadata: { source: doc.path },
    });
  }
}

// src/workflows/createIndex.ts

import { VectorStore } from '@mastra/vector';

import { loadDocuments } from '../utils/docLoader';

export async function createIndex() {

const store = new VectorStore({

provider: 'pinecone',

indexName: 'my-docs',

});

const docs = await loadDocuments('./data');

for (const doc of docs) {

await store.upsert({

id: doc.id,

vector: await store.embed(doc.text),

metadata: { source: doc.path },

});

}

4‑3. RAG（Retrieval Augmented Generation）実装例

// src/workflows/ragAnswer.ts
import { RetrievalPlugin } from '@mastra/plugins/retrieval';
import { defaultToolkit } from '../toolkit';
import { VectorStore } from '@mastra/vector';

export async function ragAnswer(query: string) {
  const retriever = new RetrievalPlugin({
    store: new VectorStore({ provider: 'pinecone', indexName: 'my-docs' }),
    topK: 5,
  });

  const results = await retriever.search(query);
  const context = results.map(r =&gt; `- ${r.text}`).join('\n');

  const prompt = `
以下の情報を参考に質問に答えてください。
${context}

質問: ${query}
回答:
`;
  return defaultToolkit.run(prompt);
}

// src/workflows/ragAnswer.ts

import { RetrievalPlugin } from '@mastra/plugins/retrieval';

import { defaultToolkit } from '../toolkit';

import { VectorStore } from '@mastra/vector';

export async function ragAnswer(query: string) {

const retriever = new RetrievalPlugin({

store: new VectorStore({ provider: 'pinecone', indexName: 'my-docs' }),

topK: 5,

});

const results = await retriever.search(query);

const context = results.map(r => `- ${r.text}`).join('\n');

const prompt = `

以下の情報を参考に質問に答えてください。

${context}

質問: ${query}

回答:

return defaultToolkit.run(prompt);

}

4‑4. 対話メモリ（Memory）戦略

実装	特徴	推奨シナリオ
In‑Memory (Map)	超高速、プロセス内のみ	単発チャット・開発デバッグ
Redis	TTL 設定可、クラスタ対応	セッション維持・マルチインスタンス
DynamoDB	フルサーバーレス、永続化保証	大規模履歴保存・分析パイプライン連携

Redis メモリ例

// src/memory/redisMemory.ts
import { RedisClient } from '@mastra/redis';

const redis = new RedisClient({ url: process.env.REDIS_URL! });

export async function saveConversation(sessionId: string, message: any) {
  await redis.lpush(`conv:${sessionId}`, JSON.stringify(message));
}

// src/memory/redisMemory.ts

import { RedisClient } from '@mastra/redis';

const redis = new RedisClient({ url: process.env.REDIS_URL! });

export async function saveConversation(sessionId: string, message: any) {

await redis.lpush(`conv:${sessionId}`, JSON.stringify(message));

}

4‑5. Observability（ログ・メトリクス）

// src/observability.ts
import winston from 'winston';
import client from 'prom-client';

export const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [new winston.transports.Console()],
});

export const requestCounter = new client.Counter({
  name: 'mastra_requests_total',
  help: 'Mastra エージェントが処理したリクエスト総数',
});

export const latencyHistogram = new client.Histogram({
  name: 'mastra_request_latency_seconds',
  help: 'リクエストレイテンシ（秒）',
  buckets: [0.1, 0.5, 1, 2, 5],
});

// src/observability.ts

import winston from 'winston';

import client from 'prom-client';

export const logger = winston.createLogger({

level: 'info',

format: winston.format.json(),

transports: [new winston.transports.Console()],

});

export const requestCounter = new client.Counter({

help: 'Mastra エージェントが処理したリクエスト総数',

});

export const latencyHistogram = new client.Histogram({

help: 'リクエストレイテンシ（秒）',

buckets: [0.1, 0.5, 1, 2, 5],

});

各ワークフローの入口で logger.info() と requestCounter.inc()、latencyHistogram.observe(duration) を呼び出すだけで、Prometheus + Grafana に可視化できます。

5. テスト・コンテナ化・本番デプロイパターン

この章では Jest（単体テスト）、Playwright（E2E）、そして Docker 化から Vercel / Cloud Run へのデプロイフロー を実装例とともに示します。CI/CD パイプラインに組み込むことで、品質保証が自動化されます。

5‑1. Jest による Assistants の単体テスト

// src/tests/agents/chatAssistant.test.ts
import { ChatAssistant } from '../../agents/ChatAssistant';
import { providerFactory } from '../../config/providers';

jest.mock('@mastra/openai', () =&gt; ({
  OpenAIProvider: jest.fn().mockImplementation(() =&gt; ({
    generate: jest.fn().mockResolvedValue({ text: 'こんにちは！' }),
  })),
}));

describe('ChatAssistant', () =&gt; {
  it('should return a greeting message', async () =&gt; {
    const assistant = new ChatAssistant();
    const reply = await assistant.handle('挨拶して');
    expect(reply).toBe('こんにちは！');
  });
});

// src/tests/agents/chatAssistant.test.ts

import { ChatAssistant } from '../../agents/ChatAssistant';

import { providerFactory } from '../../config/providers';

jest.mock('@mastra/openai', () => ({

OpenAIProvider: jest.fn().mockImplementation(() => ({

generate: jest.fn().mockResolvedValue({ text: 'こんにちは！' }),

})),

}));

describe('ChatAssistant', () => {

it('should return a greeting message', async () => {

const assistant = new ChatAssistant();

const reply = await assistant.handle('挨拶して');

expect(reply).toBe('こんにちは！');

});

実行コマンド: yarn test（Jest が自動で coverage を生成し、80% 以上を目標にしてください）

5‑2. Playwright によるエンドツーエンドテスト

// src/tests/e2e/workflow.spec.ts
import { test, expect } from '@playwright/test';

test('RAG workflow returns a relevant answer', async ({ page }) =&gt; {
  await page.goto('http://localhost:3000');
  await page.fill('#query-input', 'Mastra の特徴は？');
  await page.click('#submit-btn');
  const answer = await page.textContent('#answer');
  expect(answer).toContain('TypeScriptベースのAIエージェントフレームワーク');
});

// src/tests/e2e/workflow.spec.ts

import { test, expect } from '@playwright/test';

test('RAG workflow returns a relevant answer', async ({ page }) => {

await page.goto('http://localhost:3000');

await page.fill('#query-input', 'Mastra の特徴は？');

await page.click('#submit-btn');

const answer = await page.textContent('#answer');

expect(answer).toContain('TypeScriptベースのAIエージェントフレームワーク');

});

実行: yarn dev でローカルサーバー起動後、npx playwright test を実行。

5‑3. Dockerfile とローカルコンテナ実行

# -------------------------------------------------
# Build Stage
# -------------------------------------------------
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build   # TypeScript を dist に出力

# -------------------------------------------------
# Runtime Stage
# -------------------------------------------------
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
ENV NODE_ENV=production
CMD [&quot;node&quot;, &quot;dist/index.js&quot;]

# -------------------------------------------------

# Build Stage

# -------------------------------------------------

FROM node:20-alpine AS builder

WORKDIR /app

COPY package.json yarn.lock ./

RUN yarn install --frozen-lockfile

COPY . .

RUN yarn build # TypeScript を dist に出力

# -------------------------------------------------

# Runtime Stage

# -------------------------------------------------

FROM node:20-alpine

WORKDIR /app

COPY --from=builder /app/dist ./dist

ENV NODE_ENV=production

CMD ["node", "dist/index.js"]

コンテナ操作例

docker build -t mastra-agent .
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e REDIS_URL=$REDIS_URL \
  mastra-agent

docker build -t mastra-agent .

docker run -p 8080:8080 \

-e OPENAI_API_KEY=$OPENAI_API_KEY \

-e REDIS_URL=$REDIS_URL \

mastra-agent

5‑4. Vercel / Cloud Run デプロイフロー

プラットフォーム	主な手順
Vercel	1. `vercel.json` に `buildCommand: "yarn build"` と `outputDirectory: "dist"` を記載 2. Vercel ダッシュボードで環境変数（シークレット）を登録 3. Git push → 自動デプロイ
Cloud Run	1. 上記 Docker イメージを Cloud Build でビルド (`gcloud builds submit --tag gcr.io/$PROJECT_ID/mastra-agent`) 2. `gcloud run deploy mastra-agent --image gcr.io/$PROJECT_ID/mastra-agent --platform managed --region us-central1 --allow-unauthenticated` 3. 環境変数は `--set-env-vars` か Secret Manager 経由で注入

スケーリング設定例（Cloud Run）

gcloud run services update mastra-agent \
  --max-instances=100 \
  --cpu=2 --memory=4Gi

gcloud run services update mastra-agent \

--max-instances=100 \

--cpu=2 --memory=4Gi

ベストプラクティス：ステートレス設計に徹し、外部永続化（Redis / DynamoDB）だけに状態を依存させることでオートスケールが円滑に機能します。

6. ライセンス・利用規約・法的留意点

6‑1. Mastra 本体のライセンス

MIT License（LICENSE ファイル参照）
商用・非商用を問わず自由に使用、改変、再配布可能です。
ただし、ソフトウェア自体の保証は無く、利用者がリスクを負う旨が明記されています。

6‑2. プロバイダー別ライセンス・利用規約

プロバイダー	主な制限事項
OpenAI	使用量に応じた課金、データ使用ポリシー（ChatGPT API はデータ保持をオプトアウト可能）
Anthropic (Claude)	1 リクエストあたりのトークン上限、商用利用は有料プランが必要
Google Gemini	データは Google のサービス規約に従う（機密情報の送信は注意）
Llama (Meta)	オープンソースモデルだが、商用での再配布には Meta の Model License を遵守

実装時のチェックリスト
1. 各 API キーに対応する利用規約をプロジェクト README に明記。
2. データ保持オプション（例: openai.apiBase の設定）を必要に応じて有効化。
3. 法務部門と連携し、個人情報保護法（GDPR・CCPA 等） に準拠した暗号化・アクセス制御を実装。

6‑3. 本ガイドの著作権

本ドキュメントは クリエイティブ・コモンズ表示 4.0 国際 (CC BY 4.0) の下で公開しています。引用や再配布時は原作者（ChatGPT）とオリジナル URL を明記してください。

7. 総括と次のステップ

本ガイドでは、Mastra フレームワークを用いたエンドツーエンド AI エージェント開発に必要な環境構築・コード実装・テスト・デプロイ・運用までのフローを網羅しました。以下のポイントを再確認してください。

公式情報は常に最新か確認 – npm view @mastra/cli version、GitHub Releases、Mastra Docs を定期的にチェック。
シークレットは Secret Manager に保管しローテーション – 事故防止とコンプライアンス遵守のため必須です。
テストカバレッジ ≥80% と CI に組み込み – 本番リリース前に自動失敗させることで品質を担保。
Observability（ログ・メトリクス）を本番環境で有効化 – 早期障害検知とパフォーマンス最適化の鍵です。
ライセンスと利用規約をプロジェクトに明示 – 法的リスク回避は開発者の基本責務です。

次にやるべきこと

タスク	推奨手順
サンプルリポジトリのクローン	`git clone https://github.com/mastra-ai/mastra-starter.git && cd mastra-starter`
ローカルで起動し、テストを走らせる	`yarn install && yarn dev` → ブラウザで `http://localhost:3000` を確認
本番環境へデプロイ	前述の Vercel または Cloud Run 手順に従い、シークレットだけを差し替えてデプロイ
高度な機能追加	RAG の再検索キャッシュ、マルチエージェント協調、Stream API でリアルタイム応答などを実装

参考書籍：『MastraによるAIエージェント開発・運用実践入門』（技術評論社） – 本ガイドのコード例は本書でも取り上げられています。更なる最適化テクニックやケーススタディを学びたい方はぜひご参照ください。

付録：リンク集

Mastra 公式サイト: https://mastra.ai
CLI リファレンス: https://docs.mastra.ai/cli
GitHub Repository: https://github.com/mastra-ai/mastra
Zenn 記事（実装ガイド）: https://zenn.dev/machamu/articles/mastra-ai-agent-framework
Aigent Lab 完全ガイド（2026 年版）: https://aigentlab.tech/articles/mastra-typescript-ai-agent-framework-complete-guide-2026/
MIT License テンプレート: https://opensource.org/licenses/MIT

本稿は 2026‑06‑21 に最終更新されました。以降のバージョンアップや新機能追加に伴い、内容が変わる可能性がありますので、必ず公式ドキュメントとリリースノートをご確認ください。

スポンサードリンク

-Mastra

comment コメントをキャンセル

: Mastra

Mastra と LangChain の比較：アーキテクチャ・性能・料金徹底解説

本稿では、MastraとLangChainの基本アーキテクチャから実装体験、ベンチマーク結果、エコシステム、料金体系まで徹底比較し、ユースケース別の適合性を示します。

: Mastra

Mastra StudioでAIエージェント開発｜既存プロジェクトとの連携ガイド

Mastra StudioはJavaScript/TypeScriptを活用したAIエージェント開発環境で、既存プロジェクトとの連携が可能です。導入手順やGitHubリポジトリ解析の実装例も紹介。

Progateの就職支援サービスと2025年の企業提携情報 | 実績データあり

AxumアプリのDocker化ガイド: RustとDocker Composeで最適化

Mastra AIエージェント開発手順【2026年最新マルチLLM・RAG】

1. 開発環境の準備と Mastra CLI のインストール

1‑1. Node.js とパッケージマネージャ (npm / Yarn) のセットアップ

Yarn のインストール（任意）

1‑2. TypeScript プロジェクトの初期化

推奨 tsconfig.json 設定

1‑3. Mastra CLI のインストール（グローバル vs ローカル）

1‑3‑a. グローバルインストール（推奨バージョン確認付き）

1‑3‑b. プロジェクトごとのローカルインストール

1‑4. 公式ドキュメントと外部リソースへのリンク集

2. Mastra プロジェクトの作成とディレクトリ構造

2‑1. mastra init によるプロジェクト雛形生成

生成結果（概要）

2‑2. 各ディレクトリの役割とベストプラクティス

3. マルチ LLM プロバイダー設定と Assistants の実装

3‑1. プロバイダー設定ファイル (src/config/providers.ts)

3‑2. 安全なシークレット管理

Secret Loader の実装例

3‑3. Assistants の実装例

(a) クラスベース（汎用チャット）

(b) 関数ベース（軽量ユースケース）

4. ワークフロー、RAG／Memory／Observability の構築

4‑1. Toolkit と Plugins の組み立て

4‑2. ベクトルストア選定とインデックス作成

インデックス作成サンプル（Pinecone）

4‑3. RAG（Retrieval Augmented Generation）実装例

4‑4. 対話メモリ（Memory）戦略

Redis メモリ例

4‑5. Observability（ログ・メトリクス）

5. テスト・コンテナ化・本番デプロイパターン

5‑1. Jest による Assistants の単体テスト

5‑2. Playwright によるエンドツーエンドテスト

5‑3. Dockerfile とローカルコンテナ実行

コンテナ操作例

5‑4. Vercel / Cloud Run デプロイフロー

スケーリング設定例（Cloud Run）

6. ライセンス・利用規約・法的留意点

6‑1. Mastra 本体のライセンス

6‑2. プロバイダー別ライセンス・利用規約

6‑3. 本ガイドの著作権

7. 総括と次のステップ

次にやるべきこと

付録：リンク集

推奨 `tsconfig.json` 設定

2‑1. `mastra init` によるプロジェクト雛形生成

3‑1. プロバイダー設定ファイル (`src/config/providers.ts`)