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

使用已定義 schema 的輸出生成時發出。包含符合指定 Zod 或 JSON schema 的部分或完整結構化資料。在某些執行情境中通常會略過此區塊；此區塊用於以串流方式生成結構化物件。

type:

"object"

區塊類型識別碼

object:

Partial<OUTPUT>

符合已定義 schema 的部分或完整結構化資料。型別由 OUTPUT schema 參數決定。

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 回傳錯誤結果而非擲回例外，則為真

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，接著重新啟動 Tool 的 execute，並填入 resumeData。

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 執行狀態（在 Workflow 中使用時）

eventTimestamp?:

number

事件發生時的時間戳記

[key: string]:

any

其他監控與執行資料

goal

每次評估 Agent 的目標時發出。取用端會使用此區塊呈現判定進度與執行期間的結果。未設定判定模型的目標不會產生 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 發出這些區塊之串流的方法