Skip to main content

ChunkType

The ChunkType type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.

Base PropertiesDirect link to Base Properties

All chunks include these base properties:

type:

string
The specific chunk type identifier

runId:

string
Unique identifier for this execution run

from:

ChunkFrom
Source of the chunk
enum

AGENT:

'AGENT'
Chunk from agent execution

USER:

'USER'
Chunk from user input

SYSTEM:

'SYSTEM'
Chunk from system processes

WORKFLOW:

'WORKFLOW'
Chunk from workflow execution

Text ChunksDirect link to Text Chunks

text-startDirect link to text-start

Signals the beginning of text generation.

type:

"text-start"
Chunk type identifier

payload:

TextStartPayload
Text start information
TextStartPayload

id:

string
Unique identifier for this text generation

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

text-deltaDirect link to text-delta

Incremental text content during generation.

type:

"text-delta"
Chunk type identifier

payload:

TextDeltaPayload
Incremental text content
TextDeltaPayload

id:

string
Unique identifier for this text generation

text:

string
The incremental text content

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

text-endDirect link to text-end

Signals the end of text generation.

type:

"text-end"
Chunk type identifier

payload:

TextEndPayload
Text end information
TextEndPayload

id:

string
Unique identifier for this text generation

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

Reasoning ChunksDirect link to Reasoning Chunks

reasoning-startDirect link to reasoning-start

Signals the beginning of reasoning generation (for models that support reasoning).

type:

"reasoning-start"
Chunk type identifier

payload:

ReasoningStartPayload
Reasoning start information
ReasoningStartPayload

id:

string
Unique identifier for this reasoning generation

signature?:

string
Reasoning signature if available

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

reasoning-deltaDirect link to reasoning-delta

Incremental reasoning text during generation.

type:

"reasoning-delta"
Chunk type identifier

payload:

ReasoningDeltaPayload
Incremental reasoning content
ReasoningDeltaPayload

id:

string
Unique identifier for this reasoning generation

text:

string
The incremental reasoning text

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

reasoning-endDirect link to reasoning-end

Signals the end of reasoning generation.

type:

"reasoning-end"
Chunk type identifier

payload:

ReasoningEndPayload
Reasoning end information
ReasoningEndPayload

id:

string
Unique identifier for this reasoning generation

signature?:

string
Final reasoning signature if available

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

reasoning-signatureDirect link to reasoning-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:

"reasoning-signature"
Chunk type identifier

payload:

ReasoningSignaturePayload
Metadata about the model's reasoning process characteristics
ReasoningSignaturePayload

id:

string
Unique identifier for the reasoning session

signature:

string
Signature describing the reasoning approach or effort level (e.g., reasoning effort settings)

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

Tool ChunksDirect link to Tool Chunks

tool-callDirect link to tool-call

A tool is being called.

type:

"tool-call"
Chunk type identifier

payload:

ToolCallPayload
Tool call information
ToolCallPayload

toolCallId:

string
Unique identifier for this tool call

toolName:

string
Name of the tool being called

args?:

Record<string, any>
Arguments passed to the tool

providerExecuted?:

boolean
Whether the provider executed the tool

output?:

any
Tool output if available

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

tool-resultDirect link to tool-result

Result from a tool execution.

type:

"tool-result"
Chunk type identifier

payload:

ToolResultPayload
Tool execution result
ToolResultPayload

toolCallId:

string
Unique identifier for the tool call

toolName:

string
Name of the executed tool

result:

any
The result of the tool execution

isError?:

boolean
Whether the result is an error

providerExecuted?:

boolean
Whether the provider executed the tool

args?:

Record<string, any>
Arguments that were passed to the tool

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

tool-call-input-streaming-startDirect link to tool-call-input-streaming-start

Signals the start of streaming tool call arguments.

type:

"tool-call-input-streaming-start"
Chunk type identifier

payload:

ToolCallInputStreamingStartPayload
Tool call input streaming start information
ToolCallInputStreamingStartPayload

toolCallId:

string
Unique identifier for this tool call

toolName:

string
Name of the tool being called

providerExecuted?:

boolean
Whether the provider executed the tool

dynamic?:

boolean
Whether the tool call is dynamic

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

tool-call-deltaDirect link to tool-call-delta

Incremental tool call arguments during streaming.

type:

"tool-call-delta"
Chunk type identifier

payload:

ToolCallDeltaPayload
Incremental tool call arguments
ToolCallDeltaPayload

argsTextDelta:

string
Incremental text delta for tool arguments

toolCallId:

string
Unique identifier for this tool call

toolName?:

string
Name of the tool being called

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

tool-call-input-streaming-endDirect link to tool-call-input-streaming-end

Signals the end of streaming tool call arguments.

type:

"tool-call-input-streaming-end"
Chunk type identifier

payload:

ToolCallInputStreamingEndPayload
Tool call input streaming end information
ToolCallInputStreamingEndPayload

toolCallId:

string
Unique identifier for this tool call

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

tool-errorDirect link to tool-error

An error occurred during tool execution.

type:

"tool-error"
Chunk type identifier

payload:

ToolErrorPayload
Tool error information
ToolErrorPayload

id?:

string
Optional identifier

toolCallId:

string
Unique identifier for the tool call

toolName:

string
Name of the tool that failed

args?:

Record<string, any>
Arguments that were passed to the tool

error:

unknown
The error that occurred

providerExecuted?:

boolean
Whether the provider executed the tool

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

Source and File ChunksDirect link to Source and File Chunks

sourceDirect link to source

Contains source information for content.

type:

"source"
Chunk type identifier

payload:

SourcePayload
Source information
SourcePayload

id:

string
Unique identifier

sourceType:

'url' | 'document'
Type of source

title:

string
Title of the source

mimeType?:

string
MIME type of the source

filename?:

string
Filename if applicable

url?:

string
URL if applicable

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

fileDirect link to file

Contains file data.

type:

"file"
Chunk type identifier

payload:

FilePayload
File data
FilePayload

data:

string | Uint8Array
The file data

base64?:

string
Base64 encoded data if applicable

mimeType:

string
MIME type of the file

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

Control ChunksDirect link to Control Chunks

startDirect link to start

Signals the start of streaming.

type:

"start"
Chunk type identifier

payload:

StartPayload
Start information
StartPayload

[key: string]:

any
Additional start data

step-startDirect link to step-start

Signals the start of a processing step.

type:

"step-start"
Chunk type identifier

payload:

StepStartPayload
Step start information
StepStartPayload

messageId?:

string
Optional message identifier

request:

object
Request information including body and other data

warnings?:

LanguageModelV2CallWarning[]
Any warnings from the language model call

step-finishDirect link to step-finish

Signals the completion of a processing step.

type:

"step-finish"
Chunk type identifier

payload:

StepFinishPayload
Step completion information
StepFinishPayload

id?:

string
Optional identifier

messageId?:

string
Optional message identifier

stepResult:

object
Step execution result with reason, warnings, and continuation info

output:

object
Output information including usage statistics

metadata:

object
Execution metadata including request and provider info

totalUsage?:

LanguageModelV2Usage
Total usage statistics

response?:

LanguageModelV2ResponseMetadata
Response metadata

providerMetadata?:

SharedV2ProviderMetadata
Provider-specific metadata

rawDirect link to raw

Contains raw data from the provider.

type:

"raw"
Chunk type identifier

payload:

RawPayload
Raw provider data
RawPayload

[key: string]:

any
Raw data from the provider

finishDirect link to finish

Stream has completed successfully.

type:

"finish"
Chunk type identifier

payload:

FinishPayload
Completion information
FinishPayload

stepResult:

object
Step execution result

output:

object
Output information including usage

metadata:

object
Execution metadata

messages:

object
Message history

errorDirect link to error

An error occurred during streaming.

type:

"error"
Chunk type identifier

payload:

ErrorPayload
Error information
ErrorPayload

error:

unknown
The error that occurred

abortDirect link to abort

Stream was aborted.

type:

"abort"
Chunk type identifier

payload:

AbortPayload
Abort information
AbortPayload

[key: string]:

any
Additional abort data

Object and Output ChunksDirect link to Object and Output Chunks

objectDirect link to object

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"
Chunk type identifier

object:

PartialSchemaOutput<OUTPUT>
Partial or complete structured data matching the defined schema. The type is determined by the OUTPUT schema parameter.

tool-outputDirect link to tool-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:

"tool-output"
Chunk type identifier

payload:

ToolOutputPayload
Wrapped execution output with metadata
ToolOutputPayload

output:

ChunkType
Nested chunk data, often containing finish events with usage statistics

step-outputDirect link to step-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:

"step-output"
Chunk type identifier

payload:

StepOutputPayload
Workflow step execution output with metadata
StepOutputPayload

output:

ChunkType
Nested chunk data from step execution, typically containing finish events or other step results

Metadata and Special ChunksDirect link to Metadata and Special Chunks

response-metadataDirect link to response-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:

"response-metadata"
Chunk type identifier

payload:

ResponseMetadataPayload
Provider response metadata for tracking and debugging
ResponseMetadataPayload

signature?:

string
Response signature if available

[key: string]:

any
Additional provider-specific metadata fields (e.g., id, modelId, timestamp, headers)

watchDirect link to watch

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:

"watch"
Chunk type identifier

payload:

WatchPayload
Monitoring data for observability and debugging of agent execution
WatchPayload

workflowState?:

object
Current workflow execution state (when used in workflows)

eventTimestamp?:

number
Timestamp when the event occurred

[key: string]:

any
Additional monitoring and execution data

tripwireDirect link to tripwire

Emitted when the stream is forcibly terminated due to content being blocked by output processors. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed.

type:

"tripwire"
Chunk type identifier

payload:

TripwirePayload
Information about why the stream was terminated by safety mechanisms
TripwirePayload

tripwireReason:

string
Explanation of why the content was blocked (e.g., 'Output processor blocked content')

Usage ExampleDirect link to Usage 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;
  }
}