Skip to main content

Run.streamVNext() (Experimental)

Experimental

This feature is experimental and the API may change in future releases.

The .streamVNext() method enables real-time streaming of responses from a workflow. This enhanced streaming capability will eventually replace the current stream() method.

Usage example​

const run = await workflow.createRunAsync();

const stream = run.streamVNext({
  inputData: {
    value: "initial data",
  },
});

Parameters​

inputData?:

z.infer<TInput>
Input data that matches the workflow's input schema

runtimeContext?:

RuntimeContext
Runtime context data to use during workflow execution

tracingContext?:

TracingContext
AI tracing context for creating child spans and adding metadata.

currentSpan?:

AISpan
Current AI span for creating child spans and adding metadata.

tracingOptions?:

TracingOptions
Options for AI tracing configuration.

metadata?:

Record<string, any>
Metadata to add to the root trace span.

closeOnSuspend?:

boolean
Whether to close the stream when the workflow is suspended, or to keep the stream open until the workflow is finished (by success or error). Default value is true.

Returns​

stream:

MastraWorkflowStream<ChunkType>
A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties

stream.status:

Promise<RunStatus>
A promise that resolves to the current workflow run status

stream.result:

Promise<WorkflowResult<TState, TOutput, TSteps>>
A promise that resolves to the final workflow result

stream.usage:

Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>
A promise that resolves to token usage statistics

stream.traceId?:

string
The trace ID associated with this execution when AI tracing is enabled.

Extended usage example​

const run = await workflow.createRunAsync();

const stream = run.streamVNext({
  inputData: {
    value: "initial data",
  },
});

const result = await stream.result;

Stream Events​

The stream emits various event types during workflow execution. Each event has a type field and a payload containing relevant data:

  • workflow-start: Workflow execution begins
  • workflow-step-start: A step begins execution
  • workflow-step-output: Custom output from a step
  • workflow-step-result: A step completes with results
  • workflow-finish: Workflow execution completes with usage statistics