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

請求資料，包括主體及其他資料

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

巢狀分塊資料，通常包含完成事件及用量統計資料

step-output

包含 Workflow 步驟執行輸出，主要用於追蹤用量及步驟完成事件。它與 tool-output 相似，但專門用於個別 Workflow 步驟。

type:

"step-output"

分塊類型識別碼

payload:

StepOutputPayload

Workflow 步驟執行輸出及中繼資料

StepOutputPayload

output:

ChunkType

步驟執行的巢狀分塊資料，通常包含完成事件或其他步驟結果

背景任務分塊

當 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、時間戳記及標頭）

watch

包含 Agent 執行的監察及可觀測性資料。視乎使用 stream() 的情境，可包括 Workflow 狀態資料、執行進度或其他執行階段詳情。

type:

"watch"

分塊類型識別碼

payload:

WatchPayload

用於 Agent 執行可觀測性及偵錯的監察資料

WatchPayload

workflowState?:

object

目前的 Workflow 執行狀態（用於 Workflow 時）

eventTimestamp?:

number

事件發生時的時間戳記

[key: string]:

any

其他監察及執行資料

goal

每次評估 Agent goal 時發出。取用者會用它在執行期間呈現評審進度及結果。未設定評審模型的目標不會產生 goal 分塊。

type:

"goal"

分塊類型識別碼

payload:

GoalEvaluationPayload

一次目標評估的結果

GoalEvaluationPayload

objective:

string

正在評審的目標

iteration:

number

目前已耗用的目標評估次數（此次評估後的 runsUsed）

maxRuns:

number

目標停止前的評估次數上限

passed:

boolean

目標是否被判定為完成

status:

"active" | "paused" | "done"

此次評估後的目標狀態

results:

ScorerResult[]

個別評分器結果

reason?:

string

評審意見或停止原因

duration:

number

目標評分檢查的總時長

timedOut:

boolean

評分是否逾時

maxRunsReached:

boolean

是否已達執行次數上限（maxRuns）

suppressFeedback:

boolean

是否禁止將目標意見訊息寫入記憶體

tripwire

當處理器封鎖內容而強制終止串流時發出。這是一項安全機制，可避免串流傳送有害或不當內容。酬載包含內容遭封鎖的原因，以及是否已要求重試。

type:

"tripwire"

分塊類型識別碼

payload:

TripwirePayload

串流因安全機制而終止的原因

TripwirePayload

reason:

string

內容遭封鎖的原因說明（例如「輸出處理器封鎖了內容」）

retry?:

boolean

處理器是否要求重試此步驟

metadata?:

unknown

處理器提供的其他中繼資料（例如分數、類別）

processorId?:

string

觸發 tripwire 的處理器 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 發出這些分塊之串流的方法