Agent.streamVNext() (Experimental)

Experimental API:

This is a new streaming implementation that supports multiple output formats (including AI SDK v5). It will replace .stream() and may change as we refine the feature based on feedback.

.streamVNext() メソッドは、強化された機能と柔軟なフォーマットにより、エージェントからの応答をリアルタイムでストリーミングできます。このメソッドはメッセージと任意のストリーミングオプションを受け取り、Mastra のネイティブ形式と AI SDK v5 との互換性を両立した次世代のストリーミング体験を提供します。

使用例


// Mastra のデフォルト形式
const mastraStream = await agent.streamVNext("message for agent");
 
// AI SDK v5 と互換の形式
const aiSdkStream = await agent.streamVNext("message for agent", {
  format: 'aisdk'
});

パラメーター

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

エージェントに送信するメッセージ。単一の文字列、文字列配列、または構造化メッセージオブジェクトを指定できます。

options?:

AgentExecutionOptions<Output, StructuredOutput, Format>

ストリーミング処理に関する任意の設定。

オプション

format?:

'mastra' | 'aisdk'

= 'mastra'

出力ストリームの形式を指定します。Mastra のネイティブ形式（デフォルト）には 'mastra'、AI SDK v5 互換には 'aisdk' を使用します。

maxSteps?:

number

実行時に処理する最大ステップ数。

scorers?:

MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>

実行結果に対して実行する評価用スコアラー。

scorer:

string

使用するスコアラー名。

sampling?:

ScoringSamplingConfig

スコアラーのサンプリング設定。

tracingContext?:

TracingContext

スパン階層とメタデータのための AI トレーシング・コンテキスト。

returnScorerData?:

boolean

レスポンスに詳細なスコアリングデータを含めるかどうか。

onChunk?:

(chunk: ChunkType) => Promise<void> | void

ストリーミング中、各チャンクごとに呼び出されるコールバック関数。

onError?:

({ error }: { error: Error | string }) => Promise<void> | void

ストリーミング中にエラーが発生した際に呼び出されるコールバック関数。

onAbort?:

(event: any) => Promise<void> | void

ストリームが中断された際に呼び出されるコールバック関数。

abortSignal?:

AbortSignal

エージェントの実行を中止できる Signal オブジェクト。シグナルが中止されると、進行中のすべての処理が終了します。

activeTools?:

Array<keyof ToolSet> | undefined

実行中に利用可能なアクティブなツール名の配列。

prepareStep?:

PrepareStepFunction<any>

マルチステップ実行の各ステップ前に呼び出されるコールバック関数。

context?:

ModelMessage[]

エージェントに与える追加のコンテキストメッセージ。

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

開発者体験を向上させた構造化出力生成を有効にします。内部で StructuredOutputProcessor を自動作成して使用します。

schema:

z.ZodSchema<S>

出力を検証するための Zod スキーマ。

model?:

MastraLanguageModel

内部の構造化エージェントに使用するモデル。未指定の場合はエージェントのモデルを使用します。

errorStrategy?:

'strict' | 'warn' | 'fallback'

パースまたは検証に失敗した場合の方針。デフォルトは 'strict'。

fallbackValue?:

errorStrategy が 'fallback' の場合のフォールバック値。

instructions?:

string

構造化エージェントへのカスタム指示。

outputProcessors?:

Processor[]

エージェントに設定された出力プロセッサを上書きします。ユーザーに返却される前にエージェントのメッセージを変更または検証できます。`processOutputResult` と `processOutputStream` のいずれか（または両方）を実装する必要があります。

inputProcessors?:

Processor[]

エージェントに設定された入力プロセッサを上書きします。エージェントで処理される前にメッセージを変更または検証できます。`processInput` 関数を実装する必要があります。

instructions?:

string

この生成でエージェントのデフォルト指示を上書きするカスタム指示。新しいエージェントインスタンスを作成せずに動的に挙動を変更するのに有用です。

output?:

Zod schema | JsonSchema7

**非推奨。** 同等の目的には structuredOutput と maxSteps:1 を使用してください。出力の期待される構造を定義します。JSON Schema オブジェクトまたは Zod スキーマを指定できます。

memory?:

object

メモリの設定。メモリ管理の推奨方法です。

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

会話スレッド。文字列 ID、または `id` と任意の `metadata` を持つオブジェクトで指定します。

resource:

string

スレッドに関連付けられたユーザーまたはリソースの識別子。

options?:

MemoryConfig

メッセージ履歴やセマンティックリコールなど、メモリ動作の設定。

onFinish?:

StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>

ストリーミング完了時に呼び出されるコールバック関数。最終結果を受け取ります。

onStepFinish?:

StreamTextOnStepFinishCallback<any> | never

各実行ステップ後に呼び出されるコールバック関数。ステップの詳細を JSON 文字列として受け取ります。構造化出力では利用できません。

resourceId?:

string

**非推奨。** 代わりに `memory.resource` を使用してください。エージェントと対話するユーザーまたはリソースの識別子。threadId が指定されている場合は必須です。

telemetry?:

TelemetrySettings

ストリーミング中のテレメトリ収集の設定。

isEnabled?:

boolean

テレメトリを有効/無効にします。実験段階ではデフォルトで無効です。

recordInputs?:

boolean

入力の記録を有効/無効にします。デフォルトで有効。機密情報の記録を避けるため、無効化することを検討してください。

recordOutputs?:

boolean

出力の記録を有効/無効にします。デフォルトで有効。機密情報の記録を避けるため、無効化することを検討してください。

functionId?:

string

この関数の識別子。関数単位でテレメトリデータをグルーピングするために使用します。

modelSettings?:

CallSettings

temperature、maxTokens、topP などのモデル固有の設定。基盤となる言語モデルに渡されます。

temperature?:

number

モデル出力のランダム性を制御します。値が高い（例: 0.8）ほどランダム性が増し、低い（例: 0.2）ほど収束的で決定的になります。

maxRetries?:

number

失敗したリクエストの最大再試行回数。

topP?:

number

Nucleus サンプリング。0〜1 の数値です。temperature か topP のいずれか片方のみを設定することを推奨します。

topK?:

number

各後続トークンで上位 K 個の選択肢からのみサンプリングします。低確率の“ロングテール”応答を除去するために使用します。

presencePenalty?:

number

Presence ペナルティ設定。プロンプトに既に含まれる情報を繰り返す傾向に影響します。-1（反復を増やす）から 1（最大ペナルティ、反復を減らす）までの数値。

frequencyPenalty?:

number

Frequency ペナルティ設定。同じ単語やフレーズを繰り返し使用する傾向に影響します。-1（反復を増やす）から 1（最大ペナルティ、反復を減らす）までの数値。

stopSequences?:

string[]

ストップシーケンス。設定すると、いずれかのストップシーケンスが生成された時点でモデルはテキスト生成を停止します。

threadId?:

string

**非推奨。** 代わりに `memory.thread` を使用してください。会話スレッドの識別子。複数の対話にわたってコンテキストを維持できます。resourceId が指定されている場合は必須です。

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

= 'auto'

ストリーミング中にエージェントがツールをどのように使用するかを制御します。

'auto':

string

ツールを使用するかどうかをモデルに任せます（デフォルト）。

'none':

string

ツールを一切使用しない。

'required':

string

少なくとも 1 つのツールを使用するようモデルに要求します。

{ type: 'tool'; toolName: string }:

object

特定のツールを名前で使用するようモデルに要求します。

toolsets?:

ToolsetsInput

ストリーミング中にエージェントで利用可能にする追加のツールセット。

clientTools?:

ToolsInput

リクエストの“クライアント”側で実行されるツール。これらのツールは定義内に execute 関数を持ちません。

savePerStep?:

boolean

各ストリームステップ完了後にメッセージを段階的に保存します（デフォルト: false）。

providerOptions?:

Record<string, Record<string, JSONValue>>

基盤となる LLM プロバイダに渡される、プロバイダ固有の追加オプション。構造は `{ providerName: { optionKey: value } }` です。例: `{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }`。

openai?:

Record<string, JSONValue>

OpenAI 固有のオプション。例: `{ reasoningEffort: 'high' }`

anthropic?:

Record<string, JSONValue>

Anthropic 固有のオプション。例: `{ maxTokens: 1000 }`

google?:

Record<string, JSONValue>

Google 固有のオプション。例: `{ safetySettings: [...] }`

[providerName]?:

Record<string, JSONValue>

その他のプロバイダ固有のオプション。キーはプロバイダ名、値はプロバイダ固有オプションのレコードです。

runId?:

string

この生成実行の一意の ID。追跡やデバッグに有用です。

runtimeContext?:

RuntimeContext

依存性注入とコンテキスト情報のためのランタイムコンテキスト。

stopWhen?:

StopCondition | StopCondition[]

エージェントの実行を停止する条件。単体または配列で指定できます。

返り値

stream:

MastraModelOutput<Output> | AISDKV5OutputStream<Output>

format パラメータに応じたストリーミングインターフェースを返します。format が 'mastra'（デフォルト）の場合は MastraModelOutput を、'aisdk' の場合は AI SDK v5 互換の AISDKV5OutputStream を返します。

追加の使用例

Mastra フォーマット（デフォルト）


import { stepCountIs } from 'ai-v5';
 
const stream = await agent.streamVNext("Tell me a story", {
  stopWhen: stepCountIs(3), // 3ステップで停止
  modelSettings: {
    temperature: 0.7,
  },
});
 
// テキストストリームにアクセス
for await (const chunk of stream.textStream) {
  console.log(chunk);
}
 
// ストリーミング完了後に全文を取得
const fullText = await stream.text;

AI SDK v5 の形式


import { stepCountIs } from 'ai-v5';
 
const stream = await agent.streamVNext("物語を聞かせて", {
  format: 'aisdk',
  stopWhen: stepCountIs(3), // 3ステップで停止
  modelSettings: {
    temperature: 0.7,
  },
});
 
// AI SDK v5 互換のインターフェースで使用
for await (const part of stream.fullStream) {
  if (part.type === 'text-delta') {
    console.log(part.text);
  }
}
 
// フロントエンド連携用の API ルート内で
return stream.toUIMessageStreamResponse();

コールバックの使用

すべてのコールバック関数がトップレベルのプロパティとして利用できるようになり、よりシンプルで使いやすいAPIになりました。


const stream = await agent.streamVNext("Tell me a story", {
  onFinish: (result) => {
    console.log('Streaming finished:', result);
  },
  onStepFinish: (step) => {
    console.log('Step completed:', step);
  },
  onChunk: (chunk) => {
    console.log('Received chunk:', chunk);
  },
  onError: ({ error }) => {
    console.error('Streaming error:', error);
  },
  onAbort: (event) => {
    console.log('Stream aborted:', event);
  },
});
 
// ストリームを処理する
for await (const chunk of stream.textStream) {
  console.log(chunk);
}

オプション付きの高度な例


import { z } from "zod";
import { stepCountIs } from 'ai-v5';
 
await agent.streamVNext("エージェントへのメッセージ", {
  format: 'aisdk', // AI SDK v5 互換モードを有効化
  stopWhen: stepCountIs(3), // 3ステップ後に停止
  modelSettings: {
    temperature: 0.7,
  },
  memory: {
    thread: "user-123",
    resource: "test-app"
  },
  toolChoice: "auto",
  // より良い開発者体験（DX）のための構造化出力
  structuredOutput: {
    schema: z.object({
      sentiment: z.enum(['positive', 'negative', 'neutral']),
      confidence: z.number(),
    }),
    model: openai("gpt-4o-mini"),
    errorStrategy: 'warn',
  },
  // ストリーミング応答の検証用出力プロセッサ
  outputProcessors: [
    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
    new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
  ],
});

Agent.streamVNext() (Experimental)

Experimental API:

This is a new streaming implementation that supports multiple output formats (including AI SDK v5). It will replace .stream() and may change as we refine the feature based on feedback.

使用例


// Mastra のデフォルト形式
const mastraStream = await agent.streamVNext("message for agent");
 
// AI SDK v5 と互換の形式
const aiSdkStream = await agent.streamVNext("message for agent", {
  format: 'aisdk'
});

パラメーター

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

エージェントに送信するメッセージ。単一の文字列、文字列配列、または構造化メッセージオブジェクトを指定できます。

options?:

AgentExecutionOptions<Output, StructuredOutput, Format>

ストリーミング処理に関する任意の設定。

オプション

format?:

'mastra' | 'aisdk'

= 'mastra'

出力ストリームの形式を指定します。Mastra のネイティブ形式（デフォルト）には 'mastra'、AI SDK v5 互換には 'aisdk' を使用します。

maxSteps?:

number

実行時に処理する最大ステップ数。

scorers?:

MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>

実行結果に対して実行する評価用スコアラー。

scorer:

string

使用するスコアラー名。

sampling?:

ScoringSamplingConfig

スコアラーのサンプリング設定。

tracingContext?:

TracingContext

スパン階層とメタデータのための AI トレーシング・コンテキスト。

returnScorerData?:

boolean

レスポンスに詳細なスコアリングデータを含めるかどうか。

onChunk?:

(chunk: ChunkType) => Promise<void> | void

ストリーミング中、各チャンクごとに呼び出されるコールバック関数。

onError?:

({ error }: { error: Error | string }) => Promise<void> | void

ストリーミング中にエラーが発生した際に呼び出されるコールバック関数。

onAbort?:

(event: any) => Promise<void> | void

ストリームが中断された際に呼び出されるコールバック関数。

abortSignal?:

AbortSignal

エージェントの実行を中止できる Signal オブジェクト。シグナルが中止されると、進行中のすべての処理が終了します。

activeTools?:

Array<keyof ToolSet> | undefined

実行中に利用可能なアクティブなツール名の配列。

prepareStep?:

PrepareStepFunction<any>

マルチステップ実行の各ステップ前に呼び出されるコールバック関数。

context?:

ModelMessage[]

エージェントに与える追加のコンテキストメッセージ。

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

開発者体験を向上させた構造化出力生成を有効にします。内部で StructuredOutputProcessor を自動作成して使用します。

schema:

z.ZodSchema<S>

出力を検証するための Zod スキーマ。

model?:

MastraLanguageModel

内部の構造化エージェントに使用するモデル。未指定の場合はエージェントのモデルを使用します。

errorStrategy?:

'strict' | 'warn' | 'fallback'

パースまたは検証に失敗した場合の方針。デフォルトは 'strict'。

fallbackValue?:

errorStrategy が 'fallback' の場合のフォールバック値。

instructions?:

string

構造化エージェントへのカスタム指示。

outputProcessors?:

Processor[]

inputProcessors?:

Processor[]

instructions?:

string

output?:

Zod schema | JsonSchema7

memory?:

object

メモリの設定。メモリ管理の推奨方法です。

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

会話スレッド。文字列 ID、または `id` と任意の `metadata` を持つオブジェクトで指定します。

resource:

string

スレッドに関連付けられたユーザーまたはリソースの識別子。

options?:

MemoryConfig

メッセージ履歴やセマンティックリコールなど、メモリ動作の設定。

onFinish?:

StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>

ストリーミング完了時に呼び出されるコールバック関数。最終結果を受け取ります。

onStepFinish?:

StreamTextOnStepFinishCallback<any> | never

各実行ステップ後に呼び出されるコールバック関数。ステップの詳細を JSON 文字列として受け取ります。構造化出力では利用できません。

resourceId?:

string

telemetry?:

TelemetrySettings

ストリーミング中のテレメトリ収集の設定。

isEnabled?:

boolean

テレメトリを有効/無効にします。実験段階ではデフォルトで無効です。

recordInputs?:

boolean

入力の記録を有効/無効にします。デフォルトで有効。機密情報の記録を避けるため、無効化することを検討してください。

recordOutputs?:

boolean

出力の記録を有効/無効にします。デフォルトで有効。機密情報の記録を避けるため、無効化することを検討してください。

functionId?:

string

この関数の識別子。関数単位でテレメトリデータをグルーピングするために使用します。

modelSettings?:

CallSettings

temperature、maxTokens、topP などのモデル固有の設定。基盤となる言語モデルに渡されます。

temperature?:

number

モデル出力のランダム性を制御します。値が高い（例: 0.8）ほどランダム性が増し、低い（例: 0.2）ほど収束的で決定的になります。

maxRetries?:

number

失敗したリクエストの最大再試行回数。

topP?:

number

Nucleus サンプリング。0〜1 の数値です。temperature か topP のいずれか片方のみを設定することを推奨します。

topK?:

number

各後続トークンで上位 K 個の選択肢からのみサンプリングします。低確率の“ロングテール”応答を除去するために使用します。

presencePenalty?:

number

frequencyPenalty?:

number

stopSequences?:

string[]

ストップシーケンス。設定すると、いずれかのストップシーケンスが生成された時点でモデルはテキスト生成を停止します。

threadId?:

string

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

= 'auto'

ストリーミング中にエージェントがツールをどのように使用するかを制御します。

'auto':

string

ツールを使用するかどうかをモデルに任せます（デフォルト）。

'none':

string

ツールを一切使用しない。

'required':

string

少なくとも 1 つのツールを使用するようモデルに要求します。

{ type: 'tool'; toolName: string }:

object

特定のツールを名前で使用するようモデルに要求します。

toolsets?:

ToolsetsInput

ストリーミング中にエージェントで利用可能にする追加のツールセット。

clientTools?:

ToolsInput

リクエストの“クライアント”側で実行されるツール。これらのツールは定義内に execute 関数を持ちません。

savePerStep?:

boolean

各ストリームステップ完了後にメッセージを段階的に保存します（デフォルト: false）。

providerOptions?:

Record<string, Record<string, JSONValue>>

openai?:

Record<string, JSONValue>

OpenAI 固有のオプション。例: `{ reasoningEffort: 'high' }`

anthropic?:

Record<string, JSONValue>

Anthropic 固有のオプション。例: `{ maxTokens: 1000 }`

google?:

Record<string, JSONValue>

Google 固有のオプション。例: `{ safetySettings: [...] }`

[providerName]?:

Record<string, JSONValue>

その他のプロバイダ固有のオプション。キーはプロバイダ名、値はプロバイダ固有オプションのレコードです。

runId?:

string

この生成実行の一意の ID。追跡やデバッグに有用です。

runtimeContext?:

RuntimeContext

依存性注入とコンテキスト情報のためのランタイムコンテキスト。

stopWhen?:

StopCondition | StopCondition[]

エージェントの実行を停止する条件。単体または配列で指定できます。

返り値

stream:

MastraModelOutput<Output> | AISDKV5OutputStream<Output>

追加の使用例

Mastra フォーマット（デフォルト）


import { stepCountIs } from 'ai-v5';
 
const stream = await agent.streamVNext("Tell me a story", {
  stopWhen: stepCountIs(3), // 3ステップで停止
  modelSettings: {
    temperature: 0.7,
  },
});
 
// テキストストリームにアクセス
for await (const chunk of stream.textStream) {
  console.log(chunk);
}
 
// ストリーミング完了後に全文を取得
const fullText = await stream.text;

AI SDK v5 の形式


import { stepCountIs } from 'ai-v5';
 
const stream = await agent.streamVNext("物語を聞かせて", {
  format: 'aisdk',
  stopWhen: stepCountIs(3), // 3ステップで停止
  modelSettings: {
    temperature: 0.7,
  },
});
 
// AI SDK v5 互換のインターフェースで使用
for await (const part of stream.fullStream) {
  if (part.type === 'text-delta') {
    console.log(part.text);
  }
}
 
// フロントエンド連携用の API ルート内で
return stream.toUIMessageStreamResponse();

コールバックの使用

すべてのコールバック関数がトップレベルのプロパティとして利用できるようになり、よりシンプルで使いやすいAPIになりました。


const stream = await agent.streamVNext("Tell me a story", {
  onFinish: (result) => {
    console.log('Streaming finished:', result);
  },
  onStepFinish: (step) => {
    console.log('Step completed:', step);
  },
  onChunk: (chunk) => {
    console.log('Received chunk:', chunk);
  },
  onError: ({ error }) => {
    console.error('Streaming error:', error);
  },
  onAbort: (event) => {
    console.log('Stream aborted:', event);
  },
});
 
// ストリームを処理する
for await (const chunk of stream.textStream) {
  console.log(chunk);
}

オプション付きの高度な例


import { z } from "zod";
import { stepCountIs } from 'ai-v5';
 
await agent.streamVNext("エージェントへのメッセージ", {
  format: 'aisdk', // AI SDK v5 互換モードを有効化
  stopWhen: stepCountIs(3), // 3ステップ後に停止
  modelSettings: {
    temperature: 0.7,
  },
  memory: {
    thread: "user-123",
    resource: "test-app"
  },
  toolChoice: "auto",
  // より良い開発者体験（DX）のための構造化出力
  structuredOutput: {
    schema: z.object({
      sentiment: z.enum(['positive', 'negative', 'neutral']),
      confidence: z.number(),
    }),
    model: openai("gpt-4o-mini"),
    errorStrategy: 'warn',
  },
  // ストリーミング応答の検証用出力プロセッサ
  outputProcessors: [
    new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
    new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
  ],
});