ChunkType
The ChunkType type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.
Base propertiesBase properties的直接链接
All chunks include these base properties:
type:
runId:
traceId?:
from:
AGENT:
USER:
SYSTEM:
WORKFLOW:
Text chunksText chunks的直接链接
text-starttext-start的直接链接
Signals the beginning of text generation.
type:
payload:
id:
providerMetadata?:
text-deltatext-delta的直接链接
Incremental text content during generation.
type:
payload:
id:
text:
providerMetadata?:
text-endtext-end的直接链接
Signals the end of text generation.
type:
payload:
id:
providerMetadata?:
Reasoning chunksReasoning chunks的直接链接
reasoning-startreasoning-start的直接链接
Signals the beginning of reasoning generation (for models that support reasoning).
type:
payload:
id:
signature?:
providerMetadata?:
reasoning-deltareasoning-delta的直接链接
Incremental reasoning text during generation.
type:
payload:
id:
text:
providerMetadata?:
reasoning-endreasoning-end的直接链接
Signals the end of reasoning generation.
type:
payload:
id:
signature?:
providerMetadata?:
reasoning-signaturereasoning-signature的直接链接
Contains the reasoning signature from models that support advanced reasoning (like OpenAI's o1 series). The signature represents metadata about the model's internal reasoning process, such as effort level or reasoning approach, but not the actual reasoning content itself.
type:
payload:
id:
signature:
providerMetadata?:
Tool chunksTool chunks的直接链接
tool-calltool-call的直接链接
A tool is being called.
type:
payload:
toolCallId:
toolName:
title?:
args?:
providerExecuted?:
output?:
providerMetadata?:
tool-resulttool-result的直接链接
Result from a tool execution.
type:
payload:
toolCallId:
toolName:
result:
isError?:
providerExecuted?:
args?:
providerMetadata?:
tool-call-input-streaming-starttool-call-input-streaming-start的直接链接
Signals the start of streaming tool call arguments.
type:
payload:
toolCallId:
toolName:
title?:
providerExecuted?:
dynamic?:
providerMetadata?:
tool-call-deltatool-call-delta的直接链接
Incremental tool call arguments during streaming.
type:
payload:
argsTextDelta:
toolCallId:
toolName?:
providerMetadata?:
tool-call-input-streaming-endtool-call-input-streaming-end的直接链接
Signals the end of streaming tool call arguments.
type:
payload:
toolCallId:
providerMetadata?:
tool-errortool-error的直接链接
An error occurred during tool execution.
type:
payload:
id?:
toolCallId:
toolName:
args?:
error:
providerExecuted?:
providerMetadata?:
Source and file chunksSource and file chunks的直接链接
sourcesource的直接链接
Contains source information for content.
type:
payload:
id:
sourceType:
title:
mimeType?:
filename?:
url?:
providerMetadata?:
filefile的直接链接
Contains file data.
type:
payload:
data:
base64?:
mimeType:
providerMetadata?:
reasoning-filereasoning-file的直接链接
Contains a file generated by the model as part of its reasoning. Emitted by providers on the AI SDK v7 specification.
type:
payload:
data:
base64?:
mimeType:
providerMetadata?:
Control chunksControl chunks的直接链接
customcustom的直接链接
Contains a provider-specific content block that doesn't map to any other standardized chunk type. Emitted by providers on the AI SDK v7 specification.
type:
payload:
kind:
{provider}.{provider-type}providerMetadata?:
startstart的直接链接
Signals the start of streaming.
type:
payload:
[key: string]:
step-startstep-start的直接链接
Signals the start of a processing step.
type:
payload:
messageId?:
modelId?:
provider?:
request:
warnings?:
step-finishstep-finish的直接链接
Signals the completion of a processing step.
type:
payload:
id?:
messageId?:
stepResult:
rawReason holds the provider's own finish reason when it reports one.output:
metadata:
totalUsage?:
response?:
providerMetadata?:
rawraw的直接链接
Contains raw data from the provider, including content types Mastra doesn't recognize, which are emitted as raw chunks rather than discarded. Raw chunks only appear when includeRawChunks is enabled.
type:
payload:
[key: string]:
finishfinish的直接链接
Stream has completed.
type:
payload:
stepResult:
reason holds the normalized finish reason, and rawReason holds the provider's own finish reason when it reports one. A reason of "error" means the run failed.output:
metadata:
messages:
response:
errorerror的直接链接
An error occurred during streaming.
type:
payload:
error:
abortabort的直接链接
Stream was aborted.
type:
payload:
[key: string]:
Object and output chunksObject and output chunks的直接链接
objectobject的直接链接
Emitted when using output generation with defined schemas. Contains partial or complete structured data that conforms to the specified Zod or JSON schema. This chunk is typically skipped in some execution contexts and used for streaming structured object generation.
type:
object:
tool-outputtool-output的直接链接
Contains output from agent or workflow execution, particularly used for tracking usage statistics and completion events. Often wraps other chunk types (like finish chunks) to provide nested execution context.
type:
payload:
output:
step-outputstep-output的直接链接
Contains output from workflow step execution, used primarily for usage tracking and step completion events. Similar to tool-output but specifically for individual workflow steps.
type:
payload:
output:
Background task chunksBackground task chunks的直接链接
Emitted when a tool call is dispatched as a background task and streamUntilIdle() is used.
background-task-startedbackground-task-started的直接链接
Emitted when a tool call is enqueued as a background task and assigned a taskId.
type:
payload:
taskId:
toolName:
toolCallId:
background-task-runningbackground-task-running的直接链接
Emitted when a worker picks up the task and execution begins.
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
startedAt:
args:
background-task-progressbackground-task-progress的直接链接
Periodic snapshot of how many background tasks are currently running across the agent.
type:
payload:
taskIds:
runningCount:
elapsedMs:
background-task-outputbackground-task-output的直接链接
A streamed output chunk emitted by the task's execute function. Wraps an inner tool-output chunk.
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
payload:
background-task-completedbackground-task-completed的直接链接
Emitted when the task finishes successfully. Triggers a continuation turn when consumed by Agent.streamUntilIdle().
type:
payload:
taskId:
toolName:
toolCallId:
agentId:
runId:
result:
completedAt:
isError?:
background-task-failedbackground-task-failed的直接链接
Emitted when the task throws or times out. Triggers a continuation turn when consumed by Agent.streamUntilIdle().
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
error:
completedAt:
background-task-suspendedbackground-task-suspended的直接链接
Emitted when a tool calls suspend() from inside its background execution. Pauses the task's workflow run with its snapshot persisted. Resume with mastra.backgroundTaskManager.resume(taskId, resumeData).
When consumed by Agent.streamUntilIdle(), this chunk drops the task from the loop's wait set without queuing a continuation. The agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
suspendData?:
suspend(data)background-task-resumedbackground-task-resumed的直接链接
Emitted when a suspended task is resumed via mastra.backgroundTaskManager.resume(taskId, resumeData). The task transitions back to running and the tool's execute is restarted with resumeData populated.
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
startedAt:
args:
background-task-cancelledbackground-task-cancelled的直接链接
Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by Agent.streamUntilIdle().
type:
payload:
taskId:
toolName:
toolCallId:
runId:
agentId:
completedAt:
Metadata and special chunksMetadata and special chunks的直接链接
response-metadataresponse-metadata的直接链接
Contains metadata about the LLM provider's response. Emitted by some providers after text generation to provide additional context like model ID, timestamps, and response headers. This chunk is used internally for state tracking and doesn't affect message assembly.
type:
payload:
signature?:
[key: string]:
watchwatch的直接链接
Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where stream() is used.
type:
payload:
workflowState?:
eventTimestamp?:
[key: string]:
goalgoal的直接链接
Emitted on every evaluation of an agent goal. Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no goal chunk.
type:
payload:
objective:
iteration:
maxRuns:
passed:
status:
results:
reason?:
duration:
timedOut:
maxRunsReached:
suppressFeedback:
tripwiretripwire的直接链接
Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
type:
payload:
reason:
retry?:
metadata?:
processorId?:
Usage exampleUsage example的直接链接
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
}
}
Related typesRelated types的直接链接
- .stream(): Method that returns streams emitting these chunks
- MastraModelOutput: The stream object that emits these chunks
- workflow.stream(): Method that returns streams emitting these chunks for workflows