streamText

Streams text generations from a language model.

You can use the streamText function for interactive use cases such as chat bots and other real-time applications. You can also generate UI components with tools.

import { streamText } from 'ai';

const { textStream } = streamText({
  model: "anthropic/claude-sonnet-5.5",
  prompt: 'Invent a new holiday and describe its traditions.',
});

for await (const textPart of textStream) {
  process.stdout.write(textPart);
}

For guidance on runtimeContext, toolsContext, tool context, and sensitive context filtering, see Runtime and Tool Context.

To see streamText in action, check out these examples.

For outputs that you only need to consume once, consider low-memory streaming with streamText. It uses the same execution engine with one stream consumer and no replay buffer. Plain streaming avoids text accumulation; tools, structured output, and callbacks retain the content their contracts require.

Import

import { streamText } from "ai"

API Signature

Parameters

model:
LanguageModel
The language model to use. Example: openai('gpt-6-astra')
instructions:
Instructions
Instructions to use that specify the behavior of the model.
messages:
Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>
A list of messages that represent a conversation. Automatically converts UI messages from the useChat hook.
SystemModelMessage
role:
'system'
The role for the system message.
content:
string
The content of the message.
UserModelMessage
role:
'user'
The role for the user message.
content:
string | Array<TextPart | ImagePart | FilePart>
The content of the message.
TextPart
type:
'text'
The type of the message part.
text:
string
The text content of the message part.
ImagePart
type:
'image'
The type of the message part.
image:
string | Uint8Array | Buffer | ArrayBuffer | URL
The image content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.
mediaType?:
string
The IANA media type of the image.
FilePart
type:
'file'
The type of the message part.
data:
string | Uint8Array | Buffer | ArrayBuffer | URL
The file content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.
mediaType:
string
The IANA media type of the file.
AssistantModelMessage
role:
'assistant'
The role for the assistant message.
content:
string | Array<TextPart | FilePart | ReasoningPart | ReasoningFilePart | ToolCallPart>
The content of the message.
TextPart
type:
'text'
The type of the message part.
text:
string
The text content of the message part.
ReasoningPart
type:
'reasoning'
The type of the reasoning part.
text:
string
The reasoning text.
ReasoningFilePart
type:
'reasoning-file'
The type of the message part.
data:
string | Uint8Array | Buffer | ArrayBuffer | URL
The file data. String are either base64 encoded content, base64 data URLs, or http(s) URLs.
mediaType:
string
The IANA media type of the file.
FilePart
type:
'file'
The type of the message part.
data:
string | Uint8Array | Buffer | ArrayBuffer | URL
The file content of the message part. String are either base64 encoded content, base64 data URLs, or http(s) URLs.
mediaType:
string
The IANA media type of the file.
filename?:
string
The name of the file.
ToolCallPart
type:
'tool-call'
The type of the message part.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
input:
object based on zod schema
Parameters generated by the model to be used by the tool.
ToolModelMessage
role:
'tool'
The role for the tool message.
content:
Array<ToolResultPart>
The content of the message.
ToolResultPart
type:
'tool-result'
The type of the message part.
toolCallId:
string
The id of the tool call the result corresponds to.
toolName:
string
The name of the tool the result corresponds to.
result:
unknown
The result returned by the tool after execution.
isError?:
boolean
Whether the result is an error or an error message.
allowSystemInMessages?:
boolean
Whether system messages are allowed in the prompt or messages fields. Defaults to false. System messages in the instructions option are always allowed. Enabling this for user-controlled messages can create a prompt injection risk.
tools:
ToolSet
Tools that are accessible to and can be called by the model. The model needs to support calling tools.
Tool
description?:
string | ((options: { context: CONTEXT; experimental_sandbox?: Experimental_SandboxSession }) => string)
Information about the purpose of the tool including details on how and when it can be used by the model. Provide a string for a fixed description, or a function to derive the description from the tool-specific context and optional experimental sandbox before each model call.
inputSchema:
Zod Schema | JSON Schema
The schema of the input that the tool expects. The language model will use this to generate the input. It is also used to validate the output of the language model. Use descriptions to make the input understandable for the language model. You can either pass in a Zod schema or a JSON schema (using the jsonSchema function).
execute?:
async (parameters: T, options: ToolExecutionOptions) => RESULT
An async function that is called with the arguments from the tool call and produces a result. If not provided, the tool will not be executed automatically.
ToolExecutionOptions
toolCallId:
string
The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
messages:
ModelMessage[]
Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call.
abortSignal:
AbortSignal
An optional abort signal that indicates that the overall operation should be aborted.
toolChoice?:
"auto" | "none" | "required" | { "type": "tool", "toolName": string }
The tool choice setting. It specifies how tools are selected for execution. The default is "auto". "none" disables tool execution. "required" requires tools to be executed. { "type": "tool", "toolName": string } specifies a specific tool to execute.
maxOutputTokens?:
number
Maximum number of tokens to generate.
temperature?:
number
Temperature setting. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either temperature or topP, but not both.
topP?:
number
Nucleus sampling. The value is passed through to the provider. The range depends on the provider and model. It is recommended to set either temperature or topP, but not both.
topK?:
number
Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. Recommended for advanced use cases only. You usually only need to use temperature.
presencePenalty?:
number
Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. The value is passed through to the provider. The range depends on the provider and model.
frequencyPenalty?:
number
Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. The value is passed through to the provider. The range depends on the provider and model.
stopSequences?:
string[]
Sequences that will stop the generation of the text. If the model generates any of these sequences, it will stop generating further text.
seed?:
number
The seed (integer) to use for random sampling. If set and supported by the model, calls will generate deterministic results.
reasoning?:
'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
Controls how much reasoning the model performs before generating a response. When omitted, the provider's default behavior is used. 'provider-default' explicitly requests the provider's default. Providers that do not support reasoning will emit a warning. Provider-specific settings take precedence over corresponding mapped fields. Partial configurations may still use portable reasoning to fill missing fields; summary and display settings can be combined with it. See the reasoning guide for provider-specific mapping details.
maxRetries?:
number
Maximum number of retries. Set to 0 to disable retries. Default: 2.
streamRetries?:
number
Maximum number of automatic retries for provider error events received after response streaming begins. Retries rerun only the current model step and preserve completed earlier steps and their tool results. Tool-related output and client-side tool work from failed attempts are discarded; other output already emitted cannot be retracted, but is excluded from the recovered step result, structured output parsing, response messages, and subsequent model steps. Final request and response metadata come from the recovered attempt. Open text and reasoning parts are ended before recovered output begins. onStepStart runs once for the logical step, onLanguageModelCallStart runs for each attempt, and onLanguageModelCallEnd runs for attempts that reach a model-call finish. Provider-executed tool work cannot be undone and may repeat. Set to 0 to disable automatic retries while allowing onError to request one callback-directed retry. With automatic retries configured, onError can request at most one additional retry after they are exhausted, bounding total recovery calls to streamRetries + 1. Omit to disable all stream retry behavior and preserve incremental tool streaming for existing onError observers. Default: 0.
abortSignal?:
AbortSignal
An optional abort signal that can be used to cancel the call. When it fires during streaming, pending result promises such as text and steps reject with the abort reason without waiting for onAbort or provider cancellation. Completed steps are available through onAbort.
timeout?:
number | { totalMs?: number; stepMs?: number; firstChunkMs?: number; chunkMs?: number; toolMs?: number; tools?: Partial<Record<`${toolName}Ms`, number>> }
Timeout in milliseconds. Can be specified as a number or as an object with totalMs, stepMs, firstChunkMs, chunkMs, toolMs, and/or tools properties. totalMs sets the total timeout for the entire call. stepMs sets the timeout for each complete step, including model generation, retries, and local tool execution. firstChunkMs sets the timeout until the first content-bearing output in each step; metadata, stream starts, empty deltas, raw chunks, and transport activity do not satisfy it. chunkMs starts with the first meaningful model output and limits gaps between subsequent meaningful model output chunks. Both output timers stop when the model response finishes and start fresh for each retry or later model call. Local tool results, including preliminary results, do not reset them; local tool execution is outside their scope. Provider-executed tools remain within the model response. toolMs sets the default timeout for all tool executions. tools sets per-tool timeout overrides using the pattern {toolName}Ms (e.g. weatherMs, slowApiMs) that take precedence over toolMs - tool names are type-checked for autocomplete. If a tool takes longer than its timeout, it aborts and returns a tool-error so the model can respond or retry. Can be used alongside abortSignal.
headers?:
Record<string, string | undefined>
Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
telemetry?:
TelemetryOptions
Telemetry configuration.
TelemetryOptions
isEnabled?:
boolean
Enable or disable telemetry. Enabled by default. Set to false to opt out.
recordInputs?:
boolean
Enable or disable input recording. Enabled by default.
recordOutputs?:
boolean
Enable or disable output recording. Enabled by default.
functionId?:
string
Identifier for this function. Used to group telemetry data by function.
includeRuntimeContext?:
{ [KEY in keyof CONTEXT]?: boolean }
Top-level runtime context properties that should be included in telemetry. Runtime context properties are excluded unless they are explicitly set to true. Lifecycle callbacks and returned results still receive the full runtimeContext.
includeToolsContext?:
{ [TOOL_NAME in keyof InferToolSetContext<TOOLS>]?: { [KEY in keyof InferToolSetContext<TOOLS>[TOOL_NAME]]?: boolean } }
Top-level tool context properties that should be included in telemetry, configured per tool. Tool context properties are excluded unless they are explicitly set to true. Lifecycle callbacks and returned results still receive the full toolsContext.
integrations?:
Telemetry | Telemetry[]
Per-call telemetry integrations that receive lifecycle events. When provided, these replace any globally registered integrations for this call.
experimental_transform?:
StreamTextTransform | Array<StreamTextTransform>
Optional stream transformations. They are applied in the order they are provided. The stream transformations must maintain the stream structure for streamText to work correctly.
includeRawChunks?:
boolean
Deprecated. Use include.rawChunks instead. Whether to include raw chunks from the provider in the stream. When enabled, you will receive raw chunks with type "raw" that contain the unprocessed data from the provider. This allows access to cutting-edge provider features not yet wrapped by the AI SDK. Defaults to false.
providerOptions?:
Record<string,JSONObject> | undefined
Provider-specific options. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.
activeTools?:
ActiveTools<TOOLS>
Limits the tools that are available for the model to call without changing the tool call and result types in the result. All tools are active by default. Tool names are restricted to the string keys of the tool set.
toolOrder?:
ToolOrder<TOOLS>
Controls the order in which tools are sent to the provider. The list can be partial. Tools not listed in toolOrder are sent after the listed tools, sorted alphabetically. Tool names are restricted to the string keys of the tool set.
toolCallConcurrency?:
number
Maximum number of tool calls that the SDK executes concurrently within a step. Set to 1 to execute calls sequentially in model-generated order. Must be a positive integer. By default, all tool calls execute concurrently.
toolApproval?:
ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>
Approval configuration for this call. Pass a GenericToolApprovalFunction to handle all tool calls in one callback with toolCall, tools, toolsContext, messages, and runtimeContext, or pass a per-tool object where each key can be a status ('not-applicable', 'approved', 'denied', or 'user-approval'), an object form such as { type: 'denied', reason: 'blocked by policy' }, or a SingleToolApprovalFunction that receives the tool input and options toolCallId, messages, toolContext, and runtimeContext (same shape as tool execution options without abortSignal, with context renamed to toolContext). The RUNTIME_CONTEXT type parameter matches the call's runtimeContext. A GenericToolApprovalFunction or SingleToolApprovalFunction may return undefined for the same effect as 'not-applicable'. 'not-applicable' is the default execution path and runs the tool without approval metadata. Use 'approved', 'denied', or their object forms when you want explicit automatic approval request/response parts in the output. Object statuses can include a reason: automatic approvals and denials forward it to the approval response, while manual user approvals forward it to the approval request for the human approver. This setting takes precedence over a tool's needsApproval default.
experimental_toolCallers?:
Experimental_ToolCallers<TOOLS>
Configures which caller tools may invoke each tool. Pass an object keyed by callee tool name whose values list caller-capable tool names. Include DIRECT_TOOL_CALL from @ai-sdk/code-mode to keep a configured tool directly callable by the model. Local-only callees are hidden from direct model calls and bound to their local caller for each generation step. Provider caller names are translated to provider-native allowed-caller options. Tools without an entry keep their existing direct tool-calling behavior.
experimental_refineToolInput?:
ToolInputRefinement<TOOLS>
Optional mapping of tool names to functions that refine parsed tool inputs. Each function receives the typed input for its tool and must return the same input type shape. The refined input is used for tool execution, stream parts, lifecycle callbacks, and telemetry.
stopWhen?:
StopCondition<TOOLS> | Array<StopCondition<TOOLS>>
Condition for stopping the generation when there are tool results in the last step. When the condition is an array, any of the conditions can be met to stop the generation. Default: isStepCount(1).
prepareStep?:
(options: PrepareStepOptions) => PrepareStepResult<TOOLS> | Promise<PrepareStepResult<TOOLS>>
Optional function that you can use to provide different settings for a step. You can modify the model, model call settings, tool choices, active tools, instructions, input messages, and experimental sandbox for each step.
PrepareStepFunction<TOOLS>
options:
object
The options for the step.
PrepareStepOptions
steps:
Array<StepResult<TOOLS>>
The steps that have been executed so far.
stepNumber:
number
The number of the step that is being executed.
model:
LanguageModel
The model that is being used.
instructions:
Instructions | undefined
The instructions that will be sent to the model for the current step. If prepareStep returns an instructions override, those instructions carry forward to later steps.
initialInstructions:
Instructions | undefined
The initial instructions that were passed into generateText or streamText.
messages:
Array<ModelMessage>
The messages that will be sent to the model for the current step. If prepareStep returns a messages override, those messages carry forward to later steps.
experimental_steeringMessages?:
Array<UserModelMessage> | undefined
The user messages that were sent with experimental_steering and added to messages for the current step. Undefined when the step received no steering messages. messages already contains them. If you return a messages override that is rebuilt from other fields, add them back together with the steering messages of previous steps from steps.
runtimeContext?:
CONTEXT
The shared runtime context passed via the runtimeContext setting.
toolsContext:
InferToolSetContext<TOOLS>
The per-tool context map passed via the toolsContext setting.
experimental_sandbox?:
Experimental_SandboxSession | undefined
The experimental sandbox environment passed via the experimental_sandbox setting.
PrepareStepResult<TOOLS>
model?:
LanguageModel
Optionally override which LanguageModel instance is used for this step.
maxOutputTokens?:
number
Maximum number of tokens to generate for this step. Uses the top-level value when omitted or undefined.
temperature?:
number
Temperature for this step. Uses the top-level value when omitted or undefined.
topP?:
number
Nucleus sampling value for this step. Uses the top-level value when omitted or undefined.
topK?:
number
Top-K sampling value for this step. Uses the top-level value when omitted or undefined.
presencePenalty?:
number
Presence penalty for this step. Uses the top-level value when omitted or undefined.
frequencyPenalty?:
number
Frequency penalty for this step. Uses the top-level value when omitted or undefined.
stopSequences?:
string[]
Stop sequences for this step. Uses the top-level value when omitted or undefined.
seed?:
number
Random sampling seed for this step. Uses the top-level value when omitted or undefined.
reasoning?:
LanguageModelV4CallOptions["reasoning"]
Reasoning effort for this step. Uses the top-level value when omitted or undefined.
toolChoice?:
ToolChoice<TOOLS>
Optionally set which tool the model must call, or provide tool call configuration for this step.
activeTools?:
ActiveTools<TOOLS>
If provided, only these tools are enabled/available for this step.
toolOrder?:
ToolOrder<TOOLS>
If provided, overrides the order in which tools are sent to the provider for this step. Tools not listed are appended alphabetically.
instructions?:
Instructions
Optionally override the instructions sent to the model for this step. The override carries forward to later steps until prepareStep returns another instructions or system override.
messages?:
Array<ModelMessage>
Optionally override the full set of messages sent to the model for this step.
runtimeContext?:
CONTEXT
Shared runtime context. Changing it will affect this step and all subsequent steps.
toolsContext:
InferToolSetContext<TOOLS>
Per-tool context map. Changing it will affect tool-specific context in this step and all subsequent steps.
experimental_sandbox?:
Experimental_SandboxSession
Experimental sandbox environment for this step. Changing it will affect tool execution in this step only.
providerOptions?:
ProviderOptions
Additional provider-specific options for this step. Can be used to pass provider-specific configuration such as container IDs for Anthropic code execution.
runtimeContext?:
CONTEXT
User-defined shared runtime context object passed to prepareStep and lifecycle callbacks.
toolsContext:
InferToolSetContext<TOOLS>
Per-tool context map keyed by tool name. Required when at least one tool defines contextSchema; not accepted when no tools need context.
experimental_sandbox?:
Experimental_SandboxSession
Experimental sandbox environment that is passed through to prepareStep, tool description functions, and tool execution. Tools can access it from their description function options and execution options.
experimental_steering?:
Experimental_Steering
Experimental steering object created with experimental_createSteering(). Messages sent with steering.steer() are added as user messages at the next step boundary, after the current step and its tool calls are done. Messages sent with steering.queue() wait until the model finishes its current task and are added one per task. A waiting message keeps the loop going for another step unless a stop condition is met. steer() and queue() resolve with { type: 'delivered', id, message, stepNumber } or { type: 'not-delivered', id, message, reason }. See Steering.
experimental_download?:
(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean; abortSignal?: AbortSignal }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>
Custom download function to control how URLs are fetched when they appear in prompts. By default, files are downloaded if the model does not support the URL for the given media type. Use createDownload({ fetch, maxBytes }) from ai to keep the default behavior with a custom fetch transport (e.g. guarded-fetch on Node.js) or size limit. Experimental feature. Return null to pass the URL directly to the model (when supported), or return downloaded content with data and media type.
include?:
{ requestBody?: boolean; requestMessages?: boolean; rawChunks?: boolean }
Controls inclusion of request body and request messages in step results, and raw provider chunks in the stream. By default, request body, request messages, and raw chunks are excluded to reduce memory usage. Set requestBody or requestMessages to true when you need access to the data. Set rawChunks to true when you need access to raw provider chunks.
Object
requestBody?:
boolean
Whether to include the request body in step results. The request body can be large when sending images or files. Default: false.
requestMessages?:
boolean
Whether to include the request messages in step results. The request messages can be large when sending images or files. Default: false.
rawChunks?:
boolean
Whether to include raw chunks from the provider in the stream. When enabled, raw chunks with type "raw" contain unprocessed provider data. Default: false.
repairToolCall?:
(options: ToolCallRepairOptions) => Promise<LanguageModelV4ToolCall | null>
A function that attempts to repair a tool call that failed to parse. Return either a repaired tool call or null if the tool call cannot be repaired.
ToolCallRepairOptions
instructions:
Instructions | undefined
The instructions provided to the model.
system?:
Instructions | undefined
The instructions provided to the model. Deprecated: use instructions instead.
messages:
ModelMessage[]
The messages in the current generation step.
toolCall:
LanguageModelV4ToolCall
The tool call that failed to parse.
tools:
TOOLS
The tools that are available.
inputSchema:
(options: { toolName: string }) => JSONSchema7
A function that returns the JSON Schema for a tool.
error:
NoSuchToolError | InvalidToolInputError
The error that occurred while parsing the tool call.
abortSignal?:
AbortSignal
An optional signal for cancelling the tool call repair.
onChunk?:
(event: OnChunkResult) => Promise<void> |void
Callback that is called for each stream part. The stream processing will pause until the callback promise is resolved.
OnChunkResult
chunk:
TextStreamPart<TOOLS>
The stream part. This is the same union as stream and includes start, steering-message, start-step, text-start, text-delta, text-end, reasoning-start, reasoning-delta, reasoning-end, custom, source, file, reasoning-file, tool-call, tool-input-start, tool-input-delta, tool-input-end, tool-result, tool-error, tool-output-denied, tool-approval-request, tool-approval-response, finish-step, finish, abort, error, raw, and ping.
TextStreamPart
type:
'text-delta'
The type to identify the object as text delta.
text:
string
The text delta.
TextStreamPart
type:
'reasoning-delta'
The type to identify the object as reasoning delta.
text:
string
The reasoning text delta.
TextStreamPart
type:
'source'
The type to identify the object as source.
source:
Source
The source.
TextStreamPart
type:
'custom'
The type to identify the object as custom content.
kind:
string
The kind of custom content, in the format {provider}.{provider-type} (e.g. openai.compaction).
providerMetadata?:
ProviderMetadata
Optional provider metadata for the custom content.
TextStreamPart
type:
'tool-call'
The type to identify the object as tool call.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
input:
object based on zod schema
Parameters generated by the model to be used by the tool.
TextStreamPart
type:
'tool-input-start'
Indicates the start of streamed tool input.
inputEncoding?:
'json' | 'text'
Encoding of subsequent tool-input-delta events. Defaults to json when omitted. Text deltas contain raw string input, such as OpenAI custom-tool code or HTML.
id:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
TextStreamPart
type:
'tool-input-delta'
The type to identify the object as streamed tool input delta.
id:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
delta:
string
The text delta of the tool input.
TextStreamPart
type:
'tool-result'
The type to identify the object as tool result.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
input:
object based on zod schema
Parameters generated by the model to be used by the tool.
output:
any
The result returned by the tool after execution has completed.
onError?:
StreamTextOnErrorCallback | StreamTextOnErrorRetryCallback
Callback that is called when an error occurs during streaming. StreamTextOnErrorCallback preserves the existing PromiseLike | void observer contract. StreamTextOnErrorRetryCallback additionally types { retry: true } results for retry-capable handlers. Well-formed mid-stream provider error events are exposed as StreamProviderError instances. When streamRetries is explicitly configured, return { retry: true } to request one callback-directed retry for the current model step after automatic retries are exhausted. Other return values do not request a retry.
OnErrorResult
error:
unknown
The error that occurred. Use StreamProviderError.isInstance to identify normalized provider error events and inspect their retry metadata.
output?:
Output
Specification for parsing structured outputs from the LLM response.
Output
Output.text():
Output
Output specification for text generation (default).
Output.object():
Output
Output specification for typed object generation using schemas. When the model generates a text response, it will return an object that matches the schema.
Options
schema:
Schema<OBJECT>
The schema of the object to generate.
name?:
string
Optional name of the output. Used by some providers for additional LLM guidance.
description?:
string
Optional description of the output. Used by some providers for additional LLM guidance.
Output.array():
Output
Output specification for array generation. When the model generates a text response, it will return an array of elements.
Options
element:
Schema<ELEMENT>
The schema of the array elements to generate.
minItems?:
number
Optional minimum number of array elements. Must be a non-negative integer.
maxItems?:
number
Optional maximum number of array elements. Must be a non-negative integer and greater than or equal to minItems.
name?:
string
Optional name of the output. Used by some providers for additional LLM guidance.
description?:
string
Optional description of the output. Used by some providers for additional LLM guidance.
Output.choice():
Output
Output specification for choice generation. When the model generates a text response, it will return a one of the choice options.
Options
options:
Array<string>
The available choices.
name?:
string
Optional name of the output. Used by some providers for additional LLM guidance.
description?:
string
Optional description of the output. Used by some providers for additional LLM guidance.
Output.json():
Output
Output specification for unstructured JSON generation. When the model generates a text response, it will return a JSON object.
Options
name?:
string
Optional name of the output. Used by some providers for additional LLM guidance.
description?:
string
Optional description of the output. Used by some providers for additional LLM guidance.
onStepEnd?:
(result: StepResult<TOOLS>) => Promise<void> | void
Callback that is called when a step ends.
StepResult
stepType:
"initial" | "continue" | "tool-result"
The type of step. The first step is always an "initial" step, and subsequent steps are either "continue" steps or "tool-result" steps.
rawFinishReason:
string | undefined
The raw reason why the generation finished (from the provider).
usage:
LanguageModelUsage
The token usage of the step.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
performance:
StepResultPerformance
Timing and throughput metrics for the step.
StepResultPerformance
effectiveOutputTokensPerSecond:
number
Effective number of output tokens per second over the full language model response.
outputTokensPerSecond:
number | undefined
Number of output tokens per second after the first generated output chunk was received. Only available for streaming steps.
inputTokensPerSecond:
number | undefined
Number of input tokens processed per second before the first generated output chunk was received. Only available for streaming steps.
effectiveTotalTokensPerSecond:
number
Effective number of input and output tokens per second over the full language model response.
stepTimeMs:
number
Total time spent on the step, including language model response time and tool execution time, in milliseconds.
responseTimeMs:
number
Time spent waiting for the language model response in milliseconds.
toolExecutionMs:
Readonly<Record<string, number>>
Time spent executing each client-side tool call in the step in milliseconds, keyed by tool call ID.
timeToFirstOutputMs:
number | undefined
Time until the first generated output chunk was received in milliseconds. Only available for streaming steps.
timeBetweenOutputChunksMs:
OutputChunkTimingStats | undefined
Timing statistics for the gaps between generated output chunks in milliseconds. Only available for streaming steps with at least two output chunks.
text:
string
The full text that has been generated.
reasoningText:
string | undefined
The reasoning text of the model (only available for some models).
sources:
Array<Source>
Sources that have been used in the final step.
Source
sourceType:
'url'
A URL source. This is return by web search RAG models.
id:
string
The ID of the source.
url:
string
The URL of the source.
title?:
string
The title of the source.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata for the source.
files:
Array<GeneratedFile>
All files that were generated in this step.
GeneratedFile
base64:
string
File as a base64 encoded string.
uint8Array:
Uint8Array
File as a Uint8Array.
mediaType:
string
The IANA media type of the file.
toolCalls:
ToolCall[]
The tool calls that have been executed.
toolResults:
ToolResult[]
The tool results that have been generated.
warnings:
Warning[] | undefined
Warnings from the model provider (e.g. unsupported settings).
response?:
Response
Response metadata.
Response
id:
string
The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.
modelId:
string
The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.
timestamp:
Date
The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.
headers?:
Record<string, string>
Optional response headers.
isContinued:
boolean
True when there will be a continuation step with a continuation text.
providerMetadata?:
Record<string,JSONObject> | undefined
Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.
onStepError?:
(event: GenerateTextStepErrorEvent) => Promise<void> | void
Callback that is called when a step that started fails before it produces a step result, i.e. when the provider call throws or rejects, or when the model stream ends without output. onStepEnd is not called for such a step. A provider error chunk does not fail the step: it still ends with onStepEnd and finishReason: 'error'. Aborts and timeouts end the step with onAbort instead.
GenerateTextStepErrorEvent
...GenerateTextStepStartEvent:
GenerateTextStepStartEvent
All properties of the onStepStart event of the step that failed, such as callId, stepNumber, steps, messages, runtimeContext, and toolsContext.
error:
unknown
The error that ended the step.
onStepFinish?:
GenerateTextOnStepFinishCallback<TOOLS>
Deprecated. Use onStepEnd instead. This alias is only used as a fallback when onStepEnd is not provided.
onEnd?:
(result: OnEndResult) => Promise<void> | void
Callback that is called when the LLM response and all request tool executions (for tools that have an execute function) are finished.
OnEndResult
rawFinishReason:
string | undefined
The raw reason why the generation finished (from the provider).
output?:
COMPLETE_OUTPUT | undefined
The parsed output when an output setting was provided and parsing succeeded.
usage:
LanguageModelUsage
The token usage of last step.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
totalUsage:
LanguageModelUsage
The total token usage from all steps.
LanguageModelUsage
inputTokens:
number | undefined
The number of input (prompt) tokens used.
outputTokens:
number | undefined
The number of output (completion) tokens used.
totalTokens:
number | undefined
The total number of tokens as reported by the provider. This number might be different from the sum of inputTokens and outputTokens and e.g. include reasoning tokens or other overhead.
providerMetadata:
Record<string,JSONObject> | undefined
Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.
text:
string
The full text that has been generated.
reasoning:
string | undefined
The reasoning text of the model (only available for some models).
reasoning:
Array<ReasoningDetail>
The reasoning details of the model (only available for some models).
ReasoningDetail
type:
'text'
The type of the reasoning detail.
text:
string
The text content (only for type "text").
signature?:
string
Optional signature (only for type "text").
ReasoningDetail
type:
'redacted'
The type of the reasoning detail.
data:
string
The redacted data content (only for type "redacted").
sources:
Array<Source>
Sources that have been used in the final step.
Source
sourceType:
'url'
A URL source. This is return by web search RAG models.
id:
string
The ID of the source.
url:
string
The URL of the source.
title?:
string
The title of the source.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata for the source.
files:
Array<GeneratedFile>
Files that were generated in all steps.
GeneratedFile
base64:
string
File as a base64 encoded string.
uint8Array:
Uint8Array
File as a Uint8Array.
mediaType:
string
The IANA media type of the file.
toolCalls:
ToolCall[]
The tool calls that have been executed.
toolResults:
ToolResult[]
The tool results that have been generated.
warnings:
Warning[] | undefined
Warnings from the model provider (e.g. unsupported settings).
response?:
Response
Response metadata.
Response
id:
string
The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.
modelId:
string
The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.
timestamp:
Date
The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.
headers?:
Record<string, string>
Optional response headers.
messages:
Array<ResponseMessage>
The response messages generated during this step. It consists of an assistant message, potentially containing tool calls. When there are tool results in this step, there is an additional tool message with the available tool results. If there are tools that do not have execute functions, they are not included in the tool results and need to be added separately.
steps:
Array<StepResult>
Response information for every step. You can use this to get information about intermediate steps, such as the tool calls or the response headers.
finalStep:
StepResult
The final step. This is a shortcut for steps.at(-1).
runtimeContext:
CONTEXT
The final state of the user-defined runtime context object when the stream is aborted.
onAbort?:
(event: OnAbortResult) => Promise<void> | void
Callback that is called when a stream is aborted via AbortSignal. You can use it to perform cleanup operations.
OnAbortResult
callId:
string
Unique identifier for this generation call, used to correlate events.
steps:
Array<StepResult>
Details for all previously finished steps.
reason?:
unknown
The raw abort reason from the AbortSignal, when one is available.
onStart?:
(event: GenerateTextStartEvent) => PromiseLike<void> | void
Callback that is called when the streamText operation begins, before any LLM calls are made. Errors thrown in this callback are silently caught and do not break the generation flow.
GenerateTextStartEvent
provider:
string
The provider identifier (e.g., "openai", "anthropic").
modelId:
string
The specific model identifier (e.g., "gpt-6-astra").
instructions:
Instructions | undefined
The instructions provided to the model.
messages:
Array<ModelMessage>
The messages for this generation.
tools:
TOOLS | undefined
The tools available for this generation.
toolChoice:
ToolChoice<TOOLS> | undefined
The tool choice strategy for this generation.
activeTools:
ActiveTools<TOOLS>
Limits which tools are available for the model to call.
toolOrder:
ToolOrder<TOOLS>
Controls the order in which tools are sent to the provider.
maxOutputTokens:
number | undefined
Maximum number of tokens to generate.
temperature:
number | undefined
Sampling temperature for generation.
topP:
number | undefined
Top-p (nucleus) sampling parameter.
topK:
number | undefined
Top-k sampling parameter.
presencePenalty:
number | undefined
Presence penalty for generation.
frequencyPenalty:
number | undefined
Frequency penalty for generation.
stopSequences:
string[] | undefined
Sequences that will stop generation.
seed:
number | undefined
Random seed for reproducible generation.
maxRetries:
number
Maximum number of retries for failed requests.
timeout:
number | { totalMs?: number; stepMs?: number; firstChunkMs?: number; chunkMs?: number; toolMs?: number; tools?: Partial<Record<`${toolName}Ms`, number>> } | undefined
Timeout configuration for the generation. Can be a number (milliseconds) or an object with totalMs, stepMs, firstChunkMs (streaming only), chunkMs, toolMs, and per-tool overrides via tools.
headers:
Record<string, string | undefined> | undefined
Additional HTTP headers sent with the request.
providerOptions:
ProviderOptions | undefined
Additional provider-specific options.
output:
OUTPUT | undefined
The output specification for structured outputs, if configured.
abortSignal:
AbortSignal | undefined
Abort signal for cancelling the operation.
include:
{ requestBody?: boolean; requestMessages?: boolean } | undefined
Settings for controlling what data is included in step results.
runtimeContext:
CONTEXT
User-defined shared runtime context object that flows through the entire generation lifecycle.
toolsContext:
InferToolSetContext<TOOLS>
Per-tool context map passed via toolsContext, keyed by tool name.
onStepStart?:
(event: GenerateTextStepStartEvent) => PromiseLike<void> | void
Callback that is called when a step begins, before the provider is called. Errors thrown in this callback are silently caught and do not break the generation flow.
GenerateTextStepStartEvent
stepNumber:
number
Zero-based index of the current step.
provider:
string
The provider identifier (e.g., "openai", "anthropic").
modelId:
string
The specific model identifier (e.g., "gpt-6-astra").
instructions:
Instructions | undefined
The instructions provided to the model for this step.
messages:
Array<ModelMessage>
The messages that will be sent to the model for this step. Uses the user-facing ModelMessage format. May be overridden by prepareStep. If prepareStep returns a messages override, those messages carry forward to later steps.
tools:
TOOLS | undefined
The tools available for this generation.
toolChoice:
LanguageModelV4ToolChoice | undefined
The tool choice configuration for this step.
activeTools:
ActiveTools<TOOLS>
Limits which tools are available for this step.
toolOrder:
ToolOrder<TOOLS>
Controls the order in which tools are sent to the provider for this step.
steps:
ReadonlyArray<StepResult<TOOLS>>
Array of results from previous steps (empty for the first step).
providerOptions:
ProviderOptions | undefined
Additional provider-specific options for this step.
headers:
Record<string, string | undefined> | undefined
Additional HTTP headers sent with the request.
output:
OUTPUT | undefined
The output specification for structured outputs, if configured.
abortSignal:
AbortSignal | undefined
Abort signal for cancelling the operation.
include:
{ requestBody?: boolean; requestMessages?: boolean } | undefined
Settings for controlling what data is included in step results.
runtimeContext:
CONTEXT
User-defined shared runtime context object. May be updated from prepareStep between steps.
toolsContext:
InferToolSetContext<TOOLS>
Per-tool context map. May be updated from prepareStep between steps.
onLanguageModelCallStart?:
(event: LanguageModelCallStartEvent) => PromiseLike<void> | void
Callback that is called immediately before the provider model call begins. Unlike onStepStart, this callback is scoped to model work only and excludes any later client-side tool execution. Errors thrown in this callback are silently caught and do not break the generation flow.
LanguageModelCallStartEvent
callId:
string
Unique identifier for the generation call.
provider:
string
The provider identifier for this model call.
modelId:
string
The specific model identifier for this model call.
instructions:
Instructions | undefined
The instructions that will be sent to the model.
messages:
Array<ModelMessage>
The messages that will be sent to the model.
tools:
ReadonlyArray<Record<string, unknown>> | undefined
Prepared tool definitions for the model call, if any.
onLanguageModelCallEnd?:
(event: LanguageModelCallEndEvent) => PromiseLike<void> | void
Callback that is called after the model response has been normalized and parsed, but before any client-side tool execution begins. Errors thrown in this callback are silently caught and do not break the generation flow.
LanguageModelCallEndEvent
callId:
string
Unique identifier for the generation call.
provider:
string
The provider identifier for this model call.
modelId:
string
The provider-returned model identifier for this model call.
finishReason:
FinishReason
The unified reason why the model call finished.
usage:
LanguageModelUsage
Token usage reported by the model call.
content:
ReadonlyArray<ContentPart<TOOLS>>
The content parts produced by the model call (text, reasoning, files, tool calls, etc.).
responseId:
string
The provider-returned response ID for this model call.
providerMetadata:
ProviderMetadata | undefined
Provider-specific metadata for this model call, when returned by the provider.
performance:
{ responseTimeMs: number; effectiveOutputTokensPerSecond: number; outputTokensPerSecond: number | undefined; inputTokensPerSecond: number | undefined; effectiveTotalTokensPerSecond: number; timeToFirstOutputMs: number | undefined; timeBetweenOutputChunksMs?: OutputChunkTimingStats }
Performance metrics for the model call.
LanguageModelCallPerformance
responseTimeMs:
number
Time spent waiting for the language model response in milliseconds.
effectiveOutputTokensPerSecond:
number
Effective number of output tokens per second over the full language model response.
outputTokensPerSecond:
number | undefined
Number of output tokens per second after the first generated output chunk was received. Only available for streaming model calls.
inputTokensPerSecond:
number | undefined
Number of input tokens processed per second before the first generated output chunk was received. Only available for streaming model calls.
effectiveTotalTokensPerSecond:
number
Effective number of input and output tokens per second over the full language model response.
timeToFirstOutputMs:
number | undefined
Time until the first generated output chunk was received in milliseconds. Only available for streaming model calls.
timeBetweenOutputChunksMs:
OutputChunkTimingStats | undefined
Timing statistics for the gaps between generated output chunks in milliseconds. Only available for streaming model calls with at least two output chunks.
onToolExecutionStart?:
(event: ToolExecutionStartEvent) => PromiseLike<void> | void
Callback that is called right before a tool's execute function runs. Errors thrown in this callback are silently caught and do not break the generation flow.
ToolExecutionStartEvent
callId:
string
Unique identifier for this generation call, used to correlate events.
toolCall:
TypedToolCall<TOOLS>
The full tool call object containing toolName, toolCallId, input, and metadata.
messages:
Array<ModelMessage>
Messages that were sent to the language model to initiate the response that contained the tool call. Does not include the system prompt nor the assistant response that contained the tool call.
toolContext:
InferToolContext<TOOLS[toolName]>
Tool-specific context object for the tool call that is about to execute. Narrowed to the context type of the individual tool, not the entire tool set.
onToolExecutionEnd?:
(event: ToolExecutionEndEvent) => PromiseLike<void> | void
Callback that is called right after a tool's execute function completes (or errors). The toolOutput field is a discriminated union: when toolOutput.type is 'tool-result', the output field contains the tool result; when toolOutput.type is 'tool-error', the error field contains the error. Errors thrown in this callback are silently caught and do not break the generation flow.
ToolExecutionEndEvent
callId:
string
Unique identifier for this generation call, used to correlate events.
toolCall:
TypedToolCall<TOOLS>
The full tool call object containing toolName, toolCallId, input, and metadata.
toolExecutionMs:
number
The wall-clock duration of the tool execution in milliseconds.
messages:
Array<ModelMessage>
Messages that were sent to the language model to initiate the response that contained the tool call. Does not include the system prompt nor the assistant response that contained the tool call.
toolContext:
InferToolContext<TOOLS[toolName]>
Tool-specific context object for the tool call that just completed. Narrowed to the context type of the individual tool, not the entire tool set.
toolOutput:
ToolOutput<TOOLS>
Discriminated union representing the tool execution result. When type is 'tool-result', the output field contains the tool's return value. When type is 'tool-error', the error field contains the error.
experimental_onToolCallStart?:
(event: ToolExecutionStartEvent) => PromiseLike<void> | void
Deprecated. Use onToolExecutionStart instead. This alias is only used as a fallback when onToolExecutionStart is not provided.
experimental_onToolCallFinish?:
(event: ToolExecutionEndEvent) => PromiseLike<void> | void
Deprecated. Use onToolExecutionEnd instead. This alias is only used as a fallback when onToolExecutionEnd is not provided.

Returns

content:
Promise<Array<ContentPart<TOOLS>>>
The content that was generated in all steps. Text parts can include an optional citations array of references supporting that text. Automatically consumes the stream.
finishReason:
PromiseLike<'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'interrupted' | 'other'>
The reason why the generation finished. A stream that ends cleanly without its provider completion signal can report "interrupted". Partial output is preserved; interruption alone does not emit an error. Streams that produce no output and no finish chunk still reject with NoOutputGeneratedError. OpenAI-compatible retains its existing error behavior. Automatically consumes the stream.
rawFinishReason:
PromiseLike<string | undefined>
The raw reason why the generation finished (from the provider).
usage:
Promise<LanguageModelUsage>
The total token usage of the generated response. When there are multiple steps, the usage is the sum of all step usages. Automatically consumes the stream.
LanguageModelUsage
inputTokens:
number | undefined
The number of input (prompt) tokens used.
outputTokens:
number | undefined
The number of output (completion) tokens used.
totalTokens:
number | undefined
The total number of tokens as reported by the provider. This number might be different from the sum of inputTokens and outputTokens and e.g. include reasoning tokens or other overhead.
totalUsage:
Promise<LanguageModelUsage>
Deprecated. Use usage instead. The total token usage of the generated response. When there are multiple steps, the usage is the sum of all step usages. Automatically consumes the stream.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
providerMetadata:
Promise<ProviderMetadata | undefined>
Deprecated. Use finalStep.providerMetadata instead. Additional provider-specific metadata from the final step. Metadata is passed through from the provider to the AI SDK and enables provider-specific results that can be fully encapsulated in the provider.
text:
Promise<string>
The full text that has been generated. Automatically consumes the stream.
reasoning:
Promise<Array<ReasoningOutput | ReasoningFileOutput>>
Deprecated. Use finalStep.reasoning instead. The full reasoning that the model has generated in the final step. Automatically consumes the stream.
ReasoningOutput
type:
'reasoning'
The type of the message part.
text:
string
The reasoning text.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata.
ReasoningFileOutput
type:
'reasoning-file'
The type of the message part.
file:
GeneratedFile
The generated file.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata.
reasoningText:
Promise<string | undefined>
Deprecated. Use finalStep.reasoningText instead. The reasoning text that the model has generated in the final step. Can be undefined if the model has only generated text. Automatically consumes the stream.
sources:
Promise<Array<Source>>
Sources that have been used as input to generate the response. For multi-step generation, the sources are accumulated from all steps. Automatically consumes the stream.
Source
sourceType:
'url'
A URL source. This is return by web search RAG models.
id:
string
The ID of the source.
url:
string
The URL of the source.
title?:
string
The title of the source.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata for the source.
files:
Promise<Array<GeneratedFile>>
Files that were generated in all steps. Automatically consumes the stream.
GeneratedFile
base64:
string
File as a base64 encoded string.
uint8Array:
Uint8Array
File as a Uint8Array.
mediaType:
string
The IANA media type of the file.
toolCalls:
Promise<TypedToolCall<TOOLS>[]>
The tool calls that have been executed in all steps. Automatically consumes the stream.
toolResults:
Promise<TypedToolResult<TOOLS>[]>
The tool results that have been generated in all steps. Resolved when all tool executions are finished.
staticToolCalls:
PromiseLike<Array<StaticToolCall<TOOLS>>>
The static tool calls that have been executed in all steps.
dynamicToolCalls:
PromiseLike<Array<DynamicToolCall>>
The dynamic tool calls that have been executed in all steps.
staticToolResults:
PromiseLike<Array<StaticToolResult<TOOLS>>>
The static tool results that have been generated in all steps.
dynamicToolResults:
PromiseLike<Array<DynamicToolResult>>
The dynamic tool results that have been generated in all steps.
request:
Promise<LanguageModelRequestMetadata>
Deprecated. Use finalStep.request instead. Additional request information from the final step. Automatically consumes the stream.
LanguageModelRequestMetadata
url?:
string
HTTP origin reported by the provider, without URL credentials, paths, queries or fragments. Unset when unavailable.
messages?:
Array<ModelMessage>
The input messages that were sent to the model for this step. Undefined by default unless requestMessages is set to true.
body?:
unknown
Request HTTP body that was sent to the provider API.
response:
Promise<LanguageModelResponseMetadata>
Deprecated. Use finalStep.response instead. Additional response information from the final step. Automatically consumes the stream.
LanguageModelResponseMetadata
id:
string
The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.
modelId:
string
The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.
timestamp:
Date
The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.
headers?:
Record<string, string>
Optional response headers.
body?:
unknown
Response body (available only for providers that use HTTP requests).
messages:
Array<ResponseMessage>
The response messages generated during the final step. It consists of an assistant message, potentially containing tool calls. When there are tool results in the final step, there is an additional tool message with the available tool results. If there are tools that do not have execute functions, they are not included in the tool results and need to be added separately.
warnings:
Promise<Warning[] | undefined>
Warnings from the model provider (e.g. unsupported settings) in all steps.
responseMessages:
Promise<Array<ResponseMessage>>
The accumulated response messages of all steps that were generated during the call.
steps:
Promise<Array<StepResult>>
Response information for every step. You can use this to get information about intermediate steps, such as the tool calls or the response headers.
StepResult
stepType:
"initial" | "continue" | "tool-result"
The type of step. The first step is always an "initial" step, and subsequent steps are either "continue" steps or "tool-result" steps.
text:
string
The generated text by the model.
reasoning:
string | undefined
The reasoning text of the model (only available for some models).
sources:
Array<Source>
Sources that have been used as input.
Source
sourceType:
'url'
A URL source. This is return by web search RAG models.
id:
string
The ID of the source.
url:
string
The URL of the source.
title?:
string
The title of the source.
providerMetadata?:
SharedV2ProviderMetadata
Additional provider metadata for the source.
files:
Array<GeneratedFile>
Files that were generated in this step.
GeneratedFile
base64:
string
File as a base64 encoded string.
uint8Array:
Uint8Array
File as a Uint8Array.
mediaType:
string
The IANA media type of the file.
toolCalls:
array
A list of tool calls made by the model.
toolResults:
array
A list of tool results returned as responses to earlier tool calls.
rawFinishReason:
string | undefined
The raw reason why the generation finished (from the provider).
usage:
LanguageModelUsage
The token usage of the generated text.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
request?:
RequestMetadata
Request metadata.
RequestMetadata
url?:
string
The HTTP origin reported by the provider, without URL credentials, paths, queries or fragments.
messages?:
Array<ModelMessage>
The input messages that were sent to the model for this step. Undefined by default unless requestMessages is set to true.
body?:
unknown
Request HTTP body that was sent to the provider API.
response?:
ResponseMetadata
Response metadata.
ResponseMetadata
id:
string
The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.
modelId:
string
The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.
timestamp:
Date
The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.
headers?:
Record<string, string>
Optional response headers.
messages:
Array<ResponseMessage>
The response messages generated during this step. It consists of an assistant message, potentially containing tool calls. When there are tool results in this step, there is an additional tool message with the available tool results. If there are tools that do not have execute functions, they are not included in the tool results and need to be added separately.
warnings:
Warning[] | undefined
Warnings from the model provider (e.g. unsupported settings).
isContinued:
boolean
True when there will be a continuation step with a continuation text.
providerMetadata?:
Record<string,JSONObject> | undefined
Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.
experimental_steeringMessages?:
Array<UserModelMessage> | undefined
The user messages that were sent with experimental_steering and added to the input of this step. Undefined when the step received no steering messages.
textStream:
AsyncIterableStream<string>
A text stream that returns only the generated text deltas. You can use it as either an AsyncIterable or a ReadableStream. Error parts are not surfaced in this stream. Use the onError callback or stream to observe them.
finalStep:
Promise<StepResult>
The final step. This is a shortcut for steps.at(-1). Automatically consumes the stream.
stream:
AsyncIterable<TextStreamPart<TOOLS>> & ReadableStream<TextStreamPart<TOOLS>>
A stream with all events, including text deltas, tool calls, tool results, and errors. Well-formed mid-stream provider failures are emitted in error parts as StreamProviderError instances. You can use it as either an AsyncIterable or a ReadableStream. Only errors that stop the stream, such as network errors, are thrown.
TextStreamPingPart
type:
'ping'
A transient provider heartbeat. It contains no generated content, does not reset model-output timeouts, and is omitted from text and UI message streams. Providers may require an explicit opt-in.
TextStreamTextEndPart
type:
'text-end'
The event type.
id:
string
The text block ID.
citations?:
Array<Citation>
References supporting this text block. Each citation contains a URL or document source, optional startIndex/endIndex offsets in this block, and an optional citedText passage from the source.
providerMetadata?:
ProviderMetadata
Additional provider metadata, including raw annotations.
TextStreamPart
type:
'text'
The type to identify the object as text.
text:
string
The text content.
TextStreamPart
type:
'reasoning'
The type to identify the object as reasoning.
text:
string
The reasoning text.
providerMetadata?:
ProviderMetadata
Optional provider metadata for the reasoning.
TextStreamPart
type:
'source'
The type to identify the object as source.
sourceType:
'url'
A URL source. This is returned by web search RAG models.
id:
string
The ID of the source.
url:
string
The URL of the source.
title?:
string
The title of the source.
providerMetadata?:
ProviderMetadata
Additional provider metadata for the source.
TextStreamPart
type:
'file'
The type to identify the object as file.
file:
GeneratedFile
The file.
GeneratedFile
base64:
string
File as a base64 encoded string.
uint8Array:
Uint8Array
File as a Uint8Array.
mediaType:
string
The IANA media type of the file.
TextStreamPart
type:
'custom'
The type to identify the object as custom content.
kind:
string
The kind of custom content, in the format {provider}.{provider-type} (e.g. openai.compaction).
providerMetadata?:
ProviderMetadata
Optional provider metadata for the custom content.
TextStreamPart
type:
'tool-call'
The type to identify the object as tool call.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
input:
object based on tool parameters
Parameters generated by the model to be used by the tool. The type is inferred from the tool definition.
TextStreamPart
type:
'tool-call-streaming-start'
Indicates the start of a tool call streaming. Only available when streaming tool calls.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
TextStreamPart
type:
'tool-call-delta'
The type to identify the object as tool call delta. Only available when streaming tool calls.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
argsTextDelta:
string
The text delta of the tool call arguments.
TextStreamPart
type:
'tool-result'
The type to identify the object as tool result.
toolCallId:
string
The id of the tool call.
toolName:
string
The name of the tool, which typically would be the name of the function.
input:
object based on tool parameters
Parameters that were passed to the tool. The type is inferred from the tool definition.
output:
tool execution return type
The result returned by the tool after execution has completed. The type is inferred from the tool execute function return type.
TextStreamPart
type:
'steering-message'
Experimental. A user message that was added to the run with experimental_steering. It is streamed before the start-step part of the step that received it.
id:
string
The id of the steering message.
message:
UserModelMessage
The user message that was added to the run.
stepNumber:
number
The number of the step whose model call received the message.
TextStreamPart
type:
'start-step'
Indicates the start of a new step in the stream.
request:
LanguageModelRequestMetadata
Information about the request that was sent to the language model provider.
LanguageModelRequestMetadata
url?:
string
HTTP origin reported by the provider, without URL credentials, paths, queries or fragments. Unset when unavailable.
messages:
Array<ModelMessage>
The input messages that were sent to the model for this step.
body?:
unknown
Request HTTP body that was sent to the provider API.
warnings:
Warning[]
Warnings from the model provider (e.g. unsupported settings).
TextStreamPart
type:
'finish-step'
Indicates the end of the current step in the stream.
response:
Omit<LanguageModelResponseMetadata, 'messages' | 'body'>
Response metadata from the language model provider. messages and body are not included on finish-step stream parts.
LanguageModelResponseMetadata
id:
string
The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.
modelId:
string
The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.
timestamp:
Date
The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.
headers:
Record<string, string>
The response headers.
usage:
LanguageModelUsage
The token usage of the generated text.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
performance:
StepResultPerformance
Timing and throughput metrics for the step.
StepResultPerformance
effectiveOutputTokensPerSecond:
number
Effective number of output tokens per second over the full language model response.
outputTokensPerSecond:
number | undefined
Number of output tokens per second after the first generated output chunk was received. Only available for streaming steps.
inputTokensPerSecond:
number | undefined
Number of input tokens processed per second before the first generated output chunk was received. Only available for streaming steps.
effectiveTotalTokensPerSecond:
number
Effective number of input and output tokens per second over the full language model response.
stepTimeMs:
number
Total time spent on the step, including language model response time and tool execution time, in milliseconds.
responseTimeMs:
number
Time spent waiting for the language model response in milliseconds.
toolExecutionMs:
Readonly<Record<string, number>>
Time spent executing each client-side tool call in the step in milliseconds, keyed by tool call ID.
timeToFirstOutputMs:
number | undefined
Time until the first generated output chunk was received in milliseconds. Only available for streaming steps.
timeBetweenOutputChunksMs:
OutputChunkTimingStats | undefined
Timing statistics for the gaps between generated output chunks in milliseconds. Only available for streaming steps with at least two output chunks.
rawFinishReason:
string | undefined
The raw reason why the generation finished (from the provider).
providerMetadata?:
ProviderMetadata | undefined
Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.
TextStreamPart
type:
'start'
Indicates the start of the stream.
TextStreamPart
type:
'finish'
The type to identify the object as finish.
rawFinishReason:
string | undefined
The raw reason why the generation finished (from the provider).
totalUsage:
LanguageModelUsage
The total token usage of the generated text.
LanguageModelUsage
inputTokens:
number | undefined
The total number of input (prompt) tokens used.
inputTokenDetails:
LanguageModelInputTokenDetails
Detailed information about the input (prompt) tokens. See also: cached tokens and non-cached tokens.
LanguageModelInputTokenDetails
noCacheTokens:
number | undefined
The number of non-cached input (prompt) tokens used.
cacheReadTokens:
number | undefined
The number of cached input (prompt) tokens read.
cacheWriteTokens:
number | undefined
The number of cached input (prompt) tokens written.
outputTokens:
number | undefined
The number of total output (completion) tokens used.
outputTokenDetails:
LanguageModelOutputTokenDetails
Detailed information about the output (completion) tokens.
LanguageModelOutputTokenDetails
textTokens:
number | undefined
The number of text tokens used.
reasoningTokens:
number | undefined
The number of reasoning tokens used.
totalTokens:
number | undefined
The total number of tokens used.
raw?:
object | undefined
Raw usage information from the provider. This is the provider's original usage information and may include additional fields.
TextStreamPart
type:
'reasoning-part-finish'
Indicates the end of a reasoning part.
TextStreamPart
type:
'error'
The type to identify the object as error.
error:
unknown
Describes the error that may have occurred during execution.
TextStreamPart
type:
'abort'
The type to identify the object as abort.
reason?:
string
Optional serialized abort reason when the stream is aborted.
fullStream:
AsyncIterable<TextStreamPart<TOOLS>> & ReadableStream<TextStreamPart<TOOLS>>
Deprecated. Use stream instead. A stream with all events, including text deltas, tool calls, tool results, and errors.
partialOutputStream:
AsyncIterableStream<PARTIAL_OUTPUT>
A stream of partial parsed outputs. It uses the output specification. AsyncIterableStream is defined as AsyncIterable & ReadableStream.
elementStream:
AsyncIterableStream<ELEMENT_OUTPUT>
A stream of individual array elements as they complete. Only available when using output: Output.array(). Each element is complete and validated against the element schema. When maxItems is set, the stream errors before emitting the first excess element. AsyncIterableStream is defined as AsyncIterable & ReadableStream.
output:
Promise<COMPLETE_OUTPUT>
The complete parsed output. It uses the output specification.
consumeStream:
(options?: ConsumeStreamOptions) => Promise<void>
Consumes the stream without processing the parts. This is useful to force the stream to finish. If an error occurs, it is passed to the optional onError callback.
toUIMessageStream:
(options?: UIMessageStreamOptions) => AsyncIterableStream<UIMessageChunk>
Converts the result to a UI message stream. Returns an AsyncIterableStream that can be used as both an AsyncIterable and a ReadableStream. The stream includes tool approval request and response chunks, including automatic approval metadata when available.
UIMessageStreamOptions
originalMessages?:
UIMessage[]
The original messages.
onStepEnd?:
(event: { messages: UIMessage[]; isContinuation: boolean; responseMessage: UIMessage; }) => PromiseLike<void> | void
Called after each step is converted to UI message parts. Receives the accumulated response message, including step metadata, for inspection or persistence. This UI conversion callback is separate from the generation callback passed to streamText.
onEnd?:
(options: { messages: UIMessage[]; isContinuation: boolean; responseMessage: UIMessage; isAborted: boolean; isCancelled?: true; outcome: UIMessageStreamOutcome; finishReason?: FinishReason; }) => PromiseLike<void> | void
Callback function called when the stream ends. Provides the updated messages, continuation, abort and consumer-cancellation state, model finish reason, and operation-level outcome.
messageMetadata?:
(options: { part: TextStreamPart<TOOLS> & { type: "start" | "finish" | "start-step" | "finish-step"; }; }) => unknown
Extracts message metadata that will be sent to the client. Called on start and finish events.
sendReasoning?:
boolean
Send reasoning parts to the client. Defaults to true.
sendSources?:
boolean
Send source parts to the client. Defaults to false.
sendFinish?:
boolean
Send the finish event to the client. Defaults to true.
sendStart?:
boolean
Send the message start event to the client. Set to false if you are using additional streamText calls and the message start event has already been sent. Defaults to true.
onError?:
(error: unknown) => string
Process an error, e.g. to log it. Returns the error message to include in the data stream. Defaults to () => "An error occurred." Handles stream errors. Also handles failed tool calls (tool execution errors and invalid tool calls) when redactToolErrors is enabled, which is the default when this callback is provided. Tool execution errors marked providerExecuted: true bypass this callback: strings pass through unchanged and other values are JSON-stringified to preserve provider error data for model-message round trips and harness runtime error messages. Invalid tool calls of provider-executed tools always use this callback.
redactToolErrors?:
boolean
Replace the error text of failed tool calls (tool execution errors and invalid tool calls) with the result of onError. By default, the client receives the same error text as the model, because the UI messages are sent back to the model on the next request and a different text changes the message history. Defaults to true when onError is provided, and to false otherwise.
consumeSseStream?:
(stream: ReadableStream) => Promise<void>
Function to consume the SSE stream. Required for proper abort handling in UI message streams. Use the consumeStream function from the AI SDK.
pipeTextStreamToResponse:
(response: ServerResponse, init?: ResponseInit) => Promise<void>
Writes text delta output to a Node.js response-like object. It sets a Content-Type header to text/plain; charset=utf-8 and writes each text delta as a separate chunk.
ResponseInit
status?:
number
The response status code.
statusText?:
string
The response status text.
headers?:
Record<string, string>
The response headers.
toUIMessageStreamResponse:
(options?: ResponseInit & UIMessageStreamOptions) => Response
Converts the result to a streamed response object with a UI message stream.
ResponseInit & UIMessageStreamOptions
status?:
number
The response status code.
statusText?:
string
The response status text.
headers?:
HeadersInit
The response headers.
toTextStreamResponse:
(init?: ResponseInit) => Response
Creates a simple text stream response. Each text delta is encoded as UTF-8 and sent as a separate chunk. Non-text-delta events are ignored.
ResponseInit
status?:
number
The response status code.
statusText?:
string
The response status text.
headers?:
Record<string, string>
The response headers.

Types

ActiveTools

type ActiveTools<TOOLS extends ToolSet> =
  | ReadonlyArray<keyof TOOLS & string>
  | undefined;

Limits a generation step to the listed tool names. undefined means no tool restriction is applied.

Examples