Skip to Content
ReferenceAgentsReference: Agent.streamVNext() | Streaming | Agents | Mastra Docs

streamVNext()

The streamVNext() method enables real-time streaming of responses from an agent. This method accepts messages and an optional options object as parameters, similar to generate().

Parameters

messages

The messages parameter can be:

  • A single string
  • An array of strings
  • An array of message objects with role and content properties

The message object structure:

interface Message {
  role: "system" | "user" | "assistant";
  content: string;
}

options (Optional)

An optional object that can include configuration for output structure, memory management, tool usage, telemetry, and more.

abortSignal?:

AbortSignal
Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.

context?:

CoreMessage[]
Additional context messages to provide to the agent.

experimental_output?:

Zod schema | JsonSchema7
Enables structured output generation alongside text generation and tool calls. The model will generate responses that conform to the provided schema.

instructions?:

string
Custom instructions that override the agent's default instructions for this specific generation. Useful for dynamically modifying agent behavior without creating a new agent instance.

memory?:

object
Configuration for memory. This is the preferred way to manage memory.

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }
The conversation thread, as a string ID or an object with an `id` and optional `metadata`.

resource:

string
Identifier for the user or resource associated with the thread.

options?:

MemoryConfig
Configuration for memory behavior, like message history and semantic recall. See `MemoryConfig` below.

maxSteps?:

number
= 5
Maximum number of steps allowed during streaming.

maxRetries?:

number
= 2
Maximum number of retries. Set to 0 to disable retries.

memoryOptions?:

MemoryConfig
**Deprecated.** Use `memory.options` instead. Configuration options for memory management. See MemoryConfig section below for details.

onFinish?:

StreamTextOnFinishCallback | StreamObjectOnFinishCallback
Callback function called when streaming is complete.

onStepFinish?:

GenerateTextOnStepFinishCallback<any> | never
Callback function called after each step during streaming. Unavailable for structured output

output?:

Zod schema | JsonSchema7
Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.

telemetry?:

TelemetrySettings
Settings for telemetry collection during streaming. See TelemetrySettings section below for details.

temperature?:

number
Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }
= 'auto'
Controls how the agent uses tools during streaming.

toolsets?:

ToolsetsInput
Additional toolsets to make available to the agent during this stream.

clientTools?:

ToolsInput
Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.

MemoryConfig

Configuration options for memory management:

lastMessages?:

number | false
Number of most recent messages to include in context. Set to false to disable.

semanticRecall?:

boolean | object
Configuration for semantic memory recall. Can be boolean or detailed config.
number

topK?:

number
Number of most semantically similar messages to retrieve.
number | object

messageRange?:

number | { before: number; after: number }
Range of messages to consider for semantic search. Can be a single number or before/after configuration.

workingMemory?:

object
Configuration for working memory.
boolean

enabled?:

boolean
Whether to enable working memory.
string

template?:

string
Template to use for working memory.

threads?:

object
Thread-specific memory configuration.
boolean | object

generateTitle?:

boolean | { model: LanguageModelV1 | ((ctx: RuntimeContext) => LanguageModelV1 | Promise<LanguageModelV1>), instructions: string | ((ctx: RuntimeContext) => string | Promise<string>) }
Controls automatic thread title generation from the user's first message. Can be a boolean to enable/disable using the agent's model, or an object specifying a custom model and/or custom instructions for title generation (useful for cost optimization or title customization). Example: { model: openai('gpt-4.1-nano'), instructions: 'Generate a concise title based on the initial user message.' }

TelemetrySettings

Settings for telemetry collection during streaming:

isEnabled?:

boolean
= false
Enable or disable telemetry. Disabled by default while experimental.

recordInputs?:

boolean
= true
Enable or disable input recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.

recordOutputs?:

boolean
= true
Enable or disable output recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.

functionId?:

string
Identifier for this function. Used to group telemetry data by function.

metadata?:

Record<string, AttributeValue>
Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.

tracer?:

Tracer
A custom OpenTelemetry tracer instance to use for the telemetry data. See OpenTelemetry documentation for details.

Protocol

start:

object
The agent starts
object

example:

{ type: 'start', runId: '1', from: 'AGENT', payload: {} }
Example message structure

step-start:

object
The start of a step
object

example:

{ type: 'step-start', runId: '1', from: 'AGENT', payload: { messageId: 'uuid', request: { /* Raw request object */ }, warnings: [] } }
Example message structure

tool-call:

object
The start of a tool call
object

example:

{ type: 'tool-call', runId: '1', from: 'AGENT', payload: { toolCallId: 'uuid', args: { ... }, toolName: 'my tool' } }
Example message structure

tool-output:

object
Custom output from a step
object

example:

{ type: 'tool-output', runId: '1', from: 'AGENT', payload: { toolName: 'my step', output: { ... }, toolCallId: 'uuid' } }
Example message structure

tool-result:

object
The result of a step
object

example:

{ type: 'tool-result', runId: '1', from: 'AGENT', payload: { toolCallId: 'uuid', result: { ... }, toolName: 'my tool' } }
Example message structure

step-finish:

object
The end of a step
object

example:

{ type: 'step-finish', runId: '1', from: 'AGENT', payload: { reason: 'stop', usage: { promptTokens: 100, completionTokens: 100, totalTokens: 200 }, response: Response, messageId: 'uuid', providerMetadata: { ... } } }
Example message structure

finish:

object
The end of the workflow
object

example:

{ type: 'finish', runId: '1', from: 'AGENT', payload: { totalUsage: { promptTokens: 100, completionTokens: 100, totalTokens: 200 } } }
Example message structure

Returns

The return value of the streamVNext() method is a custom MatraAgentStream. This stream extends a ReadableStream, so all basic stream methods are available.

PropertiesTable for Return Values

textStream?:

ReadableStream<string>
Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.

usage?:

Promise<object>
Total usage of the agent, including agents/workflows as a tool.
number

promptTokens?:

number
The number of prompt tokens used by the agent.
number

completionTokens?:

number
The number of completion tokens used by the agent.
number

totalTokens?:

number
The total number of tokens used by the agent.

finishReason?:

Promise<string>
The reason the agent stopped streaming.

toolCalls?:

Promise<object>
The tool calls made by the agent.

toolResults?:

Promise<object>
The tool results returned by the agent.

text?:

Promise<string>
The full text of the agent's response.

object?:

Promise<object>
The object of the agent's response, if you use output or experimental output.

Examples

Basic Text Streaming

const stream = await myAgent.streamVNext([
  { role: "user", content: "Tell me a story." },
]);
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

Structured Output Streaming with Thread Context

import { z } from "zod";
 
const schema = z.object({
  summary: z.string(),
  nextSteps: z.array(z.string()),
});
 
const response = await myAgent.streamVNext("What should we do next?", {
  output: schema,
  memory: {
    thread: "project-123",
  },
});
 
const result = await response.object;
console.log("Final structured result:", result);
getMemory()createTool()