ai
Version:
AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.
1,409 lines (1,378 loc) • 105 kB
TypeScript
import * as _ai_sdk_provider from '@ai-sdk/provider';
import { EmbeddingModelV4Embedding, LanguageModelV4, LanguageModelV3, LanguageModelV2, SharedV4Warning, LanguageModelV4Source, SharedV4ProviderMetadata, LanguageModelV4Usage, JSONObject, LanguageModelV4CallOptions, LanguageModelV4Prompt, AISDKError, LanguageModelV4ToolCall, JSONSchema7, ProviderV4, ProviderV3, ProviderV2, LanguageModelV4ToolResultOutput, LanguageModelV4ToolChoice, LanguageModelV4FunctionTool, LanguageModelV4ProviderTool } from '@ai-sdk/provider';
import { GatewayModelId } from '@ai-sdk/gateway';
import { ModelMessage, AssistantModelMessage, ToolModelMessage, ProviderOptions, ToolSet, SystemModelMessage, Context, InferToolSetContext, Arrayable, InferToolInput, InferToolOutput, ReasoningPart, ReasoningFilePart, InferToolContext, ToolExecutionOptions, MaybePromiseLike, ToolResultOutput, Tool, Experimental_SandboxSession, RetryFunction, ToolApprovalRequest, ToolApprovalResponse } from '@ai-sdk/provider-utils';
export { convertAsyncIteratorToReadableStream } from '@ai-sdk/provider-utils';
/**
* Embedding.
*/
type Embedding = EmbeddingModelV4Embedding;
declare global {
/**
* Global interface that can be augmented by third-party packages to register custom model IDs.
*
* You can register model IDs in two ways:
*
* 1. Register based on Model IDs from a provider package:
* @example
* ```typescript
* import { openai } from '@ai-sdk/openai';
* type OpenAIResponsesModelId = Parameters<typeof openai>[0];
*
* declare global {
* interface RegisteredProviderModels {
* openai: OpenAIResponsesModelId;
* }
* }
* ```
*
* 2. Register individual model IDs directly as keys:
* @example
* ```typescript
* declare global {
* interface RegisteredProviderModels {
* 'my-provider:my-model': any;
* 'my-provider:another-model': any;
* }
* }
* ```
*/
interface RegisteredProviderModels {
}
}
/**
* Global provider model ID type that defaults to GatewayModelId but can be augmented
* by third-party packages via declaration merging.
*/
type GlobalProviderModelId = [keyof RegisteredProviderModels] extends [
never
] ? GatewayModelId : keyof RegisteredProviderModels | RegisteredProviderModels[keyof RegisteredProviderModels];
/**
* Language model that is used by the AI SDK.
*/
type LanguageModel = GlobalProviderModelId | LanguageModelV4 | LanguageModelV3 | LanguageModelV2;
/**
* Reason why a language model finished generating a response.
*
* Can be one of the following:
* - `stop`: model generated stop sequence
* - `length`: model generated maximum number of tokens
* - `content-filter`: content filter violation stopped the model
* - `tool-calls`: model triggered tool calls
* - `error`: model stopped because of an error
* - `other`: model stopped for other reasons
*/
type FinishReason = 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other';
/**
* Warning from the model provider for this call. The call will proceed, but e.g.
* some settings might not be supported, which can lead to suboptimal results.
*/
type CallWarning = SharedV4Warning;
/**
* A source that has been used as input to generate the response.
*/
type Source = LanguageModelV4Source;
/**
* Tool choice for the generation. It supports the following settings:
*
* - `auto` (default): the model can choose whether and which tools to call.
* - `required`: the model must call a tool. It can choose which tool to call.
* - `none`: the model must not call tools
* - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool
*/
type ToolChoice<TOOLS extends Record<string, unknown>> = 'auto' | 'none' | 'required' | {
type: 'tool';
toolName: Extract<keyof TOOLS, string>;
};
/**
* Metadata for a language model request.
*/
type LanguageModelRequestMetadata = {
/**
* The input messages that were sent to the model for this step.
*/
readonly messages?: Array<ModelMessage>;
/**
* Request HTTP body that was sent to the provider API.
*/
readonly body?: unknown;
};
/**
* A message that was generated during the generation process.
* It can be either an assistant message or a tool message.
*/
type ResponseMessage = AssistantModelMessage | ToolModelMessage;
/**
* Metadata for a language model response.
*/
type LanguageModelResponseMetadata = {
/**
* The response messages that were generated during the call.
* Response messages can be either assistant messages or tool messages.
* They contain a generated id.
*/
readonly messages: Array<ResponseMessage>;
/**
* ID for the generated response.
*/
readonly id: string;
/**
* Timestamp for the start of the generated response.
*/
readonly timestamp: Date;
/**
* The ID of the response model that was used to generate the response.
*/
readonly modelId: string;
/**
* Response headers (available only for providers that use HTTP requests).
*/
readonly headers?: Record<string, string>;
/**
* Response body (available only for providers that use HTTP requests).
*/
readonly body?: unknown;
};
/**
* Additional provider-specific metadata that is returned from the provider.
*
* This is needed to enable provider-specific functionality that can be
* fully encapsulated in the provider.
*/
type ProviderMetadata = SharedV4ProviderMetadata;
/**
* Represents the number of tokens used in a prompt and completion.
*/
type LanguageModelUsage = {
/**
* The total number of input (prompt) tokens used.
*/
inputTokens: number | undefined;
/**
* Detailed information about the input tokens.
*/
inputTokenDetails: {
/**
* The number of non-cached input (prompt) tokens used.
*/
noCacheTokens: number | undefined;
/**
* The number of cached input (prompt) tokens read.
*/
cacheReadTokens: number | undefined;
/**
* The number of cached input (prompt) tokens written.
*/
cacheWriteTokens: number | undefined;
};
/**
* The number of total output (completion) tokens used.
*/
outputTokens: number | undefined;
/**
* Detailed information about the output tokens.
*/
outputTokenDetails: {
/**
* The number of text tokens used.
*/
textTokens: number | undefined;
/**
* The number of reasoning tokens used.
*/
reasoningTokens: number | undefined;
};
/**
* The total number of tokens used.
*/
totalTokens: number | undefined;
/**
* Raw usage information from the provider.
*
* This is the usage information in the shape that the provider returns.
* It can include additional information that is not part of the standard usage information.
*/
raw?: JSONObject;
};
/**
* Represents the number of tokens used in an embedding.
*/
type EmbeddingModelUsage = {
/**
* The number of tokens used in the embedding.
*/
tokens: number;
};
declare function asLanguageModelUsage(usage: LanguageModelV4Usage): LanguageModelUsage;
declare function createNullLanguageModelUsage(): LanguageModelUsage;
declare function addLanguageModelUsage(usage1: LanguageModelUsage, usage2: LanguageModelUsage): LanguageModelUsage;
/**
* Warning from the model provider for this call. The call will proceed, but e.g.
* some settings might not be supported, which can lead to suboptimal results.
*/
type Warning = SharedV4Warning;
/**
* A function for logging warnings.
*
* You can assign it to the `AI_SDK_LOG_WARNINGS` global variable to use it as the default warning logger.
*
* @example
* ```ts
* globalThis.AI_SDK_LOG_WARNINGS = (options) => {
* console.log('WARNINGS:', options.warnings, options.provider, options.model);
* };
* ```
*/
type LogWarningsFunction = (options: {
/**
* The warnings returned by the model provider.
*/
warnings: Warning[];
/**
* The provider id used for the call, if scoped to a specific provider.
*/
provider?: string;
/**
* The model id used for the call, if scoped to a specific provider.
*/
model?: string;
}) => void;
/**
* Event passed to the `onStart` callback for embed and embedMany operations.
*
* Called when the operation begins, before the embedding model is called.
*/
type EmbedStartEvent = {
/** Unique identifier for this embed call, used to correlate events. */
readonly callId: string;
/** Identifies the operation type (e.g. 'ai.embed' or 'ai.embedMany'). */
readonly operationId: string;
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'text-embedding-3-small'). */
readonly modelId: string;
/** The value(s) being embedded. A string for embed, an array for embedMany. */
readonly value: string | Array<string>;
/** Maximum number of retries for failed requests. */
readonly maxRetries: number;
/** Additional HTTP headers sent with the request. */
readonly headers: Record<string, string | undefined> | undefined;
/** Additional provider-specific options. */
readonly providerOptions: ProviderOptions | undefined;
};
/**
* Event passed to the `onEnd` callback for embed and embedMany operations.
*
* Called when the operation completes, after the embedding model returns.
*/
type EmbedEndEvent = {
/** Unique identifier for this embed call, used to correlate events. */
readonly callId: string;
/** Identifies the operation type (e.g. 'ai.embed' or 'ai.embedMany'). */
readonly operationId: string;
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'text-embedding-3-small'). */
readonly modelId: string;
/** The value(s) that were embedded. A string for embed, an array for embedMany. */
readonly value: string | Array<string>;
/** The resulting embedding(s). A single vector for embed, an array for embedMany. */
readonly embedding: Embedding | Array<Embedding>;
/** Token usage for the embedding operation. */
readonly usage: EmbeddingModelUsage;
/** Warnings from the embedding model, e.g. unsupported settings. */
readonly warnings: Array<Warning>;
/** Optional provider-specific metadata. */
readonly providerMetadata: ProviderMetadata | undefined;
/** Response data including headers and body. A single response for embed, an array for embedMany. */
readonly response: {
headers?: Record<string, string>;
body?: unknown;
} | Array<{
headers?: Record<string, string>;
body?: unknown;
} | undefined> | undefined;
};
/**
* Event fired when an individual embedding model call (inner operation doEmbed) begins.
*
* For `embed`, there is one call. For `embedMany`, there may be multiple
* calls when values are chunked.
*/
type EmbeddingModelCallStartEvent = {
/** Unique identifier for this embed call, used to correlate events. */
readonly callId: string;
/** Unique identifier for this individual doEmbed invocation, used to correlate start/finish within parallel chunks. */
readonly embedCallId: string;
/** Identifies the inner operation (e.g. 'ai.embed.doEmbed' or 'ai.embedMany.doEmbed'). */
readonly operationId: string;
/** The provider identifier. */
readonly provider: string;
/** The specific model identifier. */
readonly modelId: string;
/** The values being embedded in this particular model call. */
readonly values: Array<string>;
};
/**
* Event fired when an individual embedding model call (doEmbed) completes.
*
* Contains the embeddings, usage, and any warnings from the model response.
*/
type EmbeddingModelCallEndEvent = {
/** Unique identifier for this embed call, used to correlate events. */
readonly callId: string;
/** Unique identifier for this individual doEmbed invocation, used to correlate start/finish within parallel chunks. */
readonly embedCallId: string;
/** Identifies the inner operation (e.g. 'ai.embed.doEmbed' or 'ai.embedMany.doEmbed'). */
readonly operationId: string;
/** The provider identifier. */
readonly provider: string;
/** The specific model identifier. */
readonly modelId: string;
/** The values that were embedded in this particular model call. */
readonly values: Array<string>;
/** The resulting embeddings from the model call. */
readonly embeddings: Array<Embedding>;
/** Token usage for this model call. */
readonly usage: EmbeddingModelUsage;
};
/**
* Model-facing generation controls. These settings influence how the model
* generates its response (token limits, sampling, penalties, stop sequences,
* seed, reasoning).
*/
type LanguageModelCallOptions = {
/**
* Maximum number of tokens to generate.
*/
maxOutputTokens?: number;
/**
* Temperature setting. The range depends on the provider and model.
*
* It is recommended to set either `temperature` or `topP`, but not both.
*/
temperature?: number;
/**
* Nucleus sampling. This is a number between 0 and 1.
*
* E.g. 0.1 would mean that only tokens with the top 10% probability mass
* are considered.
*
* It is recommended to set either `temperature` or `topP`, but not both.
*/
topP?: 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.
*/
topK?: number;
/**
* Presence penalty setting. It affects the likelihood of the model to
* repeat information that is already in the prompt.
*
* The presence penalty is a number between -1 (increase repetition)
* and 1 (maximum penalty, decrease repetition). 0 means no penalty.
*/
presencePenalty?: number;
/**
* Frequency penalty setting. It affects the likelihood of the model
* to repeatedly use the same words or phrases.
*
* The frequency penalty is a number between -1 (increase repetition)
* and 1 (maximum penalty, decrease repetition). 0 means no penalty.
*/
frequencyPenalty?: number;
/**
* Stop sequences.
* If set, the model will stop generating text when one of the stop sequences is generated.
* Providers may have limits on the number of stop sequences.
*/
stopSequences?: string[];
/**
* The seed (integer) to use for random sampling. If set and supported
* by the model, calls will generate deterministic results.
*/
seed?: number;
/**
* Reasoning effort level for the model. Controls how much reasoning
* the model performs before generating a response.
*
* Use `'provider-default'` to use the provider's default reasoning level.
* Use `'none'` to disable reasoning (if supported by the provider).
*/
reasoning?: LanguageModelV4CallOptions['reasoning'];
};
/**
* Timeout configuration for API calls. Can be specified as:
* - A number representing milliseconds
* - An object with `totalMs` property for the total timeout in milliseconds
* - An object with `stepMs` property for the timeout of each step in milliseconds
* - An object with `chunkMs` property for the timeout between stream chunks (streaming only)
* - An object with `toolMs` property for the default timeout for all tool executions
* - An object with `tools` property for per-tool timeout overrides using `{toolName}Ms` keys
*/
type TimeoutConfiguration<TOOLS extends ToolSet> = number | {
totalMs?: number;
stepMs?: number;
chunkMs?: number;
toolMs?: number;
tools?: Partial<Record<`${keyof TOOLS & string}Ms`, number>>;
};
/**
* Instructions to include in the prompt. Can be used with `prompt` or `messages`.
*/
type Instructions = string | SystemModelMessage | Array<SystemModelMessage>;
/**
* Prompt part of the AI function options.
* It contains instructions, a simple text prompt, or a list of messages.
*/
type Prompt = {
/**
* Instructions to include in the prompt. Can be used with `prompt` or `messages`.
*/
instructions?: Instructions;
/**
* Instructions to include in the prompt. Can be used with `prompt` or `messages`.
*
* @deprecated Use `instructions` instead.
*/
system?: Instructions;
/**
* Whether system messages are allowed in the `prompt` or `messages` fields.
*
* When disabled, system messages must be provided through the `instructions`
* option.
*
* @default false
*/
allowSystemInMessages?: boolean;
} & ({
/**
* A prompt. It can be either a text prompt or a list of messages.
*
* You can either use `prompt` or `messages` but not both.
*/
prompt: string | Array<ModelMessage>;
/**
* A list of messages.
*
* You can either use `prompt` or `messages` but not both.
*/
messages?: never;
} | {
/**
* A list of messages.
*
* You can either use `prompt` or `messages` but not both.
*/
messages: Array<ModelMessage>;
/**
* A prompt. It can be either a text prompt or a list of messages.
*
* You can either use `prompt` or `messages` but not both.
*/
prompt?: never;
});
/**
* Event passed to the `onStart` callback of
* `generateObject` and `streamObject`.
*
* Called when the operation begins, before any LLM call.
*
* @deprecated
*/
interface GenerateObjectStartEvent {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/** Identifies the operation type (e.g. `'ai.generateObject'` or `'ai.streamObject'`). */
readonly operationId: string;
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'gpt-4o'). */
readonly modelId: string;
/** The system message(s) provided to the model. */
readonly system: Instructions | undefined;
/** The prompt string or array of messages if using the prompt option. */
readonly prompt: string | Array<ModelMessage> | undefined;
/** The messages array if using the messages option. */
readonly messages: Array<ModelMessage> | undefined;
/** Maximum number of tokens to generate. */
readonly maxOutputTokens: number | undefined;
/** Sampling temperature for generation. */
readonly temperature: number | undefined;
/** Top-p (nucleus) sampling parameter. */
readonly topP: number | undefined;
/** Top-k sampling parameter. */
readonly topK: number | undefined;
/** Presence penalty for generation. */
readonly presencePenalty: number | undefined;
/** Frequency penalty for generation. */
readonly frequencyPenalty: number | undefined;
/** Random seed for reproducible generation. */
readonly seed: number | undefined;
/** Maximum number of retries for failed requests. */
readonly maxRetries: number;
/** Additional HTTP headers sent with the request. */
readonly headers: Record<string, string | undefined> | undefined;
/** Additional provider-specific options. */
readonly providerOptions: ProviderOptions | undefined;
/** The output strategy type. */
readonly output: 'object' | 'array' | 'enum' | 'no-schema';
/** The JSON Schema used for object generation, if any. */
readonly schema: Record<string, unknown> | undefined;
/** Optional name of the schema. */
readonly schemaName: string | undefined;
/** Optional description of the schema. */
readonly schemaDescription: string | undefined;
}
/**
* Event passed to the `onStepStart` callback of
* `generateObject` and `streamObject`.
*
* Called when the model call (step) begins, before the provider is called.
* For object generation, there is always exactly one step (step 0).
*
* @deprecated
*/
interface GenerateObjectStepStartEvent {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/** Zero-based index of the current step. Always `0` for object generation. */
readonly stepNumber: 0;
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'gpt-4o'). */
readonly modelId: string;
/** Additional provider-specific options. */
readonly providerOptions: ProviderOptions | undefined;
/** Additional HTTP headers sent with the request. */
readonly headers: Record<string, string | undefined> | undefined;
/** The prompt messages in provider format (for telemetry). */
readonly promptMessages?: LanguageModelV4Prompt;
}
/**
* Event passed to the `onStepEnd` callback of
* `generateObject` and `streamObject`.
*
* Called when the model call (step) completes, with the raw result
* before JSON parsing and schema validation.
*
* @deprecated
*/
interface GenerateObjectStepEndEvent {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/** Zero-based index of the current step. Always `0` for object generation. */
readonly stepNumber: 0;
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'gpt-4o'). */
readonly modelId: string;
/** The unified reason why the generation finished. */
readonly finishReason: FinishReason;
/** The token usage of the generated response. */
readonly usage: LanguageModelUsage;
/** The raw text output from the model (before JSON parsing). */
readonly objectText: string;
/** The reasoning generated by the model, if any. */
readonly reasoning: string | undefined;
/** Warnings from the model provider (e.g. unsupported settings). */
readonly warnings: CallWarning[] | undefined;
/** Additional request information. */
readonly request: Omit<LanguageModelRequestMetadata, 'messages'>;
/** Additional response information. */
readonly response: Omit<LanguageModelResponseMetadata, 'messages'>;
/** Additional provider-specific metadata. */
readonly providerMetadata: ProviderMetadata | undefined;
/** Milliseconds from the start of the stream to the first chunk (streaming only). */
readonly msToFirstChunk: number | undefined;
}
/**
* Event passed to the `onFinish` callback of
* `generateObject` and `streamObject`.
*
* Called when the entire operation completes, including JSON parsing
* and schema validation. For `streamObject`, the object may be undefined
* if validation failed (the error is provided in that case).
*
* @deprecated
*/
interface GenerateObjectEndEvent<RESULT> {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/**
* The generated object (typed according to the schema).
* Always defined for `generateObject`. May be `undefined` for `streamObject`
* when parsing or validation fails.
*/
readonly object: RESULT | undefined;
/**
* Error from parsing or schema validation, if any.
* Always `undefined` for `generateObject` (which throws instead).
*/
readonly error: unknown | undefined;
/** The reasoning generated by the model, if any. */
readonly reasoning: string | undefined;
/** The unified reason why the generation finished. */
readonly finishReason: FinishReason;
/** The token usage of the generated response. */
readonly usage: LanguageModelUsage;
/** Warnings from the model provider (e.g. unsupported settings). */
readonly warnings: CallWarning[] | undefined;
/** Additional request information. */
readonly request: Omit<LanguageModelRequestMetadata, 'messages'>;
/** Additional response information. */
readonly response: Omit<LanguageModelResponseMetadata, 'messages'>;
/** Additional provider-specific metadata. */
readonly providerMetadata: ProviderMetadata | undefined;
}
type StandardizedPrompt = {
/**
* Instructions.
*/
instructions: Instructions | undefined;
/**
* Messages.
*/
messages: ModelMessage[];
};
/**
* Converts a prompt input into a standardized prompt with validated model
* messages.
*
* @param prompt - The prompt definition to standardize.
* Set `allowSystemInMessages` to true to allow system messages in the
* `prompt` or `messages` fields. System messages in the `instructions`
* option are always allowed.
* @returns The standardized prompt.
* @throws {InvalidPromptError} When the prompt is invalid.
*/
declare function standardizePrompt({ allowSystemInMessages, system, instructions, prompt, messages, }: Prompt): Promise<StandardizedPrompt>;
/**
* A callback function that can be used with `notify`.
*/
type Callback<EVENT> = (event: EVENT) => PromiseLike<void> | void;
/**
* Tool names that are enabled for a generation step.
*
* `undefined` means no tool restriction is applied. Tool names are object keys
* at runtime, so the type is restricted to the string keys of the configured
* tool set.
*/
type ActiveTools<TOOLS extends ToolSet> = ReadonlyArray<keyof TOOLS & string> | undefined;
type IncludedContext<CONTEXT extends Context | unknown | never> = {
[KEY in keyof NoInfer<CONTEXT>]?: boolean;
} | undefined;
type IncludedToolsContext<TOOLS extends ToolSet> = {
[TOOL_NAME in keyof NoInfer<InferToolSetContext<TOOLS>>]?: IncludedContext<NoInfer<InferToolSetContext<TOOLS>[TOOL_NAME]>>;
} | undefined;
/**
* Telemetry configuration.
*/
type TelemetryOptions<RUNTIME_CONTEXT extends Context = Context, TOOLS extends ToolSet = ToolSet> = {
/**
* Enable or disable telemetry. Enabled by default when a telemetry
* integration is registered. Set to `false` to opt out.
*/
isEnabled?: boolean;
/**
* Enable or disable input recording. Enabled by default.
*
* You might want to disable input recording to avoid recording sensitive
* information, to reduce data transfers, or to increase performance.
*/
recordInputs?: boolean;
/**
* Enable or disable output recording. Enabled by default.
*
* You might want to disable output recording to avoid recording sensitive
* information, to reduce data transfers, or to increase performance.
*/
recordOutputs?: boolean;
/**
* Identifier for this function. Used to group telemetry data by function.
*/
functionId?: string;
/**
* Top-level runtime context properties that should be included in telemetry.
* Runtime context properties are excluded unless they are explicitly set to `true`.
*/
includeRuntimeContext?: IncludedContext<RUNTIME_CONTEXT>;
/**
* 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`.
*/
includeToolsContext?: IncludedToolsContext<TOOLS>;
/**
* Per-call telemetry integrations that receive lifecycle events during generation.
*
* When provided, these integrations will take precedence over the globally registered
* integrations for this call.
*/
integrations?: Arrayable<Telemetry>;
};
/**
* Download a file from a URL.
*
* @param url - The URL to download from.
* @param maxBytes - Maximum allowed download size in bytes. Defaults to 100 MiB.
* @param abortSignal - An optional abort signal to cancel the download.
* @returns The downloaded data and media type.
*
* @throws DownloadError if the download fails or exceeds maxBytes.
*/
declare const download: ({ url, maxBytes, abortSignal, }: {
url: URL;
maxBytes?: number;
abortSignal?: AbortSignal;
}) => Promise<{
data: Uint8Array<ArrayBufferLike>;
mediaType: string | undefined;
}>;
/**
* Experimental. Can change in patch versions without warning.
*
* Download function. Called with the array of URLs and a boolean indicating
* whether the URL is supported by the model.
*
* The download function can decide for each URL:
* - to return null (which means that the URL should be passed to the model)
* - to download the asset and return the data (incl. retries, authentication, etc.)
*
* Should throw DownloadError if the download fails.
*
* Should return an array of objects sorted by the order of the requested downloads.
* For each object, the data should be a Uint8Array if the URL was downloaded.
* For each object, the mediaType should be the media type of the downloaded asset.
* For each object, the data should be null if the URL should be passed through as is.
*/
type DownloadFunction = (options: Array<{
url: URL;
isUrlSupportedByModel: boolean;
}>) => PromiseLike<Array<{
data: Uint8Array;
mediaType: string | undefined;
} | null>>;
/**
* Default download function.
* Downloads the file if it is not supported by the model.
*/
declare const createDefaultDownloadFunction: (download?: typeof download) => DownloadFunction;
/**
* A generated file.
*/
interface GeneratedFile {
/**
* File as a base64 encoded string.
*/
readonly base64: string;
/**
* File as a Uint8Array.
*/
readonly uint8Array: Uint8Array;
/**
* The IANA media type of the file.
*
* @see https://www.iana.org/assignments/media-types/media-types.xhtml
*/
readonly mediaType: string;
}
/**
* Reasoning output of a text generation. It contains a reasoning.
*/
interface ReasoningOutput {
type: 'reasoning';
/**
* The reasoning text.
*/
text: string;
/**
* Additional provider-specific metadata. They are passed through
* to the provider from the AI SDK and enable provider-specific
* functionality that can be fully encapsulated in the provider.
*/
providerMetadata?: ProviderMetadata;
}
/**
* Reasoning file output of a text generation.
* It contains a file generated as part of reasoning.
*/
interface ReasoningFileOutput {
type: 'reasoning-file';
/**
* The generated file.
*/
file: GeneratedFile;
/**
* Additional provider-specific metadata. They are passed through
* to the provider from the AI SDK and enable provider-specific
* functionality that can be fully encapsulated in the provider.
*/
providerMetadata?: ProviderMetadata;
}
/**
* Create a union of the given object's values, and optionally specify which keys to get the values from.
*
* Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31438) if you want to have this type as a built-in in TypeScript.
*
* @example
* ```
* // data.json
* {
* 'foo': 1,
* 'bar': 2,
* 'biz': 3
* }
*
* // main.ts
* import type {ValueOf} from 'type-fest';
* import data = require('./data.json');
*
* export function getData(name: string): ValueOf<typeof data> {
* return data[name];
* }
*
* export function onlyBar(name: string): ValueOf<typeof data, 'bar'> {
* return data[name];
* }
*
* // file.ts
* import {getData, onlyBar} from './main';
*
* getData('foo');
* //=> 1
*
* onlyBar('foo');
* //=> TypeError ...
*
* onlyBar('bar');
* //=> 2
* ```
* @see https://github.com/sindresorhus/type-fest/blob/main/source/value-of.d.ts
*/
type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];
type BaseToolCall = {
type: 'tool-call';
toolCallId: string;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: JSONObject;
};
/**
* A tool call whose `toolName` maps to a tool in the declared tool set,
* with an `input` type inferred from that tool's input schema.
*/
type StaticToolCall<TOOLS extends ToolSet> = ValueOf<{
[NAME in keyof TOOLS]: BaseToolCall & {
toolName: NAME & string;
input: InferToolInput<TOOLS[NAME]>;
dynamic?: false | undefined;
invalid?: false | undefined;
error?: never;
title?: string;
};
}>;
/**
* A tool call whose `toolName` is only known at runtime, such as an invalid
* or otherwise untyped call that cannot be matched to the declared tool set.
*/
type DynamicToolCall = BaseToolCall & {
toolName: string;
input: unknown;
dynamic: true;
title?: string;
/**
* True if this is caused by an unparsable tool call or
* a tool that does not exist.
*/
invalid?: boolean;
/**
* The error that caused the tool call to be invalid.
*/
error?: unknown;
};
/**
* A tool call returned by text generation, either statically typed from the
* declared tool set or dynamically typed when the tool cannot be inferred.
*/
type TypedToolCall<TOOLS extends ToolSet> = StaticToolCall<TOOLS> | DynamicToolCall;
/**
* Output part that indicates that a tool approval request has been made.
*
* The tool approval request can be approved or denied in the next tool message.
*/
type ToolApprovalRequestOutput<TOOLS extends ToolSet> = {
type: 'tool-approval-request';
/**
* ID of the tool approval request.
*/
approvalId: string;
/**
* Tool call that the approval request is for.
*/
toolCall: TypedToolCall<TOOLS>;
/**
* Flag indicating whether the tool was automatically approved or denied.
*
* @default false
*/
isAutomatic?: boolean;
/**
* HMAC-SHA256 signature binding this approval request to its tool call.
*/
signature?: string;
};
/**
* Output part that indicates that a tool approval response is available.
*/
type ToolApprovalResponseOutput<TOOLS extends ToolSet> = {
type: 'tool-approval-response';
/**
* ID of the tool approval.
*/
approvalId: string;
/**
* Tool call that the approval response is for.
*/
toolCall: TypedToolCall<TOOLS>;
/**
* Flag indicating whether the approval was granted or denied.
*/
approved: boolean;
/**
* Optional reason for the approval or denial.
*/
reason?: string;
/**
* Flag indicating whether the tool call is provider-executed.
* Only provider-executed tool approval responses should be sent to the model.
*/
providerExecuted?: boolean;
};
type StaticToolError<TOOLS extends ToolSet> = ValueOf<{
[NAME in keyof TOOLS]: {
type: 'tool-error';
toolCallId: string;
toolName: NAME & string;
input: InferToolInput<TOOLS[NAME]>;
error: unknown;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: JSONObject;
dynamic?: false | undefined;
title?: string;
};
}>;
type DynamicToolError = {
type: 'tool-error';
toolCallId: string;
toolName: string;
input: unknown;
error: unknown;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: JSONObject;
dynamic: true;
title?: string;
};
type TypedToolError<TOOLS extends ToolSet> = StaticToolError<TOOLS> | DynamicToolError;
type StaticToolResult<TOOLS extends ToolSet> = ValueOf<{
[NAME in keyof TOOLS]: {
type: 'tool-result';
toolCallId: string;
toolName: NAME & string;
input: InferToolInput<TOOLS[NAME]>;
output: InferToolOutput<TOOLS[NAME]>;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: JSONObject;
dynamic?: false | undefined;
preliminary?: boolean;
title?: string;
};
}>;
type DynamicToolResult = {
type: 'tool-result';
toolCallId: string;
toolName: string;
input: unknown;
output: unknown;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: JSONObject;
dynamic: true;
preliminary?: boolean;
title?: string;
};
type TypedToolResult<TOOLS extends ToolSet> = StaticToolResult<TOOLS> | DynamicToolResult;
type ContentPart<TOOLS extends ToolSet> = {
type: 'text';
text: string;
providerMetadata?: ProviderMetadata;
} | {
type: 'custom';
kind: `${string}.${string}`;
providerMetadata?: ProviderMetadata;
} | ReasoningOutput | ReasoningFileOutput | ({
type: 'source';
} & Source) | {
type: 'file';
file: GeneratedFile;
providerMetadata?: ProviderMetadata;
} | ({
type: 'tool-call';
} & TypedToolCall<TOOLS> & {
providerMetadata?: ProviderMetadata;
}) | ({
type: 'tool-result';
} & TypedToolResult<TOOLS> & {
providerMetadata?: ProviderMetadata;
}) | ({
type: 'tool-error';
} & TypedToolError<TOOLS> & {
providerMetadata?: ProviderMetadata;
}) | ToolApprovalRequestOutput<TOOLS> | ToolApprovalResponseOutput<TOOLS>;
/**
* Timing statistics for the gaps between generated output chunks.
*/
type OutputChunkTimingStats = {
/** Shortest observed time between output chunks in milliseconds. */
readonly min: number;
/** 10th percentile time between output chunks in milliseconds. */
readonly p10: number;
/** Median time between output chunks in milliseconds. */
readonly median: number;
/** Average time between output chunks in milliseconds. */
readonly avg: number;
/** 90th percentile time between output chunks in milliseconds. */
readonly p90: number;
/** Longest observed time between output chunks in milliseconds. */
readonly max: number;
};
/**
* Performance metrics for a single step in the generation process.
*/
type StepResultPerformance = {
/**
* Effective number of output tokens per second over the full language model
* response.
*
* Calculated as `outputTokens / requestSeconds`.
*/
readonly effectiveOutputTokensPerSecond: number;
/**
* Number of output tokens per second after the first generated output chunk
* was received.
*
* Only available for streaming steps.
*
* Calculated as `outputTokens / outputStreamSeconds`.
*/
readonly outputTokensPerSecond: number | undefined;
/**
* Number of input tokens processed per second before the first generated
* output chunk was received.
*
* Only available for streaming steps.
*
* Calculated as `inputTokens / ttftSeconds`.
*/
readonly inputTokensPerSecond: number | undefined;
/**
* Effective number of input and output tokens per second over the full
* language model response.
*
* Calculated as `(inputTokens + outputTokens) / requestSeconds`.
*/
readonly effectiveTotalTokensPerSecond: number;
/**
* Total time spent on the step in milliseconds.
*/
readonly stepTimeMs: number;
/**
* Time spent waiting for the language model response in milliseconds.
*/
readonly responseTimeMs: number;
/**
* Time spent executing each client-side tool call in milliseconds, keyed by
* tool call ID.
*/
readonly toolExecutionMs: Readonly<Record<string, number>>;
/**
* Time until the first generated output chunk was received in milliseconds.
*
* This includes text deltas, reasoning deltas, generated files, reasoning
* files, tool input deltas, and tool calls.
*
* Only available for streaming steps.
*/
readonly timeToFirstOutputMs: number | undefined;
/**
* Timing statistics for the gaps between generated output chunks in
* milliseconds.
*
* Only available for streaming steps with at least two generated output
* chunks.
*/
readonly timeBetweenOutputChunksMs?: OutputChunkTimingStats;
};
/**
* The result of a single step in the generation process.
*/
type StepResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context = Context> = {
/**
* Unique identifier for the generation call this step belongs to.
*/
readonly callId: string;
/**
* Zero-based index of this step.
*/
readonly stepNumber: number;
/**
* Information about the model that produced this step.
*/
readonly model: {
/** The provider of the model. */
readonly provider: string;
/** The ID of the model. */
readonly modelId: string;
};
/**
* Tool context.
*/
readonly toolsContext: InferToolSetContext<TOOLS>;
/**
* The runtime context that was used as input for the step.
*/
readonly runtimeContext: RUNTIME_CONTEXT;
/**
* The content that was generated in the last step.
*/
readonly content: Array<ContentPart<TOOLS>>;
/**
* The generated text. Can be an empty string if the model has not generated any text.
*/
readonly text: string;
/**
* The reasoning that was generated during the generation.
*/
readonly reasoning: Array<ReasoningPart | ReasoningFilePart>;
/**
* The reasoning text that was generated during the generation.
*
* It is a concatenation of all reasoning parts (but excluding reasoning file parts).
* Can be undefined if the model has only generated text.
*/
readonly reasoningText: string | undefined;
/**
* The files that were generated during the generation.
*/
readonly files: Array<GeneratedFile>;
/**
* The sources that were used to generate the text.
*/
readonly sources: Array<Source>;
/**
* The tool calls that were made during the generation.
*/
readonly toolCalls: Array<TypedToolCall<TOOLS>>;
/**
* The static tool calls that were made in the last step.
*/
readonly staticToolCalls: Array<StaticToolCall<TOOLS>>;
/**
* The dynamic tool calls that were made in the last step.
*/
readonly dynamicToolCalls: Array<DynamicToolCall>;
/**
* The results of the tool calls.
*/
readonly toolResults: Array<TypedToolResult<TOOLS>>;
/**
* The static tool results that were made in the last step.
*/
readonly staticToolResults: Array<StaticToolResult<TOOLS>>;
/**
* The dynamic tool results that were made in the last step.
*/
readonly dynamicToolResults: Array<DynamicToolResult>;
/**
* The unified reason why the generation finished.
*/
readonly finishReason: FinishReason;
/**
* The raw reason why the generation finished (from the provider).
*/
readonly rawFinishReason: string | undefined;
/**
* The token usage of the generated text.
*/
readonly usage: LanguageModelUsage;
/**
* Performance metrics for the step.
*/
readonly performance: StepResultPerformance;
/**
* Warnings from the model provider (e.g. unsupported settings).
*/
readonly warnings: CallWarning[] | undefined;
/**
* Additional request information.
*/
readonly request: LanguageModelRequestMetadata;
/**
* Additional response information.
*/
readonly response: LanguageModelResponseMetadata;
/**
* Additional provider-specific metadata. They are passed through
* from the provider to the AI SDK and enable provider-specific
* results that can be fully encapsulated in the provider.
*/
readonly providerMetadata: ProviderMetadata | undefined;
};
declare class DefaultStepResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context = Context> implements StepResult<TOOLS, RUNTIME_CONTEXT> {
readonly callId: StepResult<TOOLS, RUNTIME_CONTEXT>['callId'];
readonly stepNumber: StepResult<TOOLS, RUNTIME_CONTEXT>['stepNumber'];
readonly model: StepResult<TOOLS, RUNTIME_CONTEXT>['model'];
readonly toolsContext: StepResult<TOOLS, RUNTIME_CONTEXT>['toolsContext'];
readonly runtimeContext: StepResult<TOOLS, RUNTIME_CONTEXT>['runtimeContext'];
readonly content: StepResult<TOOLS, RUNTIME_CONTEXT>['content'];
readonly finishReason: StepResult<TOOLS, RUNTIME_CONTEXT>['finishReason'];
readonly rawFinishReason: StepResult<TOOLS, RUNTIME_CONTEXT>['rawFinishReason'];
readonly usage: StepResult<TOOLS, RUNTIME_CONTEXT>['usage'];
readonly performance: StepResult<TOOLS, RUNTIME_CONTEXT>['performance'];
readonly warnings: StepResult<TOOLS, RUNTIME_CONTEXT>['warnings'];
readonly request: StepResult<TOOLS, RUNTIME_CONTEXT>['request'];
readonly response: StepResult<TOOLS, RUNTIME_CONTEXT>['response'];
readonly providerMetadata: StepResult<TOOLS, RUNTIME_CONTEXT>['providerMetadata'];
constructor({ callId, stepNumber, provider, modelId, runtimeContext, toolsContext, content, finishReason, rawFinishReason, usage, performance, warnings, request, response, providerMetadata, }: {
callId: StepResult<TOOLS, RUNTIME_CONTEXT>['callId'];
stepNumber: StepResult<TOOLS, RUNTIME_CONTEXT>['stepNumber'];
provider: StepResult<TOOLS, RUNTIME_CONTEXT>['model']['provider'];
modelId: StepResult<TOOLS, RUNTIME_CONTEXT>['model']['modelId'];
runtimeContext: StepResult<TOOLS, RUNTIME_CONTEXT>['runtimeContext'];
toolsContext: StepResult<TOOLS, RUNTIME_CONTEXT>['toolsContext'];
content: StepResult<TOOLS, RUNTIME_CONTEXT>['content'];
finishReason: StepResult<TOOLS, RUNTIME_CONTEXT>['finishReason'];
rawFinishReason: StepResult<TOOLS, RUNTIME_CONTEXT>['rawFinishReason'];
usage: StepResult<TOOLS, RUNTIME_CONTEXT>['usage'];
performance: StepResult<TOOLS, RUNTIME_CONTEXT>['performance'];
warnings: StepResult<TOOLS, RUNTIME_CONTEXT>['warnings'];
request: StepResult<TOOLS, RUNTIME_CONTEXT>['request'];
response: StepResult<TOOLS, RUNTIME_CONTEXT>['response'];
providerMetadata: StepResult<TOOLS, RUNTIME_CONTEXT>['providerMetadata'];
});
get text(): string;
get reasoning(): Array<ReasoningPart | ReasoningFilePart>;
get reasoningText(): string | undefined;
get files(): GeneratedFile[];
get sources(): (({
type: "source";
} & {
type: "source";
sourceType: "url";
id: string;
url: string;
title?: string;
providerMetadata?: _ai_sdk_provider.SharedV4ProviderMetadata;
}) | ({
type: "source";
} & {
type: "source";
sourceType: "document";
id: string;
mediaType: string;
title: string;
filename?: string;
providerMetadata?: _ai_sdk_provider.SharedV4ProviderMetadata;
}))[];
get toolCalls(): (({
type: "tool-call";
} & {
type: "tool-call";
toolCallId: string;
providerExecuted?: boolean;
providerMetadata?: ProviderMetadata;
toolMetadata?: _ai_sdk_provider.JSONObject;
} & {
toolName: string;
input: unknown;
dynamic: true;
title?: string;
invalid?: boolean;
error?: unknown;
} & {
providerMetadata?: ProviderMetadata;
}) | ({
type: "tool-call";
} & StaticToolCall<TOOLS> & {
providerMetadata?: ProviderMetadata;
}))[];
get staticToolCalls(): StaticToolCall<TOOLS>[];
get dynamicToolCalls(): DynamicToolCall[];
get toolResults(): (({
type: "tool-result";
} & DynamicToolResult & {
providerMetadata?: ProviderMetadata;
}) | ({
type: "tool-result";
} & StaticToolResult<TOOLS> & {
providerMetadata?: ProviderMetadata;
}))[];
get staticToolResults(): StaticToolResult<TOOLS>[];
get dynamicToolResults(): DynamicToolResult[];
}
/**
* Common model information used across callback events.
*/
type ModelInfo = {
/** The provider identifier (e.g., 'openai', 'anthropic'). */
readonly provider: string;
/** The specific model identifier (e.g., 'gpt-4o'). */
readonly modelId: string;
};
/**
* Event passed to the `onLanguageModelCallStart` callback.
*
* Called immediately before the provider model call begins.
* Unlike `onStepStart`, this only represents model invocation work.
*/
type LanguageModelCallStartEvent = ModelInfo & {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/** Prepared tool definitions for the model call, if any. */
readonly tools: ReadonlyArray<Record<string, unknown>> | undefined;
} & StandardizedPrompt & LanguageModelCallOptions;
/**
* Event passed to the `onLanguageModelCallEnd` callback.
*
* Called after the model response has been normalized and parsed, but before
* any client-side tool execution begins.
*/
type LanguageModelCallEndEvent<TOOLS extends ToolSet = ToolSet> = ModelInfo & {
/** Unique identifier for this generation call, used to correlate events. */
readonly callId: string;
/** The unified reason why the model call finished. */
readonly finishReason: FinishReason;
/** The token usage reported by the model call. */
readonly usage: LanguageModelUsage;
/** The content parts produced by the model call. */
readonly content: ReadonlyArray<ContentPart<TOOLS>>;
/** The provider-returned response id for this model call. */
readonly responseId: string;
/** Performance metrics for the model call. */
readonly performance: {
/** Time spent waiting for the language model response in milliseconds. */
readonly responseTimeMs: number;
/**
* Effective number of output tokens per second over the full language
* model response.
*/
readonly effectiveOutputTokensPerSecond: number;
/**
* Number of output tokens per second af