MastraModelOutput

実験的 API: この型は実験的な streamVNext() メソッドの一部です。フィードバックに基づき機能を改善していく過程で、API が変更される可能性があります。

MastraModelOutput クラスは agent.streamVNext() によって返され、モデル出力へのストリーミングアクセスと Promise ベースのアクセスの両方を提供します。構造化出力の生成、ツール呼び出し、推論、包括的な使用状況の追跡をサポートします。


// MastraModelOutput は agent.streamVNext() によって返されます
const stream = await agent.streamVNext("Hello world");

セットアップと基本的な使い方については、streamVNext() メソッドのドキュメントを参照してください。

ストリーミングプロパティ

これらのプロパティにより、モデルの出力を生成と同時にリアルタイムで参照できます：

fullStream:

ReadableStream<ChunkType<OUTPUT>>

テキスト、ツール呼び出し、推論、メタデータ、コントロールチャンクなど、あらゆるチャンクタイプを含む完全なストリーム。モデルの応答のすべての側面にきめ細かくアクセスできます。

ReadableStream

ChunkType:

ChunkType<OUTPUT>

ストリーミング中に出力されうるすべてのチャンクタイプ

textStream:

ReadableStream<string>

テキストコンテンツのみを増分で流すストリーム。メタデータ、ツール呼び出し、コントロールチャンクをすべて除外し、生成中のテキストだけを提供します。

objectStream:

ReadableStream<PartialSchemaOutput<OUTPUT>>

出力スキーマ使用時の、構造化オブジェクトの進行中更新を流すストリーム。構築途中の部分的なオブジェクトを逐次出力し、構造化データ生成をリアルタイムに可視化できます。

ReadableStream

PartialSchemaOutput:

PartialSchemaOutput<OUTPUT>

定義済みスキーマに適合する未完成の部分オブジェクト

elementStream:

ReadableStream<InferSchemaOutput<OUTPUT> extends (infer T)[] ? T : never>

出力スキーマが配列型を定義している場合に、配列の各要素を個別に流すストリーム。配列全体の完了を待たず、各要素が完了し次第出力されます。

Promiseベースのプロパティ

これらのプロパティは、ストリームの完了後に最終値へと解決されます:

text:

Promise<string>

モデルからの連結済みの完全なテキスト応答。テキスト生成が完了すると解決されます。

object:

Promise<InferSchemaOutput<OUTPUT>>

出力スキーマ使用時の、完全な構造化オブジェクト応答。解決前にスキーマで検証され、検証に失敗した場合は拒否されます。

Promise

InferSchemaOutput:

InferSchemaOutput<OUTPUT>

スキーマ定義に厳密一致する完全型付けオブジェクト

reasoning:

Promise<string>

reasoning をサポートするモデル（OpenAI の o1 シリーズなど）における、完全な reasoning テキスト。reasoning 非対応のモデルでは空文字列を返します。

reasoningText:

Promise<string | undefined>

reasoning コンテンツへの別経路。reasoning 非対応のモデルでは undefined の可能性があり、一方で 'reasoning' は空文字列を返します。

toolCalls:

Promise<ToolCallChunk[]>

実行中に行われたすべてのツール呼び出しチャンクの配列。各チャンクにはツールのメタデータと実行詳細が含まれます。

ToolCallChunk

type:

'tool-call'

チャンク種別の識別子

runId:

string

実行ラン識別子

from:

ChunkFrom

チャンクの発生元（AGENT、WORKFLOW など）

payload:

ToolCallPayload

toolCallId、toolName、args、実行詳細を含むツール呼び出しデータ

toolResults:

Promise<ToolResultChunk[]>

ツール呼び出しに対応するすべてのツール結果チャンクの配列。実行結果およびエラー情報を含みます。

ToolResultChunk

type:

'tool-result'

チャンク種別の識別子

runId:

string

実行ラン識別子

from:

ChunkFrom

チャンクの発生元（AGENT、WORKFLOW など）

payload:

ToolResultPayload

toolCallId、toolName、result、エラー状態を含むツール結果データ

usage:

Promise<Record<string, number>>

入力トークン、出力トークン、合計トークン、reasoning トークン（reasoning モデルの場合）を含むトークン使用状況の統計。

Record

inputTokens:

number

入力プロンプトで消費したトークン数

outputTokens:

number

応答で生成されたトークン数

totalTokens:

number

入力トークンと出力トークンの合計

reasoningTokens?:

number

非公開の reasoning トークン（reasoning モデル向け）

finishReason:

Promise<string | undefined>

生成が停止した理由（例: 'stop'、'length'、'tool_calls'、'content_filter'）。ストリームが完了していない場合は undefined。

enum

stop:

'stop'

モデルが自然に完了

length:

'length'

最大トークン数に到達

tool_calls:

'tool_calls'

モデルがツールを呼び出した

content_filter:

'content_filter'

コンテンツがフィルタリングされた

エラーのプロパティ

error:

string | Error | { message: string; stack: string; } | undefined

ストリームでエラーが発生した場合のエラー情報。エラーが発生していない場合は undefined。文字列メッセージ、Error オブジェクト、またはスタックトレースを含むシリアライズ済みエラーのいずれか。

メソッド

getFullOutput:

() => Promise<FullOutput>

テキスト、構造化オブジェクト、ツール呼び出し、使用状況統計、推論、メタデータなど、すべての結果を含む包括的な出力オブジェクトを返します。ストリームの全結果へアクセスするための便利な単一メソッドです。

FullOutput

text:

string

完全なテキスト応答

object?:

InferSchemaOutput<OUTPUT>

スキーマが提供された場合の構造化出力

toolCalls:

ToolCallChunk[]

実行されたすべてのツール呼び出しチャンク

toolResults:

ToolResultChunk[]

すべてのツール結果チャンク

usage:

Record<string, number>

トークン使用量の統計

reasoning?:

string

利用可能な場合の推論テキスト

finishReason?:

string

生成が終了した理由

consumeStream:

(options?: ConsumeStreamOptions) => Promise<void>

チャンクを処理せずにストリーム全体を手動で消費します。最終的な Promise ベースの結果だけが必要で、ストリームの消費を明示的に開始したい場合に便利です。

ConsumeStreamOptions

onError?:

(error: Error) => void

ストリームエラーを処理するためのコールバック

使い方の例

テキストの基本的なストリーミング


const stream = await agent.streamVNext("Write a haiku");
 
// 生成されるそばからテキストをストリーミングする
for await (const text of stream.textStream) {
  process.stdout.write(text);
}
 
// あるいは、全文をまとめて取得する
const fullText = await stream.text;
console.log(fullText);

構造化出力のストリーミング


const stream = await agent.streamVNext("Generate user data", {
  output: z.object({
    name: z.string(),
    age: z.number(),
    email: z.string()
  })
});
 
// 部分オブジェクトをストリーミング
for await (const partial of stream.objectStream) {
  console.log("進行状況:", partial); // { name: "John" }, { name: "John", age: 30 }, ...
}
 
// 検証済みの最終オブジェクトを取得
const user = await stream.object;
console.log("最終結果:", user); // { name: "John", age: 30, email: "john@example.com" }

ツールの呼び出しと結果


const stream = await agent.streamVNext("What's the weather in NYC?", {
  tools: { weather: weatherTool }
});
 
// ツール呼び出しをモニタリング
const toolCalls = await stream.toolCalls;
const toolResults = await stream.toolResults;
 
console.log("呼び出されたツール:", toolCalls);
console.log("結果:", toolResults);

出力の一括取得


const stream = await agent.streamVNext("Analyze this data");
 
const output = await stream.getFullOutput();
console.log({
  text: output.text,
  usage: output.usage,
  reasoning: output.reasoning,
  finishReason: output.finishReason
});

フルストリーム処理


const stream = await agent.streamVNext("Complex task");
 
for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      process.stdout.write(chunk.payload.text);
      break;
    case 'tool-call':
      console.log(`ツール ${chunk.payload.toolName} を呼び出し中...`);
      break;
    case 'reasoning-delta':
      console.log(`推論: ${chunk.payload.text}`);
      break;
    case 'finish':
      console.log(`完了！理由: ${chunk.payload.stepResult.reason}`);
      break;
  }
}

エラー処理


const stream = await agent.streamVNext("Analyze this data");
 
try {
  // オプション1: consumeStream 内でエラーを処理する
  await stream.consumeStream({
    onError: (error) => {
      console.error("ストリームエラー:", error);
    }
  });
  
  const result = await stream.text;
} catch (error) {
  console.error("結果の取得に失敗しました:", error);
}
 
// オプション2: error プロパティを確認する
const result = await stream.getFullOutput();
if (stream.error) {
  console.error("ストリームでエラーが発生しました:", stream.error);
}

MastraModelOutput


// MastraModelOutput は agent.streamVNext() によって返されます
const stream = await agent.streamVNext("Hello world");

セットアップと基本的な使い方については、streamVNext() メソッドのドキュメントを参照してください。

ストリーミングプロパティ

これらのプロパティにより、モデルの出力を生成と同時にリアルタイムで参照できます：

fullStream:

ReadableStream<ChunkType<OUTPUT>>

ReadableStream

ChunkType:

ChunkType<OUTPUT>

ストリーミング中に出力されうるすべてのチャンクタイプ

textStream:

ReadableStream<string>

objectStream:

ReadableStream<PartialSchemaOutput<OUTPUT>>

ReadableStream

PartialSchemaOutput:

PartialSchemaOutput<OUTPUT>

定義済みスキーマに適合する未完成の部分オブジェクト

elementStream:

ReadableStream<InferSchemaOutput<OUTPUT> extends (infer T)[] ? T : never>

Promiseベースのプロパティ

これらのプロパティは、ストリームの完了後に最終値へと解決されます:

text:

Promise<string>

モデルからの連結済みの完全なテキスト応答。テキスト生成が完了すると解決されます。

object:

Promise<InferSchemaOutput<OUTPUT>>

出力スキーマ使用時の、完全な構造化オブジェクト応答。解決前にスキーマで検証され、検証に失敗した場合は拒否されます。

Promise

InferSchemaOutput:

InferSchemaOutput<OUTPUT>

スキーマ定義に厳密一致する完全型付けオブジェクト

reasoning:

Promise<string>

reasoning をサポートするモデル（OpenAI の o1 シリーズなど）における、完全な reasoning テキスト。reasoning 非対応のモデルでは空文字列を返します。

reasoningText:

Promise<string | undefined>

reasoning コンテンツへの別経路。reasoning 非対応のモデルでは undefined の可能性があり、一方で 'reasoning' は空文字列を返します。

toolCalls:

Promise<ToolCallChunk[]>

実行中に行われたすべてのツール呼び出しチャンクの配列。各チャンクにはツールのメタデータと実行詳細が含まれます。

ToolCallChunk

type:

'tool-call'

チャンク種別の識別子

runId:

string

実行ラン識別子

from:

ChunkFrom

チャンクの発生元（AGENT、WORKFLOW など）

payload:

ToolCallPayload

toolCallId、toolName、args、実行詳細を含むツール呼び出しデータ

toolResults:

Promise<ToolResultChunk[]>

ツール呼び出しに対応するすべてのツール結果チャンクの配列。実行結果およびエラー情報を含みます。

ToolResultChunk

type:

'tool-result'

チャンク種別の識別子

runId:

string

実行ラン識別子

from:

ChunkFrom

チャンクの発生元（AGENT、WORKFLOW など）

payload:

ToolResultPayload

toolCallId、toolName、result、エラー状態を含むツール結果データ

usage:

Promise<Record<string, number>>

入力トークン、出力トークン、合計トークン、reasoning トークン（reasoning モデルの場合）を含むトークン使用状況の統計。

Record

inputTokens:

number

入力プロンプトで消費したトークン数

outputTokens:

number

応答で生成されたトークン数

totalTokens:

number

入力トークンと出力トークンの合計

reasoningTokens?:

number

非公開の reasoning トークン（reasoning モデル向け）

finishReason:

Promise<string | undefined>

生成が停止した理由（例: 'stop'、'length'、'tool_calls'、'content_filter'）。ストリームが完了していない場合は undefined。

enum

stop:

'stop'

モデルが自然に完了

length:

'length'

最大トークン数に到達

tool_calls:

'tool_calls'

モデルがツールを呼び出した

content_filter:

'content_filter'

コンテンツがフィルタリングされた

エラーのプロパティ

error:

string | Error | { message: string; stack: string; } | undefined

メソッド

getFullOutput:

() => Promise<FullOutput>

FullOutput

text:

string

完全なテキスト応答

object?:

InferSchemaOutput<OUTPUT>

スキーマが提供された場合の構造化出力

toolCalls:

ToolCallChunk[]

実行されたすべてのツール呼び出しチャンク

toolResults:

ToolResultChunk[]

すべてのツール結果チャンク

usage:

Record<string, number>

トークン使用量の統計

reasoning?:

string

利用可能な場合の推論テキスト

finishReason?:

string

生成が終了した理由

consumeStream:

(options?: ConsumeStreamOptions) => Promise<void>

ConsumeStreamOptions

onError?:

(error: Error) => void

ストリームエラーを処理するためのコールバック

使い方の例

テキストの基本的なストリーミング


const stream = await agent.streamVNext("Write a haiku");
 
// 生成されるそばからテキストをストリーミングする
for await (const text of stream.textStream) {
  process.stdout.write(text);
}
 
// あるいは、全文をまとめて取得する
const fullText = await stream.text;
console.log(fullText);

構造化出力のストリーミング


const stream = await agent.streamVNext("Generate user data", {
  output: z.object({
    name: z.string(),
    age: z.number(),
    email: z.string()
  })
});
 
// 部分オブジェクトをストリーミング
for await (const partial of stream.objectStream) {
  console.log("進行状況:", partial); // { name: "John" }, { name: "John", age: 30 }, ...
}
 
// 検証済みの最終オブジェクトを取得
const user = await stream.object;
console.log("最終結果:", user); // { name: "John", age: 30, email: "john@example.com" }

ツールの呼び出しと結果


const stream = await agent.streamVNext("What's the weather in NYC?", {
  tools: { weather: weatherTool }
});
 
// ツール呼び出しをモニタリング
const toolCalls = await stream.toolCalls;
const toolResults = await stream.toolResults;
 
console.log("呼び出されたツール:", toolCalls);
console.log("結果:", toolResults);

出力の一括取得


const stream = await agent.streamVNext("Analyze this data");
 
const output = await stream.getFullOutput();
console.log({
  text: output.text,
  usage: output.usage,
  reasoning: output.reasoning,
  finishReason: output.finishReason
});

フルストリーム処理


const stream = await agent.streamVNext("Complex task");
 
for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      process.stdout.write(chunk.payload.text);
      break;
    case 'tool-call':
      console.log(`ツール ${chunk.payload.toolName} を呼び出し中...`);
      break;
    case 'reasoning-delta':
      console.log(`推論: ${chunk.payload.text}`);
      break;
    case 'finish':
      console.log(`完了！理由: ${chunk.payload.stepResult.reason}`);
      break;
  }
}

エラー処理


const stream = await agent.streamVNext("Analyze this data");
 
try {
  // オプション1: consumeStream 内でエラーを処理する
  await stream.consumeStream({
    onError: (error) => {
      console.error("ストリームエラー:", error);
    }
  });
  
  const result = await stream.text;
} catch (error) {
  console.error("結果の取得に失敗しました:", error);
}
 
// オプション2: error プロパティを確認する
const result = await stream.getFullOutput();
if (stream.error) {
  console.error("ストリームでエラーが発生しました:", stream.error);
}

MastraModelOutput

ストリーミングプロパティ

fullStream:

ChunkType:

textStream:

objectStream:

PartialSchemaOutput:

elementStream:

Promiseベースのプロパティ

text:

object:

InferSchemaOutput:

reasoning:

reasoningText:

toolCalls:

type:

runId:

from:

payload:

toolResults:

type:

runId:

from:

payload:

usage:

inputTokens:

outputTokens:

totalTokens:

reasoningTokens?:

finishReason:

stop:

length:

tool_calls:

content_filter:

エラーのプロパティ

error:

メソッド

getFullOutput:

text:

object?:

toolCalls:

toolResults:

usage:

reasoning?:

finishReason?:

consumeStream:

onError?:

使い方の例

テキストの基本的なストリーミング

構造化出力のストリーミング

ツールの呼び出しと結果

出力の一括取得

フルストリーム処理

エラー処理

関連する型

MastraModelOutput

ストリーミングプロパティ

fullStream:

ChunkType:

textStream:

objectStream:

PartialSchemaOutput:

elementStream:

Promiseベースのプロパティ

text:

object:

InferSchemaOutput:

reasoning:

reasoningText:

toolCalls:

type:

runId:

from:

payload:

toolResults:

type:

runId:

from:

payload:

usage: