Mastra 使い方｜AIエージェントを作る手順を解説【2026】

01Mastraとは？何ができるフレームワークか

Mastra（マストラ）は、TypeScriptでAIエージェントを構築するためのオープンソースフレームワークです。公式は「素早く試作し、自信を持って本番投入する」ことを掲げており、エージェント開発でよく必要になる部品を最初からまとめて提供します。JavaScript／TypeScriptの資産をそのまま活かせるため、フロントエンドやNode.jsの開発に慣れている人と相性が良い作りです。

用意されている中核の部品は、対話や判断を担うAgents（エージェント）、外部の処理を呼び出すTools（ツール）、複数ステップを定義するWorkflows（ワークフロー）、検索連携のRAG、会話の状態を保持するMemory、そして品質を測るEvalsです。これらを一つの枠組みの中で組み合わせられるので、「LLMを呼ぶ処理」と「その前後の実処理」を別々のライブラリでつなぐ手間が減ります。

エージェントの呼び出し方は2通りあります。開発サーバーが生成するREST APIエンドポイント経由と、Node.jsのコード内からmastra.getAgent()で直接呼ぶ方法です。Webアプリの一部に組み込むことも、バッチ処理から呼ぶこともできる設計になっています。AIモデル同士をつなぐ標準規格についてはMCP（Model Context Protocol）の解説もあわせて読むと、ツール接続の全体像が掴みやすくなります。

02Mastraの使い方｜インストールと初期設定の手順

導入は雛形の生成から始めます。ターミナルで次のコマンドを実行すると、対話形式のセットアップが立ち上がります。npm以外にpnpm・Yarn・Bunでも同等のコマンドが用意されています。

npm create mastra@latest

ウィザードでは、プロジェクト名、入れる部品（Agents／Tools／Workflowsから選択）、既定で使うLLMプロバイダ、そしてサンプルコードを含めるかどうかを聞かれます。最初は迷わずサンプルコードを含める選択にしておくと、動く状態の雛形が手に入るため、そこから読み解くのが近道です。既定プロバイダはあとから変更できるので、手元にあるAPIキーに合わせて選べば問題ありません。

生成が終わったらプロジェクトに移動し、依存をインストールします。初回はモデルへ接続するためのAPIキーを環境変数に置きます。使うプロバイダに応じて、OPENAI_API_KEY・ANTHROPIC_API_KEY・GOOGLE_API_KEYのいずれかを.envに記述します。キーは必ず環境変数で渡し、公開リポジトリには置かないでください。

# .env の例
ANTHROPIC_API_KEY=発行したAPIキー

03Mastraでエージェントを作る方法

エージェントはAgentクラスのインスタンスとして定義します。渡す設定は主に4つで、識別名のname、振る舞いを決めるシステム指示のinstructions、使うモデルを指すmodel、そして呼び出せる関数群のtoolsです。次は問い合わせ内容を分類するエージェントの最小例です。

import { Agent } from "@mastra/core/agent";

export const supportAgent = new Agent({
  name: "support-agent",
  instructions: "あなたは問い合わせ内容を分類する担当です。返答は日本語で簡潔に、カテゴリ名だけを返してください。",
  model: "anthropic/claude-sonnet-5",
});

instructionsは、そのエージェントの性格と出力の形を決める最も重要な部分です。曖昧に書くと出力もぶれるため、「何を」「どの言語で」「どの形式で」返すかまで書き切るのが安定させるコツです。定義したエージェントは、Mastra本体に登録してから呼び出します。

import { Mastra } from "@mastra/core";
import { supportAgent } from "./agents/support";

export const mastra = new Mastra({
  agents: { supportAgent },
});

// 呼び出し
const agent = mastra.getAgent("supportAgent");
const res = await agent.generate("領収書を再発行してほしいという問い合わせ");
console.log(res.text);

04Mastraでツールを作り外部APIをつなぐ方法

エージェントに「調べる」「登録する」といった実処理をさせたいときは、Toolsを定義してtoolsに渡します。ツールはcreateToolで作り、入力と出力のスキーマをzodで宣言します。スキーマを明示することで、モデルが引数を正しい形で渡しやすくなります。

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const fetchInquiries = createTool({
  id: "fetch-inquiries",
  description: "指定日の問い合わせ一覧を取得する",
  inputSchema: z.object({ date: z.string() }),
  outputSchema: z.object({ items: z.array(z.string()) }),
  execute: async ({ context }) => {
    // ここで実際のDB/APIから取得する
    const items = await loadFromDb(context.date);
    return { items };
  },
});

あとはエージェント定義のtoolsにこのツールを渡すだけです。モデルはdescriptionを手がかりに「今このツールを呼ぶべきか」を判断し、必要なときだけexecuteを実行します。外部APIの呼び出し、社内DBの参照、ファイルの書き出しなど、TypeScriptで書ける処理はそのままツールにできます。

05開発サーバーとプレイグラウンドの使い方

書いたエージェントは、開発サーバーを立てればすぐ試せます。プロジェクト直下で次を実行します。

npm run dev

既定ではポート4111でサーバーが起動し、ブラウザでhttp://localhost:4111を開くとプレイグラウンドが表示されます。ここでエージェントを選び、チャット形式で入力を送ると、応答とツールの呼び出し履歴を目で確認できます。同時にエージェントごとのREST APIエンドポイントも生成されるため、フロントエンドや別プロセスからfetchで叩いて組み込み動作を試すこともできます。最初のうちは、プレイグラウンドでinstructionsを調整しながら出力の当たり方を確かめるのが、遠回りに見えて確実な進め方です。

06Mastraでモデルを切り替える方法（OpenAI・Anthropic・Google）

使うモデルは、modelに「プロバイダ／モデル名」の文字列を渡すだけで切り替わります。別途SDKを差し込む必要はなく、Mastra内蔵のモデルルーターがプロバイダとの接続を引き受けます。例えば次のように書きます。

// OpenAIを使う場合
model: "openai/gpt-5.5",
// Anthropicを使う場合
model: "anthropic/claude-sonnet-5",
// Googleを使う場合
model: "google/gemini-3-6-flash",

切り替えに必要なのは、対応する環境変数（OPENAI_API_KEYなど）を用意することだけです。同じエージェントのコードのまま、コスト重視のモデルと品質重視のモデルを入れ替えて比較できるため、案件ごとに最適なモデルを選ぶ検証がしやすくなります。国内向けの構築では、日本語の指示の通りやすさでanthropic/claude-sonnet-5のようなモデルを起点に、コストと速度で調整していくのが現実的です。各モデルの位置づけはClaude Opus 5の解説も参考になります。

07Mastraは自前実装や既存フレームワークと何が違う？

違いは、エージェント開発に必要な部品が一つの枠組みに揃っている点です。LLMのAPIを直接叩く自前実装だと、ツール呼び出しの制御、状態の保持、評価の仕組みを自分で組む必要があります。Mastraはそれらを共通の作法で扱えるようにしています。編集部が主要な観点で差分を整理すると次のようになります。

この差から、開発のアウトプットは「動く試作までの時間」と「モデル差し替えの検証量」で変わると想定されます。仕様上、接続やUIの下ごしらえが省ける分、同じ工数でも試せる案数が増える方向だと考えられます。これは公式が示す構成から導いた想定で、案件の規模や要件によって効果の出方は変わります。

08サイト制作・自社ツール開発でMastraをどう使うか

制作会社の実務でMastraがはまりやすいのは、繰り返し発生する判断作業を小さなエージェントに任せる使い方です。例として、サイトの問い合わせフォームに届いた内容を分類し、担当を振り分ける社内ツールを考えます。分類エージェントに取得ツールを持たせ、次のように組みます。

import { Agent } from "@mastra/core/agent";
import { fetchInquiries } from "../tools/fetch-inquiries";

export const triageAgent = new Agent({
  name: "triage-agent",
  instructions: [
    "問い合わせを次の4分類のいずれかに振り分けます：",
    "見積もり / 不具合 / 保守 / その他。",
    "分類名と、担当チーム名だけをJSONで返してください。",
  ].join("\n"),
  model: "anthropic/claude-sonnet-5",
  tools: { fetchInquiries },
});

これをスケジュール実行に載せれば、毎朝の問い合わせを自動で仕分けし、結果を社内チャットへ流す運用が組めます。同じ発想で、LP改善の壁打ち相手（ファーストビューの文言案を複数出させる）、記事の内部リンク候補の抽出、フォーム入力のバリデーション補助など、これまで人が目視でやっていた判断を部分的に肩代わりさせられます。

サイト制作そのものに使うなら、既存ページのHTMLを渡して「見出し構造の問題点を指摘して」と分類・指摘させるツール化が向きます。作ったエージェントはREST経由で社内ダッシュボードから叩けるため、非エンジニアのメンバーでもボタン一つで実行できる形にまとめられます。認証情報は環境変数に置き、対象データに個人情報が含まれる場合は匿名化してから渡す運用にしてください。

09Mastraの料金とデプロイ先

Mastra自体はオープンソースのフレームワークのため、フレームワークの利用に費用はかかりません。実際に発生するのは、エージェントが呼び出すLLMのAPI利用料です。つまりコストは、選んだモデル（OpenAI・Anthropic・Googleなど）の従量課金に依存します。検証段階では安価なモデルで組み、本番で品質重視のモデルへ差し替える進め方だと、無駄な出費を抑えやすくなります。

作ったエージェントは、Node.jsが動く環境にデプロイして公開します。REST APIとして動くため、一般的なサーバーレス基盤やコンテナ環境に載せられます。まずはローカルのプレイグラウンドで固めてから、小さく公開して実データで様子を見るのが安全な順序です。

10Mastraのよくある質問

11まとめ｜Mastraを試すかの判断基準

Mastraを採用するかは、「チームがTypeScript／Node.jsで動けるか」で判断すると分かりやすくなります。その条件を満たすなら、npm create mastra@latestで雛形を作り、プレイグラウンドで小さなエージェントを一つ動かすところまでを最初の一歩にするのが失敗しにくい進め方です。まずは分類や要約のような判断作業を1件だけ任せてみて、出力の安定度を手元で確かめてから用途を広げるのがおすすめです。

モデルの選び方はClaude Opus 5の解説、ツール接続の標準規格についてはMCPの解説でまとめています。エージェント開発の土台を整えたい方はあわせて参照してください。

12出典