はじめに
本ハンズオンでは、AIエージェントフレームワークのMastraを使って、シンプルなAIエージェントの実装を解説します。
Claude CodeやDevinのようなコーディングエージェントを使っていると、「AIエージェント = 難しい」と捉えがちかと思います。ですが実際は、今まで培ったWebアプリの開発知識とスキルがあれば、AIエージェントの開発は誰でも気軽に始めることができます！
本ハンズオンをきっかけに、AIエージェントの開発に一歩踏み出す方が増えれば幸いです☺️
ハンズオンのステップ
- 【本記事で解説】MastraのサンプルAIエージェントをVercelにデプロイし、curlコマンドで実行する
- サンプルAIエージェントにチャットUIを実装し、Vercelにデプロイする
- サンプルAIエージェントを改造し、複数のToolを自律的に実行するAIエージェントを実装する
事前に準備が必要なもの
- Node.js(
v20.0以上) - サポート対象のモデルプロバイダー[1]のAPIキー
- 本記事では、OpenAIのAPIキーを利用します
0. 前提知識
AIエージェントとは？
OpenAIが2025年4月に公開した資料によれば[2]、AIエージェントとは「ユーザーに代わってタスクを自律的に遂行するシステム」のことを指します。
AIエージェントが持つ特性は、定義の観点をどこに置くかで大きく異なります。
-
技術的定義
「自然言語によってタスクを指示でき、LLMが推論・計画し、必要に応じてツールを呼び出して実世界の行動を実行できるシステム」 -
アーキテクチャ的定義
「LLMを推論エンジン、ツールを実行器(Executor)、メモリを文脈維持機構とするエージェントアーキテクチャ」 -
概念的定義
「自然言語を入出力とし、外界とのインタラクションを通じて目標達成を図る人工知能的存在」
アーキテクチャ的定義に則れば、AIエージェントは「LLM単体」ではなく、「LLMを中核とした複合知的システム」として扱われれますし、概念的定義によれば"思考し、決定し、行動する"存在であることが重要になり、ルールベースのチャットボットはAIエージェントには当てはまらないシステムとなります。
まとめると、AIエージェントとは、LLMが中心となって、記憶・ツール・推論を統合し、人間の指示を理解して実世界のタスクを遂行する「自律的な知的ソフトウェア」 だと言えます。
AIエージェントに必要な要素[3]
AIエージェントは、以下の3つの構成要素から成り立ちます。
| 要素 | |
|---|---|
| 🧠 モデル (Model) | 推論と意思決定を担うLLM |
| 🔧 ツール (Tools) | エージェントがアクションを実行するために使用する外部関数やAPI |
| 📝 指示 (Instructions) | エージェントの振る舞いを定める明確なガイドラインとガードレール |
AIエージェントの動作を表すフローチャート
これは僕の見解ですが、システムとしての動作仕様がプロンプトで定義される特徴があることから、AIエージェントは 「業務ロジックが自然言語で表現され、ワークフローを自律的に実行するアプリケーション」 とも言えるでしょう。
Mastraとは？
Mastraは、LLMを組み込んだアプリケーションとエージェントを構築するためのTypeScript製フレームワークです。Gatsbyの開発チームによって開発がスタートし、2年先行していたLangGraph(Python版)のGitHubスター数を一時追い抜く[4]など、2025年に入ってから急成長を遂げています。
主な特徴は、以下の通りです。[5]
| 特徴 | |
|---|---|
| 🤖 モデルルーティング (Model Routing) |
OpenAI、Anthropic、Geminiなど40以上のAIモデルプロバイダーに標準インターフェースで接続可能。 |
| 🕶️ エージェント (Agents) |
LLMとツールを使用する自律的なエージェントを構築。目標に対して推論し、ツールを選択し、タスクを完了するまで反復処理を実行。 |
| 💼 ワークフロー (Workflows) |
複雑な複数ステップのプロセスに対応したグラフベースのワークフローエンジン。.then()、.branch()、.parallel()などの制御フローメソッドをサポート。 |
| 👍️ 人による承認・入力 (Human-in-the-loop) |
エージェント/ワークフローを一時停止してユーザー入力を待機可能。状態ストレージを使用して実行の一時停止と再開が可能。 |
| 📀 コンテキスト管理 (Context Management) |
会話履歴の提供、さまざまなソース (API、データベース、ファイル)からのデータ取得、一貫したエージェント動作のためのワーキングメモリとセマンティックメモリの追加が可能。 |
| 🫂 統合 (Integrations) |
React、Next.js、Node.jsと互換性あり。スタンドアロンエンドポイントとしてのデプロイが可能。エージェンティックUIライブラリとの統合をサポート。 |
| ✨️ 本番環境に不可欠な要素 (Production Essentials) |
組み込みの品質評価と監視ツールにより、エージェントの継続的な測定と改善が可能。 |
単にエージェントやワークフローの構築にとどまらず、品質評価や監視系のツールまで組み込まれており、「プロトタイピングから製品版の開発まで、必要な機能は一通り揃っている」と公式ドキュメントでは謳われています。
多機能さ故に、どこから手をつけるべきか迷ってしまうでしょうが、シンプルなエージェントの開発に絞るのであれば、「エージェント」「ワークフロー」「統合」の3機能だけ意識すればOKです。
さて、大まかな前提知識はインプットできたでしょうか？
ここからいよいよ、Mastraを使ったAIエージェントの構築へと入ります🔥
1. サンプルのエージェントを立ち上げる
1-1. create mastraコマンドを実行する
npm create mastra@latest
対話形式でプロジェクトの設定が進むため、順番に答えて行きます。
実行ログ
~ % npm create mastra@latest
Need to install the following packages:
create-mastra@0.17.0
Ok to proceed? (y) y
> npx
> "create-mastra"
┌ Mastra Create
│
◇ What do you want to name your project?
│ mastra-sample
│
◇ Where should we create the Mastra files? (default: src/)
│ src/
│
◇ Select a default provider:
│ OpenAI
│
◇ Enter your OpenAI API key?
│ Enter API key
│
◇ Enter your API key:
│ sk-proj-xxx
│
◇ Make your IDE into a Mastra expert? (Installs Mastra's MCP server)
│ Skip for now
│
◇ Project structure created
│
◇ npm dependencies installed
│
◇ Mastra CLI installed
│
◇ Mastra dependencies installed
│
◇ .gitignore added
│
└ Project created successfully
│
◑ Initializing Mastra
up to date in 566ms
◇
│
◇ ───────────────────────────────────────╮
│ │
│ │
│ Mastra initialized successfully! │
│ │
│ │
├──────────────────────────────────────────╯
│
└
To start your project:
cd mastra-sample
npm run dev
作成されたmastra-sample以下のディレクトリ構成は、以下のようになります。
├── .env
├── .gitignore
├── node_modules
├── package-lock.json
├── package.json
├── src
│ └── mastra
│ ├── agents
│ │ └── weather-agent.ts
│ ├── index.ts
│ ├── tools
│ │ └── weather-tool.ts
│ └── workflows
│ └── weather-workflow.ts
└── tsconfig.json
1-2. Mastraのローカル開発サーバーを立ち上げる
npm run devを実行すると、Mastraのローカル開発サーバーが立ち上がります。
http://localhost:4111/にアクセスしてみましょう。以下のようなPlaygroundが開きます。
サンプルで作成されるのは、地名を伝えると現在の天気の情報を返してくれるエージェントです。
1-3. GitHubにレポジトリを作成し、push
Vercelへのデプロイがしやすくなるので、GitHubレポジトリを作ってpushしておきましょう。
諸々面倒なので、全部Claude Codeにやらせていく😋
2. サンプルのエージェントをVercelにデプロイする
2-1. コンテキスト永続化のコードを削除
Vercelはサーバーレスなプラットフォームであるため、ローカルファイルシステムにデータを書き込むLibSQLストアに対応していません。該当のコードを削除し、無効化しておきましょう。
@@ -1,17 +1,12 @@
export const mastra = new Mastra({
workflows: { weatherWorkflow },
agents: { weatherAgent },
- storage: new LibSQLStore({
- // stores observability, scores, ... into memory storage, if it needs to persist, change to file:../mastra.db
- url: ":memory:",
- }),
logger: new PinoLogger({
name: 'Mastra',
level: 'info',
@@ -21,9 +19,4 @@
export const weatherAgent = new Agent({
// ..
model: 'openai/gpt-4o-mini',
tools: { weatherTool },
- memory: new Memory({
- storage: new LibSQLStore({
- url: 'file:../mastra.db', // path is relative to the .mastra/output directory
- }),
- }),
});
2-2. VercelDeployerの追加
Mastraには、Vercelへのデプロイを簡単に設定し、処理するパッケージが用意されています。
インストールして、Mastraの設定に登録しましょう。
npm install @mastra/deployer-vercel@latest
@@ -1,12 +1,14 @@
import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
+import { VercelDeployer } from '@mastra/deployer-vercel';
import { weatherWorkflow } from './workflows/weather-workflow';
import { weatherAgent } from './agents/weather-agent';
export const mastra = new Mastra({
workflows: { weatherWorkflow },
agents: { weatherAgent },
+ deployer: new VercelDeployer(),
logger: new PinoLogger({
name: 'Mastra',
level: 'info',
2-3. Vercelにデプロイ
いよいよ、Vercelへのデプロイを実行します！
vercel.com/newから、VercelのGitHub Appにレポジトリへのアクセス許可を与え、「import」ボタンから、ビルドとデプロイの設定画面に進みます。
vercel.com/new にデプロイしたいレポジトリが表示されればOK
以下2つ設定し、「Deploy」ボタンを押すとデプロイ作業が始まります。
-
Buid Command:
npm run build -
Enviroment Variables:
OPENAI_API_KEYを登録 ※.envのアップロードで自動設定できます
「Congratulations!」が出たら、デプロイ完了です！
2-4. 動作確認
curlコマンドを使って、動作確認をしてみましょう！
curl -X POST https://xxx.vercel.app/api/agents/weatherAgent/generate \
-H "Content-Type: application/json" \
-d '{
"messages": "東京の天気を教えて"
}' | jq
現在の東京の天気情報が返ってくればOKです！お疲れ様でした🥳
{
"text": "東京の現在の天気は以下の通りです：\n\n- **気温**: 18.9°C（体感温度: 19.6°C）\n- **湿度**: 76%\n- **風速**: 5.4 m/s（最大風速: 20.9 m/s）\n- **天候**: 部分的に曇り\n\n何か特別な活動を計画していますか？それに基づいて提案できますよ。",
"usage": {
...
トラブルシューティング
ビルドコマンドが失敗してしまう
- LibSQL関連のコード削除を忘れていないか、チェックしましょう。
- Mastraは更新が激しいフレームワークのため、依存パッケージのバージョン不整合が発生しやすいです。
@mastra/xxxのバージョンを確認しましょう。
Could not find API keyというエラーが返ってきてしまう
{
"error": "Could not find API key process.env.OPENAI_API_KEY for model id openai/gpt-4o-mini"
}
- APIキーの環境変数への設定が漏れてしまっています。Vercelの設定画面に転記した後、Redeployの実行が必要になるため、忘れないようにしましょう。
環境変数を修正すると、Redeployを勧めてくれます
まとめ
create mastraコマンドで作成したサンプルAIエージェントをVercelにデプロイすることができました！
ですがこのままでは、コマンドライン上でしかリクエストを送ることができません。次の記事では、チャットUIを持つAIエージェントを構築し、Vercelにデプロイするところまで解説します👊
【次回】Mastraを使ってAIエージェントを作ろう！ - 基礎編(2) -
参考リンク
-
A practical guide to building agents
※日本語版はこちら - Mastra公式ドキュメント
- Mastra GitHub
- From Local to Live: Deploying Mastra Agents to Vercel with Basic Authentication | by David Sam | Medium
レポジトリはこちら
-
Mastraが対応しているモデルプロバイダーは、以下の3つに大別されます。
・ AI SDKチームがメンテナンスする公式プロバイダー
・ OpenAI互換プロバイダー
・ コミュニティプロバイダー ↩︎ -
A practical guide to building agents - What is an agent? より。 ↩︎
-
A practical guide to building agents - Agent design foundations より。 ↩︎
-
Sam Bhagwat(Mastra CEO)のLinkedin投稿より。
なお、2025/10/19時点では、LangGraphのスター数の方が多い(Mastra: 17,551 / LangGraph: 19,933)。 ↩︎
Discussion