エージェントのストリーミング（VNext）

Mastra のエージェントは、クライアントとのリアルタイムなやり取りに向けて応答のストリーミングをサポートしています。これにより、応答を段階的にレンダリングでき、ユーザー体験が向上します。

実験的な API: 本ガイドで紹介する streamVNext メソッドは、拡張されたストリーミング形式に対応する実験的機能です。追加のテストと改良を経て、現在の stream() メソッドに置き換わる予定です。本番環境では、streamVNext が確定するまでは安定版の stream() メソッドの利用をご検討ください。

使い方

実験的なストリーミングプロトコルでは、エージェントの streamVNext メソッドを使用します。このメソッドは現在、Mastra（デフォルト）および AI SDK v5 に対応した複数の出力ストリーム形式をサポートしています。

Format パラメータ

format パラメータは出力ストリームの種類を決定します:

'mastra' (デフォルト): MastraModelOutput を返します — Mastra のネイティブなストリーミング形式
'aisdk': AISDKV5OutputStream を返します — useChat などの AI SDK v5 インターフェースと互換性あり


// Mastra 形式（デフォルト）
const mastraStream = await agent.streamVNext("Hello");
 
// AI SDK v5 形式
const aiSdkStream = await agent.streamVNext("Hello", { 
  format: 'aisdk' 
});

デフォルトの Mastra 形式

デフォルトでは、streamVNext は MastraModelOutput ストリームを返します:


const stream = await agent.streamVNext("Tell me a story.");
 
// テキストストリームにアクセス
for await (const chunk of stream.textStream) {
  console.log(chunk);
}
 
// あるいは、ストリーミング後に全文を取得
const fullText = await stream.text;

AI SDK v5 互換

AI SDK v5 と統合する場合は、format: 'aisdk' パラメータで AISDKV5OutputStream を取得します:


const stream = await agent.streamVNext("Tell me a story.", {
  format: 'aisdk'
});
 
// このストリームは AI SDK v5 の各種インターフェースと互換です
for await (const chunk of stream.fullStream) {
  // AI SDK v5 形式のチャンクを処理
  console.log(chunk);
}

ストリームのプロパティ

どちらのストリーム形式でも、さまざまなレスポンスのプロパティにアクセスできます:

stream.textStream - テキストチャンクを出力する読み取り可能なストリーム
stream.text - 完全なテキストレスポンスで解決される Promise
stream.finishReason - エージェントがストリーミングを停止した理由
stream.usage - トークン使用量情報

ツールでストリームを使う方法

各ツールは writer 引数を受け取ります。これはカスタムの書き込み関数を備えた書き込み可能なストリームで、この関数を使ってツールのレスポンスをストリームに書き込みます。

src/mastra/tools/test-tool.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherInfo = createTool({
  id: "Get Weather Information",
  inputSchema: z.object({
    city: z.string(),
  }),
  outputSchema: z.object({
    conditions: z.string(),
    temperature: z.number(),
  }),
  description: `Fetches the current weather information for a given city`,
  execute: async ({ context: { city }, writer }) => {
    writer.write({
      type: "weather-data",
      args: {
        city
      },
      status: "pending"
    })
    // Tool logic here (e.g., API call)
    console.log("Using tool to fetch weather information for", city);
 
    writer.write({
      type: "weather-data",
      args: {
        city
      },
      status: "success",
      result: {
        temperature: 20,
        conditions: "Sunny"
      }
    })
 
    return { temperature: 20, conditions: "Sunny" }; // Example return
  },
});

エージェントベースのツール内でストリーミングを利用するには、エージェントで streamVNext を呼び出し、writer にパイプします:

src/mastra/tools/test-tool.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherInfo = createTool({
  id: "Get Weather Information",
  description: `Fetches the current weather information for a given city`,
  inputSchema: z.object({
    city: z.string(),
  }),
  outputSchema: z.object({
    text: z.string(),
  }),
  execute: async ({ context: { city }, writer, mastra }) => {
    const agent = mastra.getAgent('weatherAgent')
    const stream = await agent.streamVNext(`What is the weather in ${city}?`);
 
    await stream.pipeTo(writer);
 
    return {
      text: await stream.text,
    }
  },
});

ストリームを writer にパイプすることで、ネストされたエージェント呼び出し全体のトークン使用量が自動的に集計されます。