「AI エージェントを業務システムに組み込みたいが、Python に書き直す予算はない」── これは TypeScript / Node.js で構築された業務システムを抱える企業の典型的な悩みです。LangChain・LlamaIndex を中心とする Python エコシステムを採用すると、既存システムとの言語境界が運用コストになる。
この問題に正面から答えるのが Mastra です。2026 年 4 月、gihyo.jp で「AI エージェントを作ってみよう ～ Mastra を使って」の連載が始まり、TypeScript 系受託の現場で一気に注目度が上がりました。本記事では、受託で採用するときの実装パターンを整理します。
Mastra の構成 ─ 4 つの柱
Mastra は以下の 4 つの機能を 1 つの SDK にまとめている、というのが最大の特徴です。
| 機能 | Mastra での扱い |
|---|---|
| Workflow | ステートマシン的にステップを定義（条件分岐・並列・リトライ込み） |
| Agent | LLM + ツール + メモリの組み合わせを宣言的に定義 |
| RAG | ベクトル DB へのインデックス・検索のヘルパー |
| Eval | エージェント・ワークフローの自動評価（精度・コスト・レイテンシ） |
LangGraph + LangSmith + LlamaIndex を別々に組む構成と比べると、SDK が 1 つにまとまっているので学習コストが圧倒的に低いのが受託でありがたいポイントです。
受託案件で使う基本パターン
Agent 定義の最小構成
import { Agent } from '@mastra/core';
import { openai } from '@ai-sdk/openai';
export const supportAgent = new Agent({
name: 'support-agent',
instructions: `
あなたは弊社のカスタマーサポートエージェントです。
顧客の問い合わせを受け、CRM・配送 API を呼び出して応答します。
破壊的操作は禁止し、必要なら人間に引き継いでください。
`,
model: openai('gpt-5.5'),
tools: { lookupCustomer, checkShipping, createTicket },
memory: new RedisMemory({ url: process.env.REDIS_URL }),
});ポイントは instructions に「やってよいこと」「やってはいけないこと」を明示することです。受託案件のガードレール記事 で書いた通り、システムプロンプトレベルでの制約は最低限の防衛線として有効です。
Workflow でビジネスフローを表現
Agent 単体では捌けない業務フローは、Workflow で組みます。
import { Workflow, Step } from '@mastra/core';
export const orderCancellation = new Workflow({
name: 'order-cancellation',
triggerSchema: z.object({ orderId: z.string() }),
})
.step(new Step({
id: 'fetch',
execute: async ({ data }) => fetchOrder(data.orderId),
}))
.step(new Step({
id: 'validate',
execute: async ({ context }) => {
if (context.fetch.status === 'shipped') {
throw new Error('Already shipped');
}
},
}))
.step(new Step({
id: 'cancel',
execute: async ({ context }) => cancelOrder(context.fetch.id),
}))
.step(new Step({
id: 'notify',
execute: async ({ context }) => notifyCustomer(context.fetch.email),
}))
.commit();ステップ単位で リトライ・タイムアウト・並列実行 が宣言的に書けるため、業務システムのワークフロー定義としても無理がありません。受託で「業務フロー図そのまま実装してください」という要件が出ても、図と Workflow がほぼ 1:1 対応します。
既存 Node.js 業務システムへの組み込み
Mastra は Node.js 18+ で動く純粋な TypeScript ライブラリとして設計されており、Express / NestJS / Fastify などの既存サーバーに後付けできます。
// Express の既存ルーターに Mastra Agent を差し込む例
app.post('/api/support/chat', async (req, res) => {
const result = await supportAgent.generate({
messages: req.body.messages,
threadId: req.user.id,
});
res.json(result);
});Python ベースの LangChain だと、別プロセス・別コンテナで FastAPI を立てて internal API として呼び出す構成になりがちですが、Mastra なら同一プロセス内で完結します。これは中小企業の業務システム改修で大きなメリットです。
RAG パイプラインの組み込み
社内ナレッジを取り込む RAG も Mastra 内で完結します。
import { MastraVector } from '@mastra/core';
import { pineconeStore } from '@mastra/pinecone';
const vector = new MastraVector({
store: pineconeStore({ apiKey: process.env.PINECONE_KEY, index: 'kb' }),
embeddings: openai.embedding('text-embedding-3-large'),
});
await vector.upsert([
{ id: 'doc-1', text: '..., metadata: { source: 'manual.pdf' } },
]);
// Agent で参照
export const supportAgent = new Agent({
// ...
tools: { searchKnowledge: vector.tool('searchKnowledge') },
});マルチモーダル埋め込みリランカーの記事 で触れた通り、RAG は「埋め込み + リランク + 引用」の 3 段構成が事実上の標準ですが、Mastra ではリランクをカスタムツールとして挿入できます。
Eval ─ 受託で「品質保証」を成立させるカギ
受託案件で AI エージェントを納品するとき、最大のハードルが 「品質をどう測るか」 です。Mastra の Eval は、データセットを使って自動評価ができます。
import { evaluate } from '@mastra/evals';
const result = await evaluate({
agent: supportAgent,
dataset: './evals/support-qa.jsonl',
metrics: ['answer-relevancy', 'faithfulness', 'context-precision'],
});
console.log(result.summary);
// { answerRelevancy: 0.87, faithfulness: 0.92, contextPrecision: 0.81 }CI に組み込めば、「リグレッション検知」を含めた継続評価が成立します。受託契約に「Eval スコア XX 以上を保証」と明記できると、納品基準が定量化できて揉めにくくなります。
落とし穴 ─ 私たちが現場でハマったポイント
実案件で Mastra を採用したときに遭遇した、3 つの落とし穴を共有します。
1. メモリの永続化を忘れる
@mastra/core のデフォルトメモリは インメモリです。本番に出すときは Redis / Postgres / Firestore へ差し替える必要がありますが、PoC からの差し替えを忘れて「再起動で会話履歴が消える」事故が起きました。
2. Workflow の状態が暴れる
Workflow の各ステップで context に積みすぎると、トークン消費が膨らみます。ステップ間で必要なフィールドだけ抽出して渡すラッパーを最初から入れます。
3. Eval データセットの作成コスト
Eval は便利ですが、データセット作成に工数を取られるのが現実です。私たちは「過去の問い合わせログから 200 件を人手でラベリング」を初期作業として見積もりに必ず入れます。
受託案件の型と単価
| 案件の型 | 期間 | 単価帯 |
|---|---|---|
| Mastra PoC（1 エージェント + 1 Workflow） | 4〜6 週間 | 250〜500 万円 |
| 業務システムへの本番組み込み | 3〜5 ヶ月 | 1,200〜3,000 万円 |
| RAG パイプライン構築 | 4〜8 週間 | 300〜800 万円 |
| Eval 基盤と CI 統合 | 単発 | 200〜500 万円 |
| 運用伴走 | 月額 | 40〜120 万円 |
Mastra と Symphony 記事 で触れたように、Mastra は Symphony との互換アダプタも進んでいるので、「単独 SDK で始め、後でマルチエージェント化」 という拡張パスも取れます。
まとめ ─ TypeScript 受託の現場で「最初に試す価値がある」フレームワーク
Mastra は、TypeScript ベースの業務システムに AI エージェントを後付けするとき、SDK を 1 つに集約できる という強みがあります。Python エコシステムへの移行コストや、別プロセス運用のオーバーヘッドを避けたい中小企業案件では、第一候補として検討する価値があります。
弊社では、Mastra を中心に据えた業務システム × AI エージェントの設計・PoC・本番構築・Eval 基盤整備を受託で行っています。「既存の Node.js 業務システムに AI を組み込みたい」「Python ベースの PoC を TypeScript に移したい」というご相談は、お問い合わせフォーム からお気軽にどうぞ。
