ChunkType

ChunkType 型は、Agent のストリーミング応答中に出力できるストリームチャンクの Mastra 形式を定義します。

基本プロパティ

すべてのチャンクには、次の基本プロパティが含まれます。

type:

string

特定のチャンクタイプ識別子

runId:

string

この実行の一意な識別子

from:

ChunkFrom

チャンクの送信元

enum

AGENT:

'AGENT'

Agent の実行からのチャンク

USER:

'USER'

ユーザー入力からのチャンク

SYSTEM:

'SYSTEM'

システムプロセスからのチャンク

WORKFLOW:

'WORKFLOW'

Workflow の実行からのチャンク

テキストチャンク

text-start

テキスト生成の開始を示します。

type:

"text-start"

チャンクタイプ識別子

payload:

TextStartPayload

テキスト開始情報

TextStartPayload

id:

string

このテキスト生成の一意な識別子

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

text-delta

生成中の増分テキストコンテンツです。

type:

"text-delta"

チャンクタイプ識別子

payload:

TextDeltaPayload

増分テキストコンテンツ

TextDeltaPayload

id:

string

このテキスト生成の一意な識別子

text:

string

増分テキストコンテンツ

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

text-end

テキスト生成の終了を示します。

type:

"text-end"

チャンクタイプ識別子

payload:

TextEndPayload

テキスト終了情報

TextEndPayload

id:

string

このテキスト生成の一意な識別子

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

推論チャンク

reasoning-start

推論をサポートするモデルで、推論生成の開始を示します。

type:

"reasoning-start"

チャンクタイプ識別子

payload:

ReasoningStartPayload

推論開始情報

ReasoningStartPayload

id:

string

この推論生成の一意な識別子

signature?:

string

利用可能な場合の推論署名

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

reasoning-delta

生成中の増分推論テキストです。

type:

"reasoning-delta"

チャンクタイプ識別子

payload:

ReasoningDeltaPayload

増分推論コンテンツ

ReasoningDeltaPayload

id:

string

この推論生成の一意な識別子

text:

string

増分推論テキスト

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

reasoning-end

推論生成の終了を示します。

type:

"reasoning-end"

チャンクタイプ識別子

payload:

ReasoningEndPayload

推論終了情報

ReasoningEndPayload

id:

string

この推論生成の一意な識別子

signature?:

string

利用可能な場合の最終推論署名

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

reasoning-signature

高度な推論をサポートするモデル（OpenAI の o1 シリーズなど）からの推論署名を含みます。署名は、推論の労力レベルやアプローチなど、モデル内部の推論プロセスに関するメタデータを表しますが、実際の推論内容そのものは含みません。

type:

"reasoning-signature"

チャンクタイプ識別子

payload:

ReasoningSignaturePayload

モデルの推論プロセス特性に関するメタデータ

ReasoningSignaturePayload

id:

string

推論セッションの一意な識別子

signature:

string

推論のアプローチまたは労力レベル（推論労力の設定など）を表す署名

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

Tool チャンク

tool-call

Tool が呼び出されていることを示します。

type:

"tool-call"

チャンクタイプ識別子

payload:

ToolCallPayload

Tool 呼び出し情報

ToolCallPayload

toolCallId:

string

この Tool 呼び出しの一意な識別子

toolName:

string

呼び出される Tool の名前

args?:

Record<string, any>

Tool に渡される引数

providerExecuted?:

boolean

Provider が Tool を実行したかどうか

output?:

any

利用可能な場合の Tool 出力

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

tool-result

Tool の実行結果です。

type:

"tool-result"

チャンクタイプ識別子

payload:

ToolResultPayload

Tool の実行結果

ToolResultPayload

toolCallId:

string

Tool 呼び出しの一意な識別子

toolName:

string

実行された Tool の名前

result:

any

Tool の実行結果

isError?:

boolean

結果がエラーかどうか

providerExecuted?:

boolean

Provider が Tool を実行したかどうか

args?:

Record<string, any>

Tool に渡された引数

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

tool-call-input-streaming-start

Tool 呼び出し引数のストリーミング開始を示します。

type:

"tool-call-input-streaming-start"

チャンクタイプ識別子

payload:

ToolCallInputStreamingStartPayload

Tool 呼び出し入力のストリーミング開始情報

ToolCallInputStreamingStartPayload

toolCallId:

string

この Tool 呼び出しの一意な識別子

toolName:

string

呼び出される Tool の名前

providerExecuted?:

boolean

Provider が Tool を実行したかどうか

dynamic?:

boolean

Tool 呼び出しが動的かどうか

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

tool-call-delta

ストリーミング中の増分 Tool 呼び出し引数です。

type:

"tool-call-delta"

チャンクタイプ識別子

payload:

ToolCallDeltaPayload

増分 Tool 呼び出し引数

ToolCallDeltaPayload

argsTextDelta:

string

Tool 引数の増分テキスト差分

toolCallId:

string

この Tool 呼び出しの一意な識別子

toolName?:

string

呼び出される Tool の名前

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

tool-call-input-streaming-end

Tool 呼び出し引数のストリーミング終了を示します。

type:

"tool-call-input-streaming-end"

チャンクタイプ識別子

payload:

ToolCallInputStreamingEndPayload

Tool 呼び出し入力のストリーミング終了情報

ToolCallInputStreamingEndPayload

toolCallId:

string

この Tool 呼び出しの一意な識別子

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

tool-error

Tool の実行中にエラーが発生したことを示します。

type:

"tool-error"

チャンクタイプ識別子

payload:

ToolErrorPayload

Tool エラー情報

ToolErrorPayload

id?:

string

省略可能な識別子

toolCallId:

string

Tool 呼び出しの一意な識別子

toolName:

string

失敗した Tool の名前

args?:

Record<string, any>

Tool に渡された引数

error:

unknown

発生したエラー

providerExecuted?:

boolean

Provider が Tool を実行したかどうか

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

ソースおよびファイルチャンク

source

コンテンツのソース情報を含みます。

type:

"source"

チャンクタイプ識別子

payload:

SourcePayload

ソース情報

SourcePayload

id:

string

一意な識別子

sourceType:

'url' | 'document'

ソースの種類

title:

string

ソースのタイトル

mimeType?:

string

ソースの MIME タイプ

filename?:

string

該当する場合のファイル名

url?:

string

該当する場合の URL

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

file

ファイルデータを含みます。

type:

"file"

チャンクタイプ識別子

payload:

FilePayload

ファイルデータ

FilePayload

data:

string | Uint8Array

ファイルデータ

base64?:

string

該当する場合の Base64 エンコード済みデータ

mimeType:

string

ファイルの MIME タイプ

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

制御チャンク

start

ストリーミングの開始を示します。

type:

"start"

チャンクタイプ識別子

payload:

StartPayload

開始情報

StartPayload

[key: string]:

any

追加の開始データ

step-start

処理ステップの開始を示します。

type:

"step-start"

チャンクタイプ識別子

payload:

StepStartPayload

ステップ開始情報

StepStartPayload

messageId?:

string

省略可能なメッセージ識別子

request:

object

body およびその他のデータを含むリクエスト情報

warnings?:

LanguageModelV2CallWarning[]

言語モデル呼び出しからの警告

step-finish

処理ステップの完了を示します。

type:

"step-finish"

チャンクタイプ識別子

payload:

StepFinishPayload

ステップ完了情報

StepFinishPayload

id?:

string

省略可能な識別子

messageId?:

string

省略可能なメッセージ識別子

stepResult:

object

理由、警告、継続情報を含むステップ実行結果

output:

object

使用量統計を含む出力情報

metadata:

object

リクエストおよび Provider 情報を含む実行メタデータ

totalUsage?:

LanguageModelV2Usage

使用量の合計統計

response?:

LanguageModelV2ResponseMetadata

応答メタデータ

providerMetadata?:

SharedV2ProviderMetadata

Provider 固有のメタデータ

raw

Provider からの生データを含みます。

type:

"raw"

チャンクタイプ識別子

payload:

RawPayload

Provider の生データ

RawPayload

[key: string]:

any

Provider からの生データ

finish

ストリームが正常に完了したことを示します。

type:

"finish"

チャンクタイプ識別子

payload:

FinishPayload

完了情報

FinishPayload

stepResult:

object

ステップ実行結果

output:

object

使用量を含む出力情報

metadata:

object

実行メタデータ

messages:

object

メッセージ履歴

response:

object

モデル Provider からの応答メタデータとメッセージ

error

ストリーミング中にエラーが発生したことを示します。

type:

"error"

チャンクタイプ識別子

payload:

ErrorPayload

エラー情報

ErrorPayload

error:

unknown

発生したエラー

abort

ストリームが中断されたことを示します。

type:

"abort"

チャンクタイプ識別子

payload:

AbortPayload

中断情報

AbortPayload

[key: string]:

any

追加の中断データ

オブジェクトおよび出力チャンク

object

定義済みのスキーマを使用して出力を生成する場合に出力されます。指定された Zod または JSON スキーマに準拠する、部分的または完全な構造化データを含みます。このチャンクは一部の実行コンテキストでは通常スキップされ、構造化オブジェクト生成のストリーミングに使用されます。

type:

"object"

チャンクタイプ識別子

object:

Partial<OUTPUT>

定義済みスキーマに一致する部分的または完全な構造化データ。型は OUTPUT スキーマパラメーターによって決まります。

tool-output

Agent または Workflow の実行出力を含み、特に使用量統計と完了イベントの追跡に使用されます。ネストされた実行コンテキストを提供するため、finish チャンクなどの別のチャンクタイプをラップすることがあります。

type:

"tool-output"

チャンクタイプ識別子

payload:

ToolOutputPayload

メタデータを含むラップされた実行出力

ToolOutputPayload

output:

ChunkType

ネストされたチャンクデータ。多くの場合、使用量統計を含む finish イベントが格納されます

step-output

Workflow ステップの実行出力を含み、主に使用量の追跡とステップ完了イベントに使用されます。tool-output と似ていますが、個々の Workflow ステップ専用です。

type:

"step-output"

チャンクタイプ識別子

payload:

StepOutputPayload

メタデータを含む Workflow ステップの実行出力

StepOutputPayload

output:

ChunkType

ステップ実行からのネストされたチャンクデータ。通常は finish イベントまたはその他のステップ結果が格納されます

バックグラウンドタスクチャンク

Tool 呼び出しがバックグラウンドタスクとしてディスパッチされ、streamUntilIdle() が使用される場合に出力されます。

background-task-started

Tool 呼び出しがバックグラウンドタスクとしてキューに追加され、taskId が割り当てられたときに出力されます。

type:

"background-task-started"

チャンクタイプ識別子

payload:

BackgroundTaskStartedPayload

新しくキューに追加されたタスクを識別します

BackgroundTaskStartedPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行される Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

background-task-running

ワーカーがタスクを取得して実行を開始したときに出力されます。

type:

"background-task-running"

チャンクタイプ識別子

payload:

BackgroundTaskRunningPayload

実行中のタスクの詳細

BackgroundTaskRunningPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行される Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

startedAt:

Date

実行が開始されたタイムスタンプ

args:

Record<string, unknown>

Tool の execute 関数に渡された引数

background-task-progress

Agent 全体で現在実行中のバックグラウンドタスク数を示す定期的なスナップショットです。

type:

"background-task-progress"

チャンクタイプ識別子

payload:

BackgroundTaskProgressPayload

実行中のすべてのタスクの集約進捗

BackgroundTaskProgressPayload

taskIds:

string[]

現在実行中のすべてのバックグラウンドタスクの ID

runningCount:

number

現在実行中のバックグラウンドタスク数

elapsedMs:

number

Agent の実行開始から経過したミリ秒数

background-task-output

タスクの execute 関数が出力するストリーミング出力チャンクです。内部の tool-output チャンクをラップします。

type:

"background-task-output"

チャンクタイプ識別子

payload:

BackgroundTaskOutputPayload

実行中のタスクからのストリーミング出力

BackgroundTaskOutputPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行される Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

payload:

ToolOutputChunk

タスクが生成した内部の tool-output チャンク

background-task-completed

タスクが正常に完了したときに出力されます。Agent.streamUntilIdle() によって処理されると、継続ターンを開始します。

type:

"background-task-completed"

チャンクタイプ識別子

payload:

BackgroundTaskResultPayload

完了したタスクの結果

BackgroundTaskResultPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行された Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

agentId:

string

タスクをディスパッチした Agent の ID

runId:

string

タスクをディスパッチした Agent の実行 ID

result:

unknown

Tool の解決済み戻り値

completedAt:

Date

タスクが完了したタイムスタンプ

isError?:

boolean

Tool が例外をスローせずエラー結果を返した場合は true

background-task-failed

タスクが例外をスローするかタイムアウトしたときに出力されます。Agent.streamUntilIdle() によって処理されると、継続ターンを開始します。

type:

"background-task-failed"

チャンクタイプ識別子

payload:

BackgroundTaskFailedPayload

タスクの失敗に関する詳細

BackgroundTaskFailedPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行された Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

error:

{ message: string }

タスクがスローしたエラーの詳細

completedAt:

Date

タスクが失敗したタイムスタンプ

background-task-suspended

Tool がバックグラウンド実行内から suspend() を呼び出したときに出力されます。スナップショットを永続化した状態でタスクの Workflow 実行を一時停止します。再開するには mastra.backgroundTaskManager.resume(taskId, resumeData) を使用します。

Agent.streamUntilIdle() によって処理されると、このチャンクは継続処理をキューに追加せず、ループの待機セットからタスクを除外します。Agent の応答は終了し、再開されたタスクが最終的に完了すると、その結果が次のユーザーターン用のメッセージリストに挿入されます。

type:

"background-task-suspended"

チャンクタイプ識別子

payload:

BackgroundTaskSuspendedPayload

タスクの一時停止に関する詳細

BackgroundTaskSuspendedPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行された Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

suspendData?:

unknown

Tool が suspend(data) に渡した値

background-task-resumed

一時停止中のタスクが mastra.backgroundTaskManager.resume(taskId, resumeData) によって再開されたときに出力されます。タスクは running に戻り、resumeData が設定された状態で Tool の execute が再開されます。

type:

"background-task-resumed"

チャンクタイプ識別子

payload:

BackgroundTaskResumedPayload

タスクの再開に関する詳細

BackgroundTaskResumedPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行された Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

startedAt:

Date

タスクが再開されたタイムスタンプ

args:

Record<string, unknown>

元の Tool 引数

background-task-cancelled

タスクが完了前にキャンセルされたときに出力されます。Agent.streamUntilIdle() によって処理されると、継続ターンを開始します。

type:

"background-task-cancelled"

チャンクタイプ識別子

payload:

BackgroundTaskCancelledPayload

タスクのキャンセルに関する詳細

BackgroundTaskCancelledPayload

taskId:

string

バックグラウンドタスクの一意な識別子

toolName:

string

実行された Tool の名前

toolCallId:

string

元の LLM Tool 呼び出しの Tool 呼び出し ID

runId:

string

タスクをディスパッチした Agent の実行 ID

agentId:

string

タスクをディスパッチした Agent の ID

completedAt:

Date

タスクがキャンセルされたタイムスタンプ

メタデータおよび特殊チャンク

response-metadata

LLM Provider の応答に関するメタデータを含みます。一部の Provider からテキスト生成後に出力され、モデル ID、タイムスタンプ、応答ヘッダーなどの追加コンテキストを提供します。このチャンクは状態追跡のために内部で使用され、メッセージの組み立てには影響しません。

type:

"response-metadata"

チャンクタイプ識別子

payload:

ResponseMetadataPayload

追跡とデバッグに使用する Provider 応答メタデータ

ResponseMetadataPayload

signature?:

string

利用可能な場合の応答署名

[key: string]:

any

Provider 固有の追加メタデータフィールド（id、modelId、timestamp、headers など）

watch

Agent の実行から得られる監視およびオブザーバビリティデータを含みます。stream() が使用されるコンテキストに応じて、Workflow の状態情報、実行進捗、その他のランタイム詳細が含まれる場合があります。

type:

"watch"

チャンクタイプ識別子

payload:

WatchPayload

Agent 実行のオブザーバビリティとデバッグに使用する監視データ

WatchPayload

workflowState?:

object

Workflow で使用する場合の現在の実行状態

eventTimestamp?:

number

イベントが発生したタイムスタンプ

[key: string]:

any

追加の監視および実行データ

goal

Agent のゴールが評価されるたびに出力されます。コンシューマーはこれを使用して、判定の進捗と実行途中の結果をレンダリングします。判定モデルが設定されていないゴールからは goal チャンクが出力されません。

type:

"goal"

チャンクタイプ識別子

payload:

GoalEvaluationPayload

1 回のゴール評価の結果

GoalEvaluationPayload

objective:

string

判定対象の目標

iteration:

number

これまでに消費したゴール評価回数（この評価後の runsUsed）

maxRuns:

number

ゴールが停止するまでの最大評価回数

passed:

boolean

ゴールが完了したと判定されたかどうか

status:

"active" | "paused" | "done"

この評価後の目標ステータス

results:

ScorerResult[]

個々の Scorer の結果

reason?:

string

判定フィードバックまたは停止理由

duration:

number

ゴールのスコアリングチェックにかかった合計時間

timedOut:

boolean

スコアリングがタイムアウトしたかどうか

maxRunsReached:

boolean

実行回数の上限（maxRuns）に達したかどうか

suppressFeedback:

boolean

ゴールのフィードバックメッセージを Memory に保存しないかどうか

tripwire

Processor によってコンテンツがブロックされ、ストリームが強制終了されたときに出力されます。有害または不適切なコンテンツのストリーミングを防ぐ安全機構として機能します。payload には、コンテンツがブロックされた理由と、再試行が要求されたかどうかに関する情報が含まれます。

type:

"tripwire"

チャンクタイプ識別子

payload:

TripwirePayload

安全機構によってストリームが終了された理由に関する情報

TripwirePayload

reason:

string

コンテンツがブロックされた理由の説明（例：'Output processor blocked content'）

retry?:

boolean

Processor がステップの再試行を要求したかどうか

metadata?:

unknown

Processor からの追加メタデータ（スコア、カテゴリーなど）

processorId?:

string

tripwire をトリガーした Processor の ID

使用例

const stream = await agent.stream('Hello')

for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      console.log('Text:', chunk.payload.text)
      break

    case 'tool-call':
      console.log('Calling tool:', chunk.payload.toolName)
      break

    case 'tool-result':
      console.log('Tool result:', chunk.payload.result)
      break

    case 'reasoning-delta':
      console.log('Reasoning:', chunk.payload.text)
      break

    case 'finish':
      console.log('Finished:', chunk.payload.stepResult.reason)
      console.log('Usage:', chunk.payload.output.usage)
      break

    case 'error':
      console.error('Error:', chunk.payload.error)
      break
  }
}

関連する型

• .stream(): これらのチャンクを出力するストリームを返すメソッド
• MastraModelOutput: これらのチャンクを出力するストリームオブジェクト
• workflow.stream(): Workflow 用にこれらのチャンクを出力するストリームを返すメソッド