> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # ChunkType `ChunkType` 型は、Agent のストリーミング応答中に出力できるストリームチャンクの Mastra 形式を定義します。 ## 基本プロパティ すべてのチャンクには、次の基本プロパティが含まれます。 **type** (`string`): 特定のチャンクタイプ識別子 **runId** (`string`): この実行の一意な識別子 **from** (`ChunkFrom`): チャンクの送信元 **from.AGENT** (`'AGENT'`): Agent の実行からのチャンク **from.USER** (`'USER'`): ユーザー入力からのチャンク **from.SYSTEM** (`'SYSTEM'`): システムプロセスからのチャンク **from.WORKFLOW** (`'WORKFLOW'`): Workflow の実行からのチャンク ## テキストチャンク ### text-start テキスト生成の開始を示します。 **type** (`"text-start"`): チャンクタイプ識別子 **payload** (`TextStartPayload`): テキスト開始情報 **payload.id** (`string`): このテキスト生成の一意な識別子 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### text-delta 生成中の増分テキストコンテンツです。 **type** (`"text-delta"`): チャンクタイプ識別子 **payload** (`TextDeltaPayload`): 増分テキストコンテンツ **payload.id** (`string`): このテキスト生成の一意な識別子 **payload.text** (`string`): 増分テキストコンテンツ **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### text-end テキスト生成の終了を示します。 **type** (`"text-end"`): チャンクタイプ識別子 **payload** (`TextEndPayload`): テキスト終了情報 **payload.id** (`string`): このテキスト生成の一意な識別子 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ## 推論チャンク ### reasoning-start 推論をサポートするモデルで、推論生成の開始を示します。 **type** (`"reasoning-start"`): チャンクタイプ識別子 **payload** (`ReasoningStartPayload`): 推論開始情報 **payload.id** (`string`): この推論生成の一意な識別子 **payload.signature** (`string`): 利用可能な場合の推論署名 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### reasoning-delta 生成中の増分推論テキストです。 **type** (`"reasoning-delta"`): チャンクタイプ識別子 **payload** (`ReasoningDeltaPayload`): 増分推論コンテンツ **payload.id** (`string`): この推論生成の一意な識別子 **payload.text** (`string`): 増分推論テキスト **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### reasoning-end 推論生成の終了を示します。 **type** (`"reasoning-end"`): チャンクタイプ識別子 **payload** (`ReasoningEndPayload`): 推論終了情報 **payload.id** (`string`): この推論生成の一意な識別子 **payload.signature** (`string`): 利用可能な場合の最終推論署名 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### reasoning-signature 高度な推論をサポートするモデル(OpenAI の o1 シリーズなど)からの推論署名を含みます。署名は、推論の労力レベルやアプローチなど、モデル内部の推論プロセスに関するメタデータを表しますが、実際の推論内容そのものは含みません。 **type** (`"reasoning-signature"`): チャンクタイプ識別子 **payload** (`ReasoningSignaturePayload`): モデルの推論プロセス特性に関するメタデータ **payload.id** (`string`): 推論セッションの一意な識別子 **payload.signature** (`string`): 推論のアプローチまたは労力レベル(推論労力の設定など)を表す署名 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ## Tool チャンク ### tool-call Tool が呼び出されていることを示します。 **type** (`"tool-call"`): チャンクタイプ識別子 **payload** (`ToolCallPayload`): Tool 呼び出し情報 **payload.toolCallId** (`string`): この Tool 呼び出しの一意な識別子 **payload.toolName** (`string`): 呼び出される Tool の名前 **payload.args** (`Record`): Tool に渡される引数 **payload.providerExecuted** (`boolean`): Provider が Tool を実行したかどうか **payload.output** (`any`): 利用可能な場合の Tool 出力 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### tool-result Tool の実行結果です。 **type** (`"tool-result"`): チャンクタイプ識別子 **payload** (`ToolResultPayload`): Tool の実行結果 **payload.toolCallId** (`string`): Tool 呼び出しの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.result** (`any`): Tool の実行結果 **payload.isError** (`boolean`): 結果がエラーかどうか **payload.providerExecuted** (`boolean`): Provider が Tool を実行したかどうか **payload.args** (`Record`): Tool に渡された引数 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### `tool-call-input-streaming-start` Tool 呼び出し引数のストリーミング開始を示します。 **type** (`"tool-call-input-streaming-start"`): チャンクタイプ識別子 **payload** (`ToolCallInputStreamingStartPayload`): Tool 呼び出し入力のストリーミング開始情報 **payload.toolCallId** (`string`): この Tool 呼び出しの一意な識別子 **payload.toolName** (`string`): 呼び出される Tool の名前 **payload.providerExecuted** (`boolean`): Provider が Tool を実行したかどうか **payload.dynamic** (`boolean`): Tool 呼び出しが動的かどうか **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### `tool-call-delta` ストリーミング中の増分 Tool 呼び出し引数です。 **type** (`"tool-call-delta"`): チャンクタイプ識別子 **payload** (`ToolCallDeltaPayload`): 増分 Tool 呼び出し引数 **payload.argsTextDelta** (`string`): Tool 引数の増分テキスト差分 **payload.toolCallId** (`string`): この Tool 呼び出しの一意な識別子 **payload.toolName** (`string`): 呼び出される Tool の名前 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### `tool-call-input-streaming-end` Tool 呼び出し引数のストリーミング終了を示します。 **type** (`"tool-call-input-streaming-end"`): チャンクタイプ識別子 **payload** (`ToolCallInputStreamingEndPayload`): Tool 呼び出し入力のストリーミング終了情報 **payload.toolCallId** (`string`): この Tool 呼び出しの一意な識別子 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### tool-error Tool の実行中にエラーが発生したことを示します。 **type** (`"tool-error"`): チャンクタイプ識別子 **payload** (`ToolErrorPayload`): Tool エラー情報 **payload.id** (`string`): 省略可能な識別子 **payload.toolCallId** (`string`): Tool 呼び出しの一意な識別子 **payload.toolName** (`string`): 失敗した Tool の名前 **payload.args** (`Record`): Tool に渡された引数 **payload.error** (`unknown`): 発生したエラー **payload.providerExecuted** (`boolean`): Provider が Tool を実行したかどうか **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ## ソースおよびファイルチャンク ### source コンテンツのソース情報を含みます。 **type** (`"source"`): チャンクタイプ識別子 **payload** (`SourcePayload`): ソース情報 **payload.id** (`string`): 一意な識別子 **payload.sourceType** (`'url' | 'document'`): ソースの種類 **payload.title** (`string`): ソースのタイトル **payload.mimeType** (`string`): ソースの MIME タイプ **payload.filename** (`string`): 該当する場合のファイル名 **payload.url** (`string`): 該当する場合の URL **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### file ファイルデータを含みます。 **type** (`"file"`): チャンクタイプ識別子 **payload** (`FilePayload`): ファイルデータ **payload.data** (`string | Uint8Array`): ファイルデータ **payload.base64** (`string`): 該当する場合の Base64 エンコード済みデータ **payload.mimeType** (`string`): ファイルの MIME タイプ **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ## 制御チャンク ### start ストリーミングの開始を示します。 **type** (`"start"`): チャンクタイプ識別子 **payload** (`StartPayload`): 開始情報 **payload.\[key: string]** (`any`): 追加の開始データ ### step-start 処理ステップの開始を示します。 **type** (`"step-start"`): チャンクタイプ識別子 **payload** (`StepStartPayload`): ステップ開始情報 **payload.messageId** (`string`): 省略可能なメッセージ識別子 **payload.request** (`object`): body およびその他のデータを含むリクエスト情報 **payload.warnings** (`LanguageModelV2CallWarning[]`): 言語モデル呼び出しからの警告 ### step-finish 処理ステップの完了を示します。 **type** (`"step-finish"`): チャンクタイプ識別子 **payload** (`StepFinishPayload`): ステップ完了情報 **payload.id** (`string`): 省略可能な識別子 **payload.messageId** (`string`): 省略可能なメッセージ識別子 **payload.stepResult** (`object`): 理由、警告、継続情報を含むステップ実行結果 **payload.output** (`object`): 使用量統計を含む出力情報 **payload.metadata** (`object`): リクエストおよび Provider 情報を含む実行メタデータ **payload.totalUsage** (`LanguageModelV2Usage`): 使用量の合計統計 **payload.response** (`LanguageModelV2ResponseMetadata`): 応答メタデータ **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 固有のメタデータ ### raw Provider からの生データを含みます。 **type** (`"raw"`): チャンクタイプ識別子 **payload** (`RawPayload`): Provider の生データ **payload.\[key: string]** (`any`): Provider からの生データ ### finish ストリームが正常に完了したことを示します。 **type** (`"finish"`): チャンクタイプ識別子 **payload** (`FinishPayload`): 完了情報 **payload.stepResult** (`object`): ステップ実行結果 **payload.output** (`object`): 使用量を含む出力情報 **payload.metadata** (`object`): 実行メタデータ **payload.messages** (`object`): メッセージ履歴 **payload.response** (`object`): モデル Provider からの応答メタデータとメッセージ ### error ストリーミング中にエラーが発生したことを示します。 **type** (`"error"`): チャンクタイプ識別子 **payload** (`ErrorPayload`): エラー情報 **payload.error** (`unknown`): 発生したエラー ### abort ストリームが中断されたことを示します。 **type** (`"abort"`): チャンクタイプ識別子 **payload** (`AbortPayload`): 中断情報 **payload.\[key: string]** (`any`): 追加の中断データ ## オブジェクトおよび出力チャンク ### object 定義済みのスキーマを使用して出力を生成する場合に出力されます。指定された Zod または JSON スキーマに準拠する、部分的または完全な構造化データを含みます。このチャンクは一部の実行コンテキストでは通常スキップされ、構造化オブジェクト生成のストリーミングに使用されます。 **type** (`"object"`): チャンクタイプ識別子 **object** (`Partial`): 定義済みスキーマに一致する部分的または完全な構造化データ。型は OUTPUT スキーマパラメーターによって決まります。 ### tool-output Agent または Workflow の実行出力を含み、特に使用量統計と完了イベントの追跡に使用されます。ネストされた実行コンテキストを提供するため、finish チャンクなどの別のチャンクタイプをラップすることがあります。 **type** (`"tool-output"`): チャンクタイプ識別子 **payload** (`ToolOutputPayload`): メタデータを含むラップされた実行出力 **payload.output** (`ChunkType`): ネストされたチャンクデータ。多くの場合、使用量統計を含む finish イベントが格納されます ### step-output Workflow ステップの実行出力を含み、主に使用量の追跡とステップ完了イベントに使用されます。tool-output と似ていますが、個々の Workflow ステップ専用です。 **type** (`"step-output"`): チャンクタイプ識別子 **payload** (`StepOutputPayload`): メタデータを含む Workflow ステップの実行出力 **payload.output** (`ChunkType`): ステップ実行からのネストされたチャンクデータ。通常は finish イベントまたはその他のステップ結果が格納されます ## バックグラウンドタスクチャンク Tool 呼び出しが[バックグラウンドタスク](https://mastra.zisheng.pro/ja/docs/long-running-agents/background-tasks)としてディスパッチされ、`streamUntilIdle()` が使用される場合に出力されます。 ### background-task-started Tool 呼び出しがバックグラウンドタスクとしてキューに追加され、`taskId` が割り当てられたときに出力されます。 **type** (`"background-task-started"`): チャンクタイプ識別子 **payload** (`BackgroundTaskStartedPayload`): 新しくキューに追加されたタスクを識別します **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行される Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID ### background-task-running ワーカーがタスクを取得して実行を開始したときに出力されます。 **type** (`"background-task-running"`): チャンクタイプ識別子 **payload** (`BackgroundTaskRunningPayload`): 実行中のタスクの詳細 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行される Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.startedAt** (`Date`): 実行が開始されたタイムスタンプ **payload.args** (`Record`): Tool の execute 関数に渡された引数 ### background-task-progress Agent 全体で現在実行中のバックグラウンドタスク数を示す定期的なスナップショットです。 **type** (`"background-task-progress"`): チャンクタイプ識別子 **payload** (`BackgroundTaskProgressPayload`): 実行中のすべてのタスクの集約進捗 **payload.taskIds** (`string[]`): 現在実行中のすべてのバックグラウンドタスクの ID **payload.runningCount** (`number`): 現在実行中のバックグラウンドタスク数 **payload.elapsedMs** (`number`): Agent の実行開始から経過したミリ秒数 ### background-task-output タスクの `execute` 関数が出力するストリーミング出力チャンクです。内部の [`tool-output`](#tool-output) チャンクをラップします。 **type** (`"background-task-output"`): チャンクタイプ識別子 **payload** (`BackgroundTaskOutputPayload`): 実行中のタスクからのストリーミング出力 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行される Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.payload** (`ToolOutputChunk`): タスクが生成した内部の tool-output チャンク ### background-task-completed タスクが正常に完了したときに出力されます。[`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/ja/reference/streaming/agents/streamUntilIdle) によって処理されると、継続ターンを開始します。 **type** (`"background-task-completed"`): チャンクタイプ識別子 **payload** (`BackgroundTaskResultPayload`): 完了したタスクの結果 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.result** (`unknown`): Tool の解決済み戻り値 **payload.completedAt** (`Date`): タスクが完了したタイムスタンプ **payload.isError** (`boolean`): Tool が例外をスローせずエラー結果を返した場合は true ### background-task-failed タスクが例外をスローするかタイムアウトしたときに出力されます。[`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/ja/reference/streaming/agents/streamUntilIdle) によって処理されると、継続ターンを開始します。 **type** (`"background-task-failed"`): チャンクタイプ識別子 **payload** (`BackgroundTaskFailedPayload`): タスクの失敗に関する詳細 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.error** (`{ message: string }`): タスクがスローしたエラーの詳細 **payload.completedAt** (`Date`): タスクが失敗したタイムスタンプ ### background-task-suspended Tool がバックグラウンド実行内から `suspend()` を呼び出したときに出力されます。スナップショットを永続化した状態でタスクの Workflow 実行を一時停止します。再開するには `mastra.backgroundTaskManager.resume(taskId, resumeData)` を使用します。 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/ja/reference/streaming/agents/streamUntilIdle) によって処理されると、このチャンクは継続処理をキューに追加せず、ループの待機セットからタスクを除外します。Agent の応答は終了し、再開されたタスクが最終的に完了すると、その結果が次のユーザーターン用のメッセージリストに挿入されます。 **type** (`"background-task-suspended"`): チャンクタイプ識別子 **payload** (`BackgroundTaskSuspendedPayload`): タスクの一時停止に関する詳細 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.suspendData** (`unknown`): Tool が suspend(data) に渡した値 ### background-task-resumed 一時停止中のタスクが `mastra.backgroundTaskManager.resume(taskId, resumeData)` によって再開されたときに出力されます。タスクは `running` に戻り、`resumeData` が設定された状態で Tool の `execute` が再開されます。 **type** (`"background-task-resumed"`): チャンクタイプ識別子 **payload** (`BackgroundTaskResumedPayload`): タスクの再開に関する詳細 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.startedAt** (`Date`): タスクが再開されたタイムスタンプ **payload.args** (`Record`): 元の Tool 引数 ### background-task-cancelled タスクが完了前にキャンセルされたときに出力されます。[`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/ja/reference/streaming/agents/streamUntilIdle) によって処理されると、継続ターンを開始します。 **type** (`"background-task-cancelled"`): チャンクタイプ識別子 **payload** (`BackgroundTaskCancelledPayload`): タスクのキャンセルに関する詳細 **payload.taskId** (`string`): バックグラウンドタスクの一意な識別子 **payload.toolName** (`string`): 実行された Tool の名前 **payload.toolCallId** (`string`): 元の LLM Tool 呼び出しの Tool 呼び出し ID **payload.runId** (`string`): タスクをディスパッチした Agent の実行 ID **payload.agentId** (`string`): タスクをディスパッチした Agent の ID **payload.completedAt** (`Date`): タスクがキャンセルされたタイムスタンプ ## メタデータおよび特殊チャンク ### response-metadata LLM Provider の応答に関するメタデータを含みます。一部の Provider からテキスト生成後に出力され、モデル ID、タイムスタンプ、応答ヘッダーなどの追加コンテキストを提供します。このチャンクは状態追跡のために内部で使用され、メッセージの組み立てには影響しません。 **type** (`"response-metadata"`): チャンクタイプ識別子 **payload** (`ResponseMetadataPayload`): 追跡とデバッグに使用する Provider 応答メタデータ **payload.signature** (`string`): 利用可能な場合の応答署名 **payload.\[key: string]** (`any`): Provider 固有の追加メタデータフィールド(id、modelId、timestamp、headers など) ### watch Agent の実行から得られる監視およびオブザーバビリティデータを含みます。`stream()` が使用されるコンテキストに応じて、Workflow の状態情報、実行進捗、その他のランタイム詳細が含まれる場合があります。 **type** (`"watch"`): チャンクタイプ識別子 **payload** (`WatchPayload`): Agent 実行のオブザーバビリティとデバッグに使用する監視データ **payload.workflowState** (`object`): Workflow で使用する場合の現在の実行状態 **payload.eventTimestamp** (`number`): イベントが発生したタイムスタンプ **payload.\[key: string]** (`any`): 追加の監視および実行データ ### goal Agent の[ゴール](https://mastra.zisheng.pro/ja/docs/long-running-agents/goals)が評価されるたびに出力されます。コンシューマーはこれを使用して、判定の進捗と実行途中の結果をレンダリングします。判定モデルが設定されていないゴールからは `goal` チャンクが出力されません。 **type** (`"goal"`): チャンクタイプ識別子 **payload** (`GoalEvaluationPayload`): 1 回のゴール評価の結果 **payload.objective** (`string`): 判定対象の目標 **payload.iteration** (`number`): これまでに消費したゴール評価回数(この評価後の runsUsed) **payload.maxRuns** (`number`): ゴールが停止するまでの最大評価回数 **payload.passed** (`boolean`): ゴールが完了したと判定されたかどうか **payload.status** (`"active" | "paused" | "done"`): この評価後の目標ステータス **payload.results** (`ScorerResult[]`): 個々の Scorer の結果 **payload.reason** (`string`): 判定フィードバックまたは停止理由 **payload.duration** (`number`): ゴールのスコアリングチェックにかかった合計時間 **payload.timedOut** (`boolean`): スコアリングがタイムアウトしたかどうか **payload.maxRunsReached** (`boolean`): 実行回数の上限(maxRuns)に達したかどうか **payload.suppressFeedback** (`boolean`): ゴールのフィードバックメッセージを Memory に保存しないかどうか ### tripwire Processor によってコンテンツがブロックされ、ストリームが強制終了されたときに出力されます。有害または不適切なコンテンツのストリーミングを防ぐ安全機構として機能します。payload には、コンテンツがブロックされた理由と、再試行が要求されたかどうかに関する情報が含まれます。 **type** (`"tripwire"`): チャンクタイプ識別子 **payload** (`TripwirePayload`): 安全機構によってストリームが終了された理由に関する情報 **payload.reason** (`string`): コンテンツがブロックされた理由の説明(例:'Output processor blocked content') **payload.retry** (`boolean`): Processor がステップの再試行を要求したかどうか **payload.metadata** (`unknown`): Processor からの追加メタデータ(スコア、カテゴリーなど) **payload.processorId** (`string`): tripwire をトリガーした Processor の ID ## 使用例 ```typescript 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()](https://mastra.zisheng.pro/ja/reference/streaming/agents/stream): これらのチャンクを出力するストリームを返すメソッド - [MastraModelOutput](https://mastra.zisheng.pro/ja/reference/streaming/agents/MastraModelOutput): これらのチャンクを出力するストリームオブジェクト - [workflow.stream()](https://mastra.zisheng.pro/ja/reference/streaming/workflows/stream): Workflow 用にこれらのチャンクを出力するストリームを返すメソッド