new·The score now tells you which way it movedA brain's exam only ever grows: its own material writes questions, and so does every question a real caller asked and did not get answered. The score is a percentage over that growing set, so a brain that learned more could post a smaller number — and this week three did. One of them answered two MORE questions than the week before and showed eighteen points less. Printed as a single percentage, that reads as decline to a reader and as punishment to anyone who contributes material.all news →
mozg.beta
Sign in

AI SDK · Core · all subjects

core api options & defaults

57 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

maxOutputTokens default value or common usage in streamText

In the streamText example, maxOutputTokens is set to 1024, demonstrating a typical usage pattern where this parameter limits the maximum length of the generated response.

streamText maxOutputTokens parameter

The streamText function accepts maxOutputTokens as a parameter, set to 512 in this example.

LanguageModelUsage object structure

The LanguageModelUsage object contains three properties: inputTokens (tokens in the prompt), outputTokens (tokens in the completion), and totalTokens (sum of input and output tokens).

generateText performance metrics available in result

Each step in generateText includes performance metrics: effectiveOutputTokensPerSecond (outputTokens / requestSeconds), outputTokensPerSecond (undefined for generateText), inputTokensPerSecond (undefined for generateText), effectiveTotalTokensPerSecond ((inputTokens + outputTokens) / requestSeconds), stepTimeMs (total time on step including LLM and tool execution), responseTimeMs (time waiting for LLM response), toolExecutionMs (time executing each client-side tool call, keyed by tool call ID), timeToFirstOutputMs (undefined for generateText), timeBetweenOutputChunksMs (undefined for generateText).

streamText performance metrics for streaming

For streamText, timeToFirstOutputMs is set when the first generated output chunk is received for a step. timeBetweenOutputChunksMs includes min, p10, median, avg, p90, and max when at least two output chunks are received.

LanguageModelUsage structure in StepResult

LanguageModelUsage in StepResult includes: inputTokens (number | undefined, total input tokens), inputTokenDetails (LanguageModelInputTokenDetails with noCacheTokens, cacheReadTokens, cacheWriteTokens), outputTokens (number | undefined, total output tokens), outputTokenDetails (LanguageModelOutputTokenDetails with textTokens and reasoningTokens), totalTokens (number | undefined), and raw (object | undefined, provider's original usage information).

generateText required and optional parameters

generateText accepts the following parameters: Required: - model (LanguageModel): The language model to use. Example: openai('gpt-4o') Optional: - instructions (Instructions): Instructions to use that specify the behavior of the model. - prompt (string | Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>): The input prompt to generate the text from. - messages (Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>): A list of messages that represent a conversation. Automatically converts UI messages from the useChat hook. - 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. - 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"): 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. If reasoning-related providerOptions are also set, they take precedence and this parameter is ignored. - maxRetries (number): Maximum number of retries. Set to 0 to disable retries. Default: 2. - abortSignal (AbortSignal): An optional abort signal that can be used to cancel the call. - timeout (number | { totalMs?: number; stepMs?: number; toolMs?: number; tools?: { [toolName]Ms?: number } }): Timeout in milliseconds. Can be specified as a number or as an object with totalMs, stepMs, toolMs, and/or tools properties. totalMs sets the total timeout for the entire call. stepMs sets the timeout for each individual step (LLM call). 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. 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. - 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. - 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. - experimental_toolCallers (Experimental_ToolCallers<TOOLS>): Configures which caller tools may invoke each tool. The callback receives typed references for caller-capable tools in the tools set and returns an object keyed by callee tool name. - 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. - 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. - 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. - experimental_download ((requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>): Custom download function to control how URLs are fetched when they appear in prompts. - include ({ requestBody?: boolean; requestMessages?: boolean; responseBody?: boolean }): Controls inclusion of request bodies, request messages, and response bodies in step results. By default, request bodies, request messages, and response bodies are excluded to reduce memory usage. - 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. - output (Output): Specification for parsing structured outputs from the LLM response. - onStart ((event: GenerateTextStartEvent) => PromiseLike<void> | void): Callback that is called when the generateText operation begins, before any LLM calls are made. Errors thrown in this callback are silently caught and do not break the generation flow. - onStepStart ((event: GenerateTextStepStartEvent) => PromiseLike<void> | void): Callback that is called when a step (LLM call) begins, before the provider is called. Errors thrown in this callback are silently caught and do not break the generation flow. - 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. - 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.

TelemetryOptions interface for generateText

TelemetryOptions accepted by generateText contains: - isEnabled (boolean, optional): Enable or disable telemetry. Enabled by default. Set to false to opt out. - recordInputs (boolean, optional): Enable or disable input recording. Enabled by default. - recordOutputs (boolean, optional): Enable or disable output recording. Enabled by default. - functionId (string, optional): Identifier for this function. Used to group telemetry data by function. - includeRuntimeContext ({ [KEY in keyof CONTEXT]?: boolean }, optional): 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 } }, optional): 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[], optional): Per-call telemetry integrations that receive lifecycle events. When provided, these replace any globally registered integrations for this call.

generateText onStart callback structure

The onStart callback receives a GenerateTextStartEvent with the following properties: - provider (string): The provider identifier (e.g., "openai", "anthropic"). - modelId (string): The specific model identifier (e.g., "gpt-4o"). - 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; chunkMs?: number } | undefined): Timeout configuration for the generation. - 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; responseBody?: boolean } | undefined): Settings for controlling what data is included in step results. - runtimeContext (CONTEXT): User-defined shared runtime context object that flows through the generation lifecycle. - toolsContext (InferToolSetContext<TOOLS>): Per-tool context map passed via toolsContext, keyed by tool name.

generateText onStepStart callback structure

The onStepStart callback receives a GenerateTextStepStartEvent with the following properties: - 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-4o"). - 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 first step). - providerOptions (ProviderOptions | undefined): Additional provider-specific options for this step. - timeout (number | { totalMs?: number; stepMs?: number; chunkMs?: number } | undefined): Timeout configuration for the generation. - headers (Record<string, string | undefined> | undefined): Additional HTTP headers sent with the request. - stopWhen (StopCondition<TOOLS> | Array<StopCondition<TOOLS>> | undefined): Condition(s) for stopping the generation. When the condition is an array, any of the conditions can be met to stop. - 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; responseBody?: 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.

generateText onLanguageModelCallStart callback structure

The onLanguageModelCallStart callback receives a LanguageModelCallStartEvent with the following properties: - 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.

generateText include parameter options

The include parameter accepts an object with the following optional properties: - requestBody (boolean, optional): Whether to include the request body in step results. The request body can be large when sending images or files. Default: false. - requestMessages (boolean, optional): Whether to include the request messages in step results. The request messages can be large when sending images or files. Default: false. - responseBody (boolean, optional): Whether to include the response body in step results. Default: false.

generateText timeout configuration options

The timeout parameter can be specified as a number (milliseconds) or as an object with the following properties: - totalMs (number, optional): Sets the total timeout for the entire call. - stepMs (number, optional): Sets the timeout for each individual step (LLM call). - toolMs (number, optional): Sets the default timeout for all tool executions. - tools (object, optional): 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.

onToolExecutionStart callback signature and properties

onToolExecutionStart is an optional callback with type (event: ToolExecutionStartEvent) => PromiseLike<void> | void. It 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. The ToolExecutionStartEvent has four properties: callId (string, unique identifier for the generation call), toolCall (TypedToolCall<TOOLS>, the full tool call object), messages (Array<ModelMessage>, messages sent to the model), and toolContext (InferToolContext<TOOLS[toolName]>, tool-specific context object narrowed to the individual tool type).

onToolExecutionEnd callback signature and properties

onToolExecutionEnd is an optional callback with type (event: ToolExecutionEndEvent) => PromiseLike<void> | void. It 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. The ToolExecutionEndEvent has five properties: callId (string), toolCall (TypedToolCall<TOOLS>), toolExecutionMs (number, wall-clock duration in milliseconds), messages (Array<ModelMessage>), toolContext (InferToolContext<TOOLS[toolName]>), and toolOutput (ToolOutput<TOOLS>).

Deprecated tool callback aliases

experimental_onToolCallStart (type: (event: ToolExecutionStartEvent) => PromiseLike<void> | void, optional) is deprecated in favor of onToolExecutionStart and only used as a fallback when onToolExecutionStart is not provided. experimental_onToolCallFinish (type: (event: ToolExecutionEndEvent) => PromiseLike<void> | void, optional) is deprecated in favor of onToolExecutionEnd and only used as a fallback when onToolExecutionEnd is not provided.

onStepEnd callback and StepResult structure

onStepEnd is an optional callback with type (stepResult: StepResult<TOOLS>) => Promise<void> | void. It is called when a step ends and receives a StepResult object. StepResult has the following properties: stepNumber (number, zero-based index), model ({ provider: string; modelId: string }), runtimeContext (CONTEXT, user-defined shared runtime context), toolsContext (InferToolSetContext<TOOLS>, per-tool context map), content (Array<ContentPart<TOOLS>>, generated content), text (string, generated text), reasoning (Array<ReasoningPart | ReasoningFilePart>, generated reasoning), reasoningText (string | undefined), files (Array<GeneratedFile>, generated files), sources (Array<Source>, sources used), toolCalls (Array<TypedToolCall<TOOLS>>), staticToolCalls (Array<StaticToolCall<TOOLS>>), dynamicToolCalls (Array<DynamicToolCall>), toolResults (Array<TypedToolResult<TOOLS>>), staticToolResults (Array<StaticToolResult<TOOLS>>), dynamicToolResults (Array<DynamicToolResult>), finishReason ('stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other'), rawFinishReason (string | undefined, from provider), usage (LanguageModelUsage), performance (StepResultPerformance, streaming-only metrics are undefined for generateText), warnings (CallWarning[] | undefined), request (LanguageModelRequestMetadata), response (LanguageModelResponseMetadata), providerMetadata (ProviderMetadata | undefined), and responseMessages (Array<ResponseMessage>).

StepResultPerformance metrics structure

StepResultPerformance includes: effectiveOutputTokensPerSecond (number), outputTokensPerSecond (number | undefined, undefined for generateText as response is not streamed), inputTokensPerSecond (number | undefined, undefined for generateText), effectiveTotalTokensPerSecond (number), stepTimeMs (number, total time including model response and tool execution), responseTimeMs (number, time waiting for model response), toolExecutionMs (Readonly<Record<string, number>>, time for each tool execution keyed by tool call ID), timeToFirstOutputMs (number | undefined, undefined for generateText), and timeBetweenOutputChunksMs (OutputChunkTimingStats | undefined, undefined for generateText).

onEnd callback signature and GenerateTextEndEvent

onEnd is an optional callback with type (event: GenerateTextEndEvent<TOOLS>) => PromiseLike<void> | void. It is called when the entire generation completes (all steps finished). The event includes the final step result properties, excluding direct performance, along with aggregated data from all steps. Use event.steps for per-step performance metrics. GenerateTextEndEvent includes: stepNumber (number), model ({ provider: string; modelId: string }), finishReason ('stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other'), rawFinishReason (string | undefined), usage (LanguageModelUsage from final step only, not aggregated), totalUsage (LanguageModelUsage aggregated across all steps), content (Array<ContentPart<TOOLS>>), providerMetadata (ProviderMetadata | undefined), text (string), reasoningText (string | undefined), reasoning (Array<ReasoningDetail>), sources (Array<Source>), files (Array<GeneratedFile>), toolCalls (Array<TypedToolCall<TOOLS>>), staticToolCalls (Array<StaticToolCall<TOOLS>>), dynamicToolCalls (Array<DynamicToolCall>), toolResults (Array<TypedToolResult<TOOLS>>), staticToolResults (Array<StaticToolResult<TOOLS>>), dynamicToolResults (Array<DynamicToolResult>), warnings (CallWarning[] | undefined), request (LanguageModelRequestMetadata), response (LanguageModelResponseMetadata), steps (Array<StepResult>, response information for every step), finalStep (StepResult, shortcut for steps.at(-1)), responseMessages (Array<ResponseMessage>), runtimeContext (CONTEXT, deprecated—use finalStep.runtimeContext instead), and toolsContext (InferToolSetContext<TOOLS>, deprecated—use finalStep.toolsContext instead).

ReasoningDetail structure with text type

ReasoningDetail with type 'text' includes: type ('text'), text (string, the text content), and signature (string, optional).

ReasoningDetail structure with redacted type

ReasoningDetail with type 'redacted' includes: type ('redacted') and data (string, the redacted data content).

onFinish deprecated callback

onFinish is a deprecated alias for onEnd.

defaultSettingsMiddleware parameters

defaultSettingsMiddleware accepts a configuration object with the property 'settings', which is an object containing default parameter values to apply to language model calls. These can include any valid LanguageModelV4CallOptions properties and optional provider metadata.

defaultSettingsMiddleware precedence rules

When using defaultSettingsMiddleware, explicitly provided parameters always take precedence over default settings. The middleware merges default settings with each model call's parameters, allowing call-specific values to override the defaults.

streamText parameter: model

The 'model' parameter is of type LanguageModel and is required. It specifies the language model to use, with an example being openai('gpt-4.1').

streamText parameter: instructions

The 'instructions' parameter is of type Instructions and is optional. It specifies instructions that determine the behavior of the model.

streamText parameter: prompt

The 'prompt' parameter accepts either a string or an array of messages (SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage). It is the input prompt to generate text from.

streamText parameter: messages

The 'messages' parameter accepts an array of message objects (SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage) representing a conversation. It automatically converts UI messages from the useChat hook.

UserModelMessage content types

UserModelMessage can contain content as either a string or an array of message parts: TextPart (type: 'text' with text: string), ImagePart (type: 'image' with image: string | Uint8Array | Buffer | ArrayBuffer | URL and optional mediaType: string), or FilePart (type: 'file' with data: string | Uint8Array | Buffer | ArrayBuffer | URL and mediaType: string).

AssistantModelMessage content types

AssistantModelMessage can contain content as either a string or an array of: TextPart (type: 'text' with text: string), ReasoningPart (type: 'reasoning' with text: string), ReasoningFilePart (type: 'reasoning-file' with data: string | Uint8Array | Buffer | ArrayBuffer | URL and mediaType: string), FilePart (type: 'file' with data, mediaType: string, and optional filename: string), or ToolCallPart (type: 'tool-call' with toolCallId: string, toolName: string, and input: object based on zod schema).

streamText parameter: allowSystemInMessages

The 'allowSystemInMessages' parameter is of type boolean and is optional, defaulting to false. When enabled, system messages are allowed in the 'prompt' or 'messages' fields. System messages in the 'instructions' option are always allowed. Enabling this for user-controlled messages can create a prompt injection risk.

streamText parameter: temperature

The 'temperature' parameter is of type number and is optional. 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.

streamText parameter: topP

The 'topP' parameter is of type number and is optional. It represents 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.

streamText parameter: topK

The 'topK' parameter is of type number and is optional. It specifies to only sample from the top K options for each subsequent token, used to remove low probability responses. Recommended for advanced use cases only.

streamText parameter: presencePenalty

The 'presencePenalty' parameter is of type number and is optional. It affects the likelihood of the model to repeat information already in the prompt. The value is passed through to the provider and the range depends on the provider and model.

streamText parameter: frequencyPenalty

The 'frequencyPenalty' parameter is of type number and is optional. It affects the likelihood of the model to repeatedly use the same words or phrases. The value is passed through to the provider and the range depends on the provider and model.

streamText parameter: seed

The 'seed' parameter is of type number and is optional. It is used for random sampling. If set and supported by the model, calls will generate deterministic results.

streamText parameter: reasoning

The 'reasoning' parameter is of type '"provider-default" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh"' and is optional. It 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. If reasoning-related providerOptions are also set, they take precedence.

streamText parameter: maxRetries

The 'maxRetries' parameter is of type number and is optional, with a default of 2. It specifies the maximum number of retries. Set to 0 to disable retries.

streamText parameter: timeout

The 'timeout' parameter can be specified as a number (timeout in milliseconds) or as an object with properties: totalMs (total timeout for entire call), stepMs (timeout for each individual step/LLM call), firstChunkMs (timeout until first content-bearing output in each step), chunkMs (timeout between content-bearing chunks after output has started), toolMs (default timeout for all tool executions), and tools (per-tool timeout overrides using pattern {toolName}Ms). If a tool takes longer than its timeout, it aborts and returns a tool-error. Can be used alongside abortSignal.

streamText parameter: headers

The 'headers' parameter is of type Record<string, string | undefined> and is optional. It specifies additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.

streamText parameter: telemetry

The 'telemetry' parameter is of type TelemetryOptions and is optional. It provides telemetry configuration for the call.

TelemetryOptions structure

TelemetryOptions contains: isEnabled (optional boolean, enabled by default, set to false to opt out), recordInputs (optional boolean, enabled by default), recordOutputs (optional boolean, enabled by default), functionId (optional string for grouping telemetry), includeRuntimeContext (optional object mapping runtime context keys to booleans), includeToolsContext (optional object mapping tool names to context property mappings), and integrations (optional Telemetry or Telemetry[] for per-call telemetry integrations that replace globally registered ones).

streamText parameter: experimental_transform

The 'experimental_transform' parameter is of type StreamTextTransform | Array<StreamTextTransform> and is optional. It specifies optional stream transformations applied in the order provided. Stream transformations must maintain the stream structure for streamText to work correctly. Each transform receives options with stopStream function and available tools, and must return a TransformStream<TextStreamPart<TOOLS>, TextStreamPart<TOOLS>>.

streamText parameter: includeRawChunks (deprecated)

The 'includeRawChunks' parameter is deprecated. Use include.rawChunks instead. When enabled, raw chunks with type 'raw' containing unprocessed provider data are included in the stream. Defaults to false.

streamText parameter: runtimeContext

The 'runtimeContext' parameter is of type CONTEXT and is optional. It is a user-defined shared runtime context object passed to prepareStep and lifecycle callbacks.

streamText parameter: experimental_sandbox

The 'experimental_sandbox' parameter is of type Experimental_SandboxSession and is optional. It is an experimental sandbox environment passed through to prepareStep, tool description functions, and tool execution. Tools can access it from their description function options and execution options.

streamText parameter: experimental_download

The 'experimental_download' parameter is of type function (requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>> and is optional. It is a custom download function to control how URLs are fetched when they appear in prompts. Return null to pass the URL directly to the model (when supported), or return downloaded content with data and media type. By default, files are downloaded if the model does not support the URL for the given media type.

streamText parameter: include

The 'include' parameter is of type { requestBody?: boolean; requestMessages?: boolean; rawChunks?: boolean } and is optional. It controls inclusion of request body and request messages in step results, and raw provider chunks in the stream. By default, all are excluded to reduce memory usage. Set requestBody or requestMessages to true to access that data. Set rawChunks to true to access raw provider chunks.

streamText parameter: onChunk

The 'onChunk' parameter is of type function (event: OnChunkResult) => Promise<void> | void and is optional. It is a callback called for each stream part. Stream processing will pause until the callback promise is resolved.

OnChunkResult structure

OnChunkResult contains a chunk property of type TextStreamPart<TOOLS>, which is the same union as 'stream' and includes types: start, 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, and raw.

streamText TextStreamPart types

TextStreamPart types include: text-delta (type: 'text-delta', text: string), reasoning-delta (type: 'reasoning-delta', text: string), source (type: 'source', source: Source), custom (type: 'custom', kind: string with format {provider}.{provider-type}, optional providerMetadata: ProviderMetadata), tool-call (type: 'tool-call', toolCallId: string, toolName: string, input: object based on zod schema), tool-input-start (type: 'tool-input-start', id: string, toolName: string), tool-input-delta (type: 'tool-input-delta', id: string, toolName: string, delta: string), tool-result (type: 'tool-result', toolCallId: string, toolName: string, input: object based on zod schema, output: any).

streamText parameter: onError

The 'onError' parameter is of type function (event: OnErrorResult) => Promise<void> | void and is optional. It is a callback called when an error occurs during streaming. It receives OnErrorResult with error: unknown property. Can be used to log errors.

StepResultPerformance metrics in streamText

Performance metrics available in StepResult include: effectiveOutputTokensPerSecond (number), outputTokensPerSecond (number | undefined, streaming only), inputTokensPerSecond (number | undefined, streaming only), effectiveTotalTokensPerSecond (number), stepTimeMs (number), responseTimeMs (number), toolExecutionMs (Readonly<Record<string, number>>), timeToFirstOutputMs (number | undefined, streaming only), and timeBetweenOutputChunksMs (OutputChunkTimingStats | undefined, streaming with at least two chunks).

LanguageModelUsage token tracking structure

LanguageModelUsage tracks: inputTokens (number | undefined), inputTokenDetails (LanguageModelInputTokenDetails with noCacheTokens, cacheReadTokens, cacheWriteTokens), outputTokens (number | undefined), outputTokenDetails (LanguageModelOutputTokenDetails with textTokens and reasoningTokens), totalTokens (number | undefined), and raw (object | undefined with provider's original usage information).

providerOptions parameter

providerOptions (optional, Record<string, JSONObject> | undefined): Provider-specific options. The outer key is the provider name and the inner values are metadata. Details depend on the provider.

maxOutputTokens parameter

maxOutputTokens (optional, number): Maximum number of tokens to generate. Used in both streamUI and streamText functions.

Give your agent this brain