Skip to Content
ドキュメントフレームワークエージェンティックUIVercel AI SDKを使用

Vercel AI SDKの使用

Mastraはモデルルーティング、React Hooks、データストリーミングメソッドをサポートするためにVercel’s AI SDK と統合されています。

AI SDK v5 (beta)

MastraはAI SDK v5 (beta)もサポートしています。v5固有のメソッドについては以下のセクションを参照してください：Vercel AI SDK v5

⚠️

このページに含まれるコード例は、プロジェクトのルートでNext.js App Routerを使用していることを前提としています。例：src/appではなくapp。

モデルルーティング

Mastraでエージェントを作成する際、AI SDKがサポートする任意のモデルを指定できます。

agents/weather-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
 
export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions: "Instructions for the agent...",
  model: openai("gpt-4-turbo"),
});

詳細については、Model ProvidersとModel Capabilitiesを参照してください。

React Hooks

MastraはHTTPストリームを使用してフロントエンドコンポーネントをエージェントに直接接続するためのAI SDKフックをサポートしています。

必要なAI SDK Reactパッケージをインストールします：

npm install @ai-sdk/react

useChat() フックの使用

useChatフックは、フロントエンドとMastraエージェント間のリアルタイムチャットインタラクションを処理し、プロンプトを送信してHTTP経由でストリーミングレスポンスを受信することを可能にします。

app/test/chat.tsx
"use client";
 
import { useChat } from "@ai-sdk/react";
 
export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: "api/chat"
  });
  return (
    <div>
      <pre>{JSON.stringify(messages, null, 2)}</pre>
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="Name of city" />
      </form>
    </div>
  );
}

useChatフックを使用して送信されたリクエストは、標準のサーバールートによって処理されます。この例では、Next.js Route Handlerを使用してPOSTルートを定義する方法を示しています。

app/api/chat/route.ts
import { mastra } from "../../mastra";
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const stream = await myAgent.stream(messages);
 
  return stream.toDataStreamResponse();
}

エージェントメモリでuseChatを使用する場合は、重要な実装の詳細についてエージェントメモリセクションを参照してください。

useCompletion() フックの使用

useCompletionフックは、フロントエンドとMastraエージェント間の単一ターン完了を処理し、プロンプトを送信してHTTP経由でストリーミングレスポンスを受信することを可能にします。

app/test/completion.tsx
"use client";
 
import { useCompletion } from "@ai-sdk/react";
 
export function Completion() {
  const { completion, input, handleInputChange, handleSubmit } = useCompletion({
    api: "api/completion"
  });
 
  return (
    <div>
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="Name of city" />
      </form>
      <p>Completion result: {completion}</p>
    </div>
  );
}

useCompletionフックを使用して送信されたリクエストは、標準のサーバールートによって処理されます。この例では、Next.js Route Handlerを使用してPOSTルートを定義する方法を示しています。

app/api/completion/route.ts
import { mastra } from "../../../mastra";
 
export async function POST(req: Request) {
  const { prompt } = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const stream = await myAgent.stream([{ role: "user", content: prompt }]);
 
  return stream.toDataStreamResponse();
}

useObject() フックの使用

useObjectフックは、Mastraエージェントからストリーミングされたテキストを消費し、定義されたスキーマに基づいて構造化されたJSONオブジェクトに解析します。

app/test/object.tsx
"use client";
 
import { experimental_useObject as useObject } from "@ai-sdk/react";
import { z } from "zod";
 
export function Object() {
  const { object, submit } = useObject({
    api: "api/object",
    schema: z.object({
      weather: z.string()
    })
  });
 
  return (
    <div>
      <button onClick={() => submit("London")}>Generate</button>
      {object ? <pre>{JSON.stringify(object, null, 2)}</pre> : null}
    </div>
  );
}

useObjectフックを使用して送信されたリクエストは、標準のサーバールートによって処理されます。この例では、Next.js Route Handlerを使用してPOSTルートを定義する方法を示しています。

app/api/object/route.ts
import { mastra } from "../../../mastra";
import { z } from "zod";
 
export async function POST(req: Request) {
  const body = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const stream = await myAgent.stream(body, {
    output: z.object({
      weather: z.string()
    })
  });
 
  return stream.toTextStreamResponse();
}

sendExtraMessageFieldsで追加データを渡す

sendExtraMessageFieldsオプションを使用すると、フロントエンドからMastraに追加データを渡すことができます。このデータはサーバー上でRuntimeContextとして利用できます。

app/test/chat-extra.tsx
"use client";
 
import { useChat } from "@ai-sdk/react";
 
export function ChatExtra() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: "/api/chat-extra",
    sendExtraMessageFields: true
  });
 
  const handleFormSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    handleSubmit(e, {
      data: {
        userId: "user123",
        preferences: {
          language: "en",
          temperature: "celsius"
        }
      }
    });
  };
 
  return (
    <div>
      <pre>{JSON.stringify(messages, null, 2)}</pre>
      <form onSubmit={handleFormSubmit}>
        <input value={input} onChange={handleInputChange} placeholder="Name of city" />
      </form>
    </div>
  );
}

sendExtraMessageFieldsを使用して送信されたリクエストは、標準的なサーバールートで処理されます。この例では、カスタムデータを抽出してRuntimeContextインスタンスに設定する方法を示しています。

app/api/chat-extra/route.ts
import { mastra } from "../../../mastra";
import { RuntimeContext } from "@mastra/core/runtime-context";
 
export async function POST(req: Request) {
  const { messages, data } = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
 
  const runtimeContext = new RuntimeContext();
 
  if (data) {
    for (const [key, value] of Object.entries(data)) {
      runtimeContext.set(key, value);
    }
  }
 
  const stream = await myAgent.stream(messages, { runtimeContext });
  return stream.toDataStreamResponse();
}

server.middlewareでruntimeContextを処理する

サーバーミドルウェアでカスタムデータを読み取ってRuntimeContextを設定することもできます：

mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
 
export const mastra = new Mastra({
  agents: { weatherAgent },
  server: {
    middleware: [
      async (c, next) => {
        const runtimeContext = c.get("runtimeContext");
 
        if (c.req.method === "POST") {
          try {
            const clonedReq = c.req.raw.clone();
            const body = await clonedReq.json();
 
            if (body?.data) {
              for (const [key, value] of Object.entries(body.data)) {
                runtimeContext.set(key, value);
              }
            }
          } catch {
          }
        }
        await next();
      },
    ],
  },
});

その後、runtimeContextパラメータを通じてツール内でこのデータにアクセスできます。詳細については、Runtime Contextドキュメントを参照してください。

データのストリーミング

aiパッケージは、カスタムデータストリームを管理するためのユーティリティを提供します。場合によっては、エージェントのdataStreamを使用して、構造化された更新や注釈をクライアントに送信したい場合があります。

必要なパッケージをインストールします：

npm install ai

createDataStream()の使用

createDataStream関数を使用すると、クライアントに追加のデータをストリーミングできます。

mastra/agents/weather-agent.ts
import { createDataStream } from "ai";
import { Agent } from "@mastra/core/agent";
 
export const weatherAgent = new Agent({...});
 
createDataStream({
  async execute(dataStream) {
    dataStream.writeData({ value: "Hello" });
 
    dataStream.writeMessageAnnotation({ type: "status", value: "processing" });
 
    const agentStream = await weatherAgent.stream("What is the weather");
 
    agentStream.mergeIntoDataStream(dataStream);
  },
  onError: (error) => `Custom error: ${error}`
});

createDataStreamResponse()の使用

createDataStreamResponse関数は、クライアントにデータをストリーミングするレスポンスオブジェクトを作成します。

app/api/chat-stream/route.ts
import { mastra } from "../../../mastra";
import { createDataStreamResponse } from "ai";
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const agentStream = await myAgent.stream(messages);
 
  const response = createDataStreamResponse({
    status: 200,
    statusText: "OK",
    headers: {
      "Custom-Header": "value"
    },
    async execute(dataStream) {
      dataStream.writeData({ value: "Hello" });
 
      dataStream.writeMessageAnnotation({
        type: "status",
        value: "processing"
      });
 
      agentStream.mergeIntoDataStream(dataStream);
    },
    onError: (error) => `Custom error: ${error}`
  });
 
  return response;
}

Vercel AI SDK v5

このガイドでは、AI SDK v4からv5ベータに移行する際のMastra固有の考慮事項について説明します。

フィードバックやバグレポートはGithubのAI SDK v5メガイシュー に追加してください。

公式移行ガイド

すべてのAI SDKコアの破壊的変更、パッケージ更新、API変更については、公式のAI SDK v5移行ガイド に従ってください。

このガイドでは、移行のMastra固有の側面のみを扱います。

  • データ互換性: v5形式で保存された新しいデータは、ベータ版からダウングレードした場合に動作しなくなります
  • バックアップの推奨: v5ベータにアップグレードする前のDBバックアップを保持してください
  • 本番環境での使用: 本番アプリケーションで使用する前に、AI SDK v5の安定版リリースを待ってください
  • プレリリース状態: Mastraのai-v5タグはプレリリース版であり、バグが含まれる可能性があります

メモリとストレージ

Mastraは内部のMessageListクラスを使用してAI SDK v4データを自動的に処理し、v4からv5への変換を含むフォーマット変換を管理します。データベースの移行は不要で、既存のメッセージはその場で翻訳され、アップグレード後も引き続き動作します。

移行戦略

MastraでAI SDK v5に移行するには、バックエンド（Mastraサーバー）とフロントエンドの両方を更新する必要があります。 移行期間中のストリーム形式変換を処理するための互換性モードを提供しています。

依存関係のアップグレード

すべてのMastraパッケージの@ai-v5プレリリース版をインストールします：

npm install mastra@ai-v5 @mastra/core@ai-v5 @mastra/memory@ai-v5

フロントエンドとMastra Playgroundが引き続き動作するように、Mastraインスタンスをv4互換性で設定します：

mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
 
import { weatherAgent } from "./agents/weather-agent";
 
export const mastra = new Mastra({
  agents: { weatherAgent },
  aiSdkCompat: 'v4',
});

ストリーム互換性の有効化

フロントエンドがカスタムAPIルートを使用してMastraエージェントを呼び出す場合、AI SDK v4互換性を維持するためにtoUIMessageStreamResponse()の結果をcreateV4CompatibleResponseでラップします。

app/api/chat/route.ts
import { mastra } from "../../../mastra";
import { createV4CompatibleResponse } from "@mastra/core/agent";
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const myAgent = mastra.getAgent("weatherAgent");
  const stream = await myAgent.stream(messages);
 
  return createV4CompatibleResponse(stream.toUIMessageStreamResponse().body!);
}

フロントエンドのアップグレード

準備ができたら、互換性フラグを削除してフロントエンドをアップグレードします：

  1. Mastra設定からaiSdkCompat: 'v4'を削除
  2. フロントエンド依存関係のアップグレードに関するAI SDKガイドに従う
  3. v5の破壊的変更に対応するようにフロントエンドコードを更新
CIでの実行CopilotKitを使用