ChunkType
ChunkType 类型定义 Agent 在 Stream 响应期间可发出的 Mastra Chunk 格式。
基本属性基本属性的直接链接
所有 Chunk 都包含以下基本属性：
type:
string
特定Chunk类型标识符
runId:
string
此次执行的唯一标识符
from:
ChunkFrom
Chunk来源
enum
AGENT:
'AGENT'
来自 Agent 执行的Chunk
USER:
'USER'
来自用户输入的Chunk
SYSTEM:
'SYSTEM'
来自系统进程的Chunk
WORKFLOW:
'WORKFLOW'
来自 Workflow 执行的Chunk
文本Chunk文本Chunk的直接链接
text-starttext-start的直接链接
表示文本生成开始。
type:
"text-start"
Chunk类型标识符
payload:
TextStartPayload
文本开始数据
TextStartPayload
id:
string
此次文本生成的唯一标识符
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
text-deltatext-delta的直接链接
生成期间逐步产生的文本内容。
type:
"text-delta"
Chunk类型标识符
payload:
TextDeltaPayload
逐步产生的文本内容
TextDeltaPayload
id:
string
此次文本生成的唯一标识符
text:
string
逐步产生的文本内容
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
text-endtext-end的直接链接
表示文本生成结束。
type:
"text-end"
Chunk类型标识符
payload:
TextEndPayload
文本结束数据
TextEndPayload
id:
string
此次文本生成的唯一标识符
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
推理Chunk推理Chunk的直接链接
reasoning-startreasoning-start的直接链接
表示推理生成开始（适用于支持推理的模型）。
type:
"reasoning-start"
Chunk类型标识符
payload:
ReasoningStartPayload
推理开始数据
ReasoningStartPayload
id:
string
此次推理生成的唯一标识符
signature?:
string
推理签署（如有）
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
reasoning-deltareasoning-delta的直接链接
生成期间逐步产生的推理文本。
type:
"reasoning-delta"
Chunk类型标识符
payload:
ReasoningDeltaPayload
逐步产生的推理内容
ReasoningDeltaPayload
id:
string
此次推理生成的唯一标识符
text:
string
逐步产生的推理文本
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
reasoning-endreasoning-end的直接链接
表示推理生成结束。
type:
"reasoning-end"
Chunk类型标识符
payload:
ReasoningEndPayload
推理结束数据
ReasoningEndPayload
id:
string
此次推理生成的唯一标识符
signature?:
string
最终推理签署（如有）
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
reasoning-signaturereasoning-signature的直接链接
包含支持进阶推理的模型（例如 OpenAI o1 系列）所产生的推理签署。签署代表模型内部推理过程的元数据，例如投入程度或推理方式，但不包含实际推理内容。
type:
"reasoning-signature"
Chunk类型标识符
payload:
ReasoningSignaturePayload
描述模型推理过程特征的元数据
ReasoningSignaturePayload
id:
string
推理工作阶段的唯一标识符
signature:
string
描述 reasoning 方法或投入级别的 signature（例如 reasoning effort 设置）
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
Tool ChunkTool Chunk的直接链接
tool-calltool-call的直接链接
正在调用 Tool。
type:
"tool-call"
Chunk类型标识符
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-resulttool-result的直接链接
Tool 执行结果。
type:
"tool-result"
Chunk类型标识符
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-starttool-call-input-streaming-start的直接链接
表示开始以Stream方式传送 Tool 调用参数。
type:
"tool-call-input-streaming-start"
Chunk类型标识符
payload:
ToolCallInputStreamingStartPayload
Tool 调用输入Stream开始数据
ToolCallInputStreamingStartPayload
toolCallId:
string
此次 Tool 调用的唯一标识符
toolName:
string
正在调用的 Tool 名称
providerExecuted?:
boolean
Provider 是否已执行 Tool
dynamic?:
boolean
Tool 调用是否为动态
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
tool-call-deltatool-call-delta的直接链接
Stream期间逐步产生的 Tool 调用参数。
type:
"tool-call-delta"
Chunk类型标识符
payload:
ToolCallDeltaPayload
逐步产生的 Tool 调用参数
ToolCallDeltaPayload
argsTextDelta:
string
Tool 参数的逐步文本差异
toolCallId:
string
此次 Tool 调用的唯一标识符
toolName?:
string
正在调用的 Tool 名称
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
tool-call-input-streaming-endtool-call-input-streaming-end的直接链接
表示结束以Stream方式传送 Tool 调用参数。
type:
"tool-call-input-streaming-end"
Chunk类型标识符
payload:
ToolCallInputStreamingEndPayload
Tool 调用输入Stream结束数据
ToolCallInputStreamingEndPayload
toolCallId:
string
此次 Tool 调用的唯一标识符
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
tool-errortool-error的直接链接
执行 Tool 时发生错误。
type:
"tool-error"
Chunk类型标识符
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 特定的元数据
来源及文档Chunk来源及文档Chunk的直接链接
sourcesource的直接链接
包含内容的来源数据。
type:
"source"
Chunk类型标识符
payload:
SourcePayload
来源数据
SourcePayload
id:
string
唯一标识符
sourceType:
'url' | 'document'
来源类型
title:
string
来源标题
mimeType?:
string
来源的 MIME 类型
filename?:
string
文档名称（如适用）
url?:
string
URL（如适用）
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
filefile的直接链接
包含文档数据。
type:
"file"
Chunk类型标识符
payload:
FilePayload
文档数据
FilePayload
data:
string | Uint8Array
文档数据
base64?:
string
Base64 编码数据（如适用）
mimeType:
string
文档的 MIME 类型
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
控制Chunk控制Chunk的直接链接
startstart的直接链接
表示Stream开始。
type:
"start"
Chunk类型标识符
payload:
StartPayload
开始数据
StartPayload
[key: string]:
any
其他开始数据
step-startstep-start的直接链接
表示处理步骤开始。
type:
"step-start"
Chunk类型标识符
payload:
StepStartPayload
步骤开始数据
StepStartPayload
messageId?:
string
可选消息标识符
request:
object
请求数据，包括主体及其他数据
warnings?:
LanguageModelV2CallWarning[]
语言模型调用传回的任何警告
step-finishstep-finish的直接链接
表示处理步骤完成。
type:
"step-finish"
Chunk类型标识符
payload:
StepFinishPayload
步骤完成数据
StepFinishPayload
id?:
string
可选标识符
messageId?:
string
可选消息标识符
stepResult:
object
步骤执行结果，包括原因、警告及延续数据
output:
object
输出数据，包括用量统计信息
metadata:
object
执行元数据，包括请求及 Provider 数据
totalUsage?:
LanguageModelV2Usage
总用量统计数据
response?:
LanguageModelV2ResponseMetadata
回应元数据
providerMetadata?:
SharedV2ProviderMetadata
Provider 特定的元数据
rawraw的直接链接
包含 Provider 的原始数据。
type:
"raw"
Chunk类型标识符
payload:
RawPayload
Provider 原始数据
RawPayload
[key: string]:
any
来自 Provider 的原始数据
finishfinish的直接链接
Stream已成功完成。
type:
"finish"
Chunk类型标识符
payload:
FinishPayload
完成数据
FinishPayload
stepResult:
object
步骤执行结果
output:
object
输出数据，包括用量信息
metadata:
object
执行元数据
messages:
object
消息记录
response:
object
模型 Provider 的回应元数据及消息
errorerror的直接链接
Stream期间发生错误。
type:
"error"
Chunk类型标识符
payload:
ErrorPayload
错误数据
ErrorPayload
error:
unknown
发生的错误
abortabort的直接链接
Stream已中止。
type:
"abort"
Chunk类型标识符
payload:
AbortPayload
中止数据
AbortPayload
[key: string]:
any
其他中止数据
对象及输出Chunk对象及输出Chunk的直接链接
objectobject的直接链接
使用已定义结构描述生成输出时发出。包含符合指定 Zod 或 JSON 结构描述的部分或完整结构化数据。在部分执行上下文中通常会略过此Chunk；此Chunk用于以Stream方式生成结构化对象。
type:
"object"
Chunk类型标识符
object:
Partial<OUTPUT>
符合指定结构描述的部分或完整结构化数据。类型由 OUTPUT 结构描述参数决定。
tool-outputtool-output的直接链接
包含 Agent 或 Workflow 执行输出，尤其用于追踪用量统计数据及完成事件。它通常会包装其他Chunk类型（例如 finish Chunk），以提供嵌套执行上下文。
type:
"tool-output"
Chunk类型标识符
payload:
ToolOutputPayload
经包装的执行输出及元数据
ToolOutputPayload
output:
ChunkType
嵌套Chunk数据，通常包含完成事件及用量统计数据
step-outputstep-output的直接链接
包含 Workflow 步骤执行输出，主要用于追踪用量及步骤完成事件。它与 tool-output 相似，但专门用于个别 Workflow 步骤。
type:
"step-output"
Chunk类型标识符
payload:
StepOutputPayload
Workflow 步骤执行输出及元数据
StepOutputPayload
output:
ChunkType
步骤执行的嵌套Chunk数据，通常包含完成事件或其他步骤结果
背景任务Chunk背景任务Chunk的直接链接
当 Tool 调用以背景任务方式派送，并使用 streamUntilIdle() 时发出。
background-task-startedbackground-task-started的直接链接
当 Tool 调用排入背景任务队列并获指派 taskId 时发出。
type:
"background-task-started"
Chunk类型标识符
payload:
BackgroundTaskStartedPayload
识别新排入队列的任务
BackgroundTaskStartedPayload
taskId:
string
背景任务的唯一标识符
toolName:
string
正在执行的 Tool 名称
toolCallId:
string
源自原始 LLM Tool 调用的 Tool 调用 ID
background-task-runningbackground-task-running的直接链接
当 worker 接手任务并开始执行时发出。
type:
"background-task-running"
Chunk类型标识符
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-progressbackground-task-progress的直接链接
定期提供 Agent 中目前执行之背景任务数目的快照。
type:
"background-task-progress"
Chunk类型标识符
payload:
BackgroundTaskProgressPayload
所有执行中任务的整体进度
BackgroundTaskProgressPayload
taskIds:
string[]
所有目前执行中背景任务的 ID
runningCount:
number
当前正在运行的后台任务数量
elapsedMs:
number
Agent 开始执行后经过的毫秒数
background-task-outputbackground-task-output的直接链接
由任务的 execute 函数发出的Stream输出 chunk，包装了一个内部 tool-output chunk。
type:
"background-task-output"
Chunk类型标识符
payload:
BackgroundTaskOutputPayload
执行中任务的Stream输出
BackgroundTaskOutputPayload
taskId:
string
背景任务的唯一标识符
toolName:
string
正在执行的 Tool 名称
toolCallId:
string
源自原始 LLM Tool 调用的 Tool 调用 ID
runId:
string
派送任务之 Agent 的执行 ID
agentId:
string
派送任务之 Agent 的 ID
payload:
ToolOutputChunk
任务产生的内部 tool-output Chunk
background-task-completedbackground-task-completed的直接链接
任务成功完成时发出。由 Agent.streamUntilIdle() 取用时会触发延续回合。
type:
"background-task-completed"
Chunk类型标识符
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-failedbackground-task-failed的直接链接
任务抛回例外或超时时发出。由 Agent.streamUntilIdle() 取用时会触发延续回合。
type:
"background-task-failed"
Chunk类型标识符
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-suspendedbackground-task-suspended的直接链接
当 Tool 在背景执行期间调用 suspend() 时发出。它会暂停任务的 Workflow 执行并保留快照。请使用 mastra.backgroundTaskManager.resume(taskId, resumeData) 恢复。
由 Agent.streamUntilIdle() 取用时，此Chunk会将任务从循圈的等待集合移除，而不会排入延续操作。Agent 回应随即结束；恢复后的任务最终完成时，结果会加入下一个用户回合的消息清单。
type:
"background-task-suspended"
Chunk类型标识符
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-resumedbackground-task-resumed的直接链接
通过 mastra.backgroundTaskManager.resume(taskId, resumeData) 恢复已暂停的任务时发出。任务会转回 running，并以已填入的 resumeData 重新启动 Tool 的 execute。
type:
"background-task-resumed"
Chunk类型标识符
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-cancelledbackground-task-cancelled的直接链接
任务在完成前遭取消时发出。由 Agent.streamUntilIdle() 取用时会触发延续回合。
type:
"background-task-cancelled"
Chunk类型标识符
payload:
BackgroundTaskCancelledPayload
任务取消详情
BackgroundTaskCancelledPayload
taskId:
string
背景任务的唯一标识符
toolName:
string
已执行的 Tool 名称
toolCallId:
string
源自原始 LLM Tool 调用的 Tool 调用 ID
runId:
string
派送任务之 Agent 的执行 ID
agentId:
string
派送任务之 Agent 的 ID
completedAt:
Date
任务取消时的时间戳记
元数据及特殊Chunk元数据及特殊Chunk的直接链接
response-metadataresponse-metadata的直接链接
包含 LLM Provider 回应的元数据。部分 Provider 会在文本生成后发出此Chunk，以提供模型 ID、时间戳记及回应标头等额外上下文。此Chunk在内部用于追踪状态，不会影响消息组合。
type:
"response-metadata"
Chunk类型标识符
payload:
ResponseMetadataPayload
用于追踪及侦错的 Provider 回应元数据
ResponseMetadataPayload
signature?:
string
回应 signature（如有）
[key: string]:
any
其他 Provider 特定的元数据字段（例如 id、modelId、时间戳和 headers）
watchwatch的直接链接
包含 Agent 执行的监察及可观测性数据。视乎使用 stream() 的上下文，可包括 Workflow 状态数据、执行进度或其他执行阶段详情。
type:
"watch"
Chunk类型标识符
payload:
WatchPayload
用于 Agent 执行可观测性及侦错的监察数据
WatchPayload
workflowState?:
object
当前 Workflow 的执行状态（用于 Workflow 时）
eventTimestamp?:
number
事件发生时的时间戳记
[key: string]:
any
其他监察及执行数据
goalgoal的直接链接
每次评估 Agent goal 时发出。取用者会用它在执行期间呈现评审进度及结果。未设定评审模型的目标不会产生 goal Chunk。
type:
"goal"
Chunk类型标识符
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
是否禁止将目标意见消息写入记忆体
tripwiretripwire的直接链接
当处理器封锁内容而强制终止Stream时发出。这是一项安全机制，可避免Stream传送有害或不当内容。payload包含内容遭封锁的原因，以及是否已要求重试。
type:
"tripwire"
Chunk类型标识符
payload:
TripwirePayload
Stream因安全机制而终止的原因
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()：传回会发出这些Chunk之Stream的方法
- MastraModelOutput：发出这些Chunk的Stream对象
- workflow.stream()：传回会为 Workflow 发出这些Chunk之Stream的方法