ストリーミング概要

Mastra はエージェントやワークフローからのリアルタイムなストリーミング応答をサポートしており、完了を待たずに生成と同時に出力を確認できます。これは、チャット、長文コンテンツ、マルチステップのワークフローなど、即時のフィードバックが重要なあらゆる場面で有用です。

はじめに

Mastra は現在 2 つのストリーミング方式をサポートしており、このページでは streamVNext() の使い方を説明します。

1. .stream(): 現行の安定版 API。AI SDK v4（LanguageModelV1）に対応。
2. .streamVNext(): 実験的な API。AI SDK v5（LanguageModelV2）に対応。

エージェントでのストリーミング

シンプルなプロンプトには単一の文字列を渡し、複数のコンテキストを提供する場合は文字列の配列を、役割や会話の流れを厳密に制御したい場合は role と content を含むメッセージオブジェクトの配列を渡せます。

Agent.streamVNext()の使用

textStream はレスポンス生成中の出力をチャンクに分割し、結果が一度に届くのではなく段階的にストリーミングされるようにします。for await ループで textStream を反復処理し、各チャンクを確認します。

const testAgent = mastra.getAgent("testAgent");
 
const stream = await testAgent.streamVNext([
  { role: "user", content: "Help me organize my day" },
]);
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

詳細は Agent.streamVNext() を参照してください。

Agent.streamVNext() の出力

この出力は、エージェントが生成した応答をストリーミングします。

もちろんです！
一日を効率的に計画するために、もう少し情報が必要です。
ご検討いただきたい質問は次のとおりです：
...

エージェントストリームのプロパティ

エージェントストリームでは、さまざまなレスポンスのプロパティにアクセスできます:

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

AI SDK v5 の互換性

AI SDK v5 では、モデルプロバイダーに LanguageModelV2 が使用されます。AI SDK v4 のモデルを使用しているというエラーが表示される場合は、モデルパッケージを次のメジャーバージョンにアップグレードしてください。

AI SDK v5 と連携するには、format を ‘aisdk’ に指定して AISDKV5OutputStream を取得します:

const testAgent = mastra.getAgent("testAgent");
 
const stream = await testAgent.streamVNext(
  [{ role: "user", content: "Help me organize my day" }],
  { format: "aisdk" }
);
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

ワークフローでのストリーミング

ワークフローからのストリーミングでは、増分的なテキストチャンクではなく、実行のライフサイクルを記述する構造化イベントの連なりが返されます。このイベントベースの形式により、.createRunAsync() を使用して実行が作成されると、ワークフローの進行状況をリアルタイムで追跡し、反応できるようになります。

Run.streamVNext() の使用

これは実験的な API です。イベントの ReadableStream を直接返します。

const run = await testWorkflow.createRunAsync();
 
const stream = await run.streamVNext({
  inputData: {
    value: "initial data"
  }
});
 
for await (const chunk of stream) {
  console.log(chunk);
}

詳細は Run.streamVNext() を参照してください。

Run.streamVNext() の出力

実験的な API のイベント構造では、トップレベルに runId と from が含まれており、ペイロードを覗かなくてもワークフローの実行を特定・追跡しやすくなります。

// ...
{
  type: 'step-start',
  runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',
  from: 'WORKFLOW',
  payload: {
    stepName: 'step-1',
    args: { value: 'initial data' },
    stepCallId: '8e15e618-be0e-4215-a5d6-08e58c152068',
    startedAt: 1755121710066,
    status: 'running'
  }
}

ワークフローストリームのプロパティ

ワークフローストリームでは、各種のレスポンスプロパティにアクセスできます:

• stream.status: ワークフロー実行のステータス。
• stream.result: ワークフロー実行の結果。
• stream.usage: ワークフロー実行におけるトークンの合計使用量。

関連

• ストリーミングイベント
• エージェントの使用
• ワークフローの概要