Mastra入門 - TypeScriptで作るAIエージェント

2022年にChatGPTが登場して以来、AIを活用したツールやアプリが世界的に注目されています。ChatGPTをはじめとしたチャットベースのアプリだけでなく、Claude CodeやGitHub Copilot、Codexなどのコーディングエージェントを活用している方も多いのではないでしょうか？

ChatGPTのおかげですっかり浸透したAIアプリですが、作るためのフレームワークも日々進歩しています。この記事では、TypeScriptでAIエージェントを作れるフレームワーク「Mastraマストラ」を紹介します。

MastraにはAIエージェントを作るための便利な機能があります。次の動画のようなAIエージェントが意外と簡単に作れるのでぜひ体験してみてください！

▼Mastraの機能の1つであるMastra Studioの画面です。Mastra自体にはUI構築のための機能はありませんが、開発・テスト用のGUIとしてMastra Studioが提供されています。

AIエージェントとは何か

まずはAIエージェントについておさらいしましょう。AIエージェントとは、ユーザーからの入力を受け取って、自律的にタスクを実行するAIシステムのことです。

AIエージェントの一種であるコーディングエージェントを例に説明します。

コーディングエージェントは、ユーザーから「このページにログインボタンを追加して」といった入力を受け取り、

入力を解釈してタスクに落とし込む
コードベースを調査し、CSSの命名ルールやHTMLの構造などを解析する
命名ルールや構造に沿ったコードを生成する
リンターやテストを実行する
ユーザーに完了した内容をフィードバックする

といった作業を自律的に行います。

なぜAIエージェントを作るのか？

ChatGPTのような汎用的なチャットAIでもある程度のことは可能です。しかし、そのままでは物足りない場合があります。たとえばインターネット等に公開されていない特定の知識や、特定のフローにもとづいたタスクなどをAIエージェントに行わせたい場合です。以下のような問題があります。

AIの知らない知識がある

AIはインターネット等で公開されていない知識を知りません。これはAIエージェントを動かすもとになるLLM（大規模言語モデル）の知識の制約によるものです。LLMは大量のデータを学習していますが、公開されているものに限ります。

また、ナレッジカットオフと呼ばれる制約もあります。モデルの学習はある時点で終了するため、そのあとの知識は知らないというものです。OpenAIの公式サイトによると、GPT-5.4はナレッジカットオフが2025年8月31日とあります（2026年3月12日時点の情報です）。

そのため、AIの学習に含まれない知識は自分であたえなければなりません。

AIに判断を任せられない

AIエージェントは自律的にタスクをこなすと説明しました。逆にいえば、AIの判断でよしなにタスクをこなします。

その際、AIの判断に完全に任せられない場合もあります。Aという処理の後に必ず人間の確認をはさみたい、Bという処理の前には別のデータベースを参照したい、処理のログを残したい、などです。その場合はフローを制御する必要があります。AIに判断を任せたままだと、このフローをスキップする可能性があります。

特定のユースケースに合わせた知識をあたえ、フローを制御できるのがAIエージェントを作るメリットです。

ICSでの活用事例

ICS社内では、Mastraで作成した「AI編集長」というエージェントを活用しています。 その名の通り、ICS MEDIAの編集長として記事の執筆をサポートしてくれます。

ICSの記事執筆に関するノウハウをAIに学習させ、Slack上で動作するチャットボットとして利用しています。

Mastraでエージェントを作ってみよう

では、さっそくAIエージェントを作ってみましょう。

MastraはNode.jsで動くフレームワークで、AIエージェントやアプリケーションを作る際に必要な機能がまとまっています。Node.js上で動くため、通常はUIを用意しないと画面での動作確認はできません。しかし、冒頭でも紹介したMastra Studioを起動するとGUIから作成したエージェントをすぐに試せます。

今回の記事でもAIエージェントの動きはMastra Studio上で確認します。

1. モデルのAPI keyを取得する

AIエージェントを作るには、AIモデルと連携する必要があります。AIモデルにはOpenAIのGPT、AnthropicのClaudeクロード、GoogleのGeminiジェミニなど各社がさまざまなものを公開しています。

Googleが提供しているAPIには無料枠があるので、今回はGoogleのGeminiを使ってみましょう。

Google AI Studioにアクセスする
[Get API key]ボタンを押す
デフォルトのAPI keyがあるので右側の[Copy API key]ボタンを押す
表示されたAPI keyをメモする

注意: API keyは絶対に公開しないようにしましょう！

API key取得手順

2. Mastraプロジェクトを作る

お好きなディレクトリ上で次のコマンドを実行し、Mastraプロジェクトを作成します。

npm create mastra@latest

※この記事ではパッケージマネージャーとしてnpmを使用します。お好きなマネージャーを使用して構いません。
※記事公開時点では、最新バージョンはv1.3.7です。以降の記載はこのバージョンでの挙動です。

いくつか質問されるので答えていきます。

What do you want to name your project? → 好きな名前でOK
Where should we create the Mastra files? → とくに希望がなければデフォルトのsrc/を指定
Select a default provider: → 1. でGoogleのAPIを取得したので「Google」を選択
Enter your Google API key? → Enter API keyを選択
Enter your API key: → 1. でメモしたAPI keyを入力
Configure Mastra tooling for agents? → とくに希望がなければrecommendedの「Skills」を選択
Select agent(s) to install skills for → お好きなエージェントを選択
Initialize a new git repository? → Gitで管理するなら「Yes」を選択

プロジェクトの作成が完了しました。

プロジェクト内の.envファイルには先ほど入力したAPI keyが含まれています。デフォルトで.envは.gitignoreに記載されているため、とくに変更しなければ公開される心配はありませんが、API keyが意図せず公開されないように.envのあつかいは気をつけましょう！

3. すでにある天気エージェントのモデルを変更する

Mastraのプロジェクトにはサンプルの天気エージェントが実装されています。デフォルトではOpenAIのモデルが使われているので、GoogleのGeminiに変更します。

src/mastra/agents/weather-agent.tsを開く
modelを'google/gemini-2.5-flash'に変更する

▼weather-agent.ts

model: 'google/gemini-2.5-flash',

モデルの変更

4. 天気エージェントを動かしてみる

エージェントを動かしてみましょう。次のコマンドを実行します。

npm run dev

http://localhost:4111にアクセスするとMastra Studioが起動します。この画面では作成したエージェントやそのほかの機能をすぐに実行できます。

エージェントを実行するには左のメニューバーから[Agents]をクリックし、[Weather Agent]（すでにある天気エージェント）を選択します。チャット欄が表示されるので、好きな地名を入力してみましょう。

地名を入力すると天気を取得して回答してくれます。

5. プロンプトを変更してみる

プロンプトを変更してみましょう。weather-agent.tsのinstructionsと書いてあるところに英語でプロンプトが書かれています。

▼weather-agent.ts

You are a helpful weather assistant that provides accurate weather information and can help planning activities based on the weather.

  Your primary function is to help users get weather details for specific locations. When responding:
  - Always ask for a location if none is provided
  - If the location name isn't in English, please translate it（以下略）

日本語訳:

あなたはお天気アシスタントです。正確な天気の情報に加え、その天気に適したアクティビティを答えます。
ユーザーからの情報がなければ必ず地名を聞くこと
地名が英語でなければ翻訳すること（以下略）

ChatGPTなどのように、自然言語で書かれた指示を変更するだけで、自分好みのエージェントにカスタマイズできます。

回答は日本語で行うこと
その地域の観光名所を3つあげること

を指示に追加してみましょう。

▼weather-agent.ts

// 省略
- If the user asks for activities, respond in the format they request.
- 回答は必ず日本語で行ってください。 //✨これを追加
- 回答にはその地域の観光名所を3つあげてください。 //✨これを追加

Use the weatherTool to fetch current weather data.

Mastra Studioで実行すると、回答が日本語になり、観光名所が追加されました。

Mastraではこのように簡単にAIエージェントを構築できます。