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,367 lines (1,321 loc) • 362 kB
TypeScript
import * as _ai_sdk_provider from '@ai-sdk/provider';
import { EmbeddingModelV4, EmbeddingModelV3, EmbeddingModelV2, EmbeddingModelV4Embedding, EmbeddingModelV4Middleware, ImageModelV4, ImageModelV3, ImageModelV2, ImageModelV4ProviderMetadata, ImageModelV2ProviderMetadata, ImageModelV4Middleware, JSONValue as JSONValue$1, LanguageModelV4, LanguageModelV3, LanguageModelV2, SharedV4Warning, LanguageModelV4Source, LanguageModelV4Middleware, RerankingModelV4, RerankingModelV3, SharedV4ProviderMetadata, SharedV4ProviderReference, SpeechModelV4, SpeechModelV3, SpeechModelV2, TranscriptionModelV4, TranscriptionModelV3, TranscriptionModelV2, JSONObject, ImageModelV4Usage, LanguageModelV4CallOptions, LanguageModelV4Prompt, AISDKError, LanguageModelV4ToolCall, JSONSchema7, ProviderV4, ProviderV3, ProviderV2, SharedV4Headers, JSONParseError, TypeValidationError, Experimental_VideoModelV4, Experimental_VideoModelV3, Experimental_VideoModelV4FrameType, EmbeddingModelV4CallOptions, Experimental_RealtimeFactoryV4, Experimental_RealtimeFactoryV4GetTokenOptions, Experimental_RealtimeFactoryV4GetTokenResult, Experimental_RealtimeModelV4, Experimental_RealtimeModelV4ClientEvent, Experimental_RealtimeModelV4ServerEvent, Experimental_RealtimeModelV4SessionConfig, Experimental_RealtimeModelV4ToolDefinition, FilesV4, SkillsV4, NoSuchModelError, FilesV4UploadFileCallOptions, SkillsV4UploadSkillResult, SkillsV4UploadSkillCallOptions, SkillsV4File } from '@ai-sdk/provider';
export { AISDKError, APICallError, EmptyResponseBodyError, InvalidPromptError, InvalidResponseDataError, JSONParseError, JSONSchema7, LoadAPIKeyError, LoadSettingError, NoContentGeneratedError, NoSuchModelError, NoSuchProviderReferenceError, TooManyEmbeddingValuesForCallError, TypeValidationError, UnsupportedFunctionalityError } from '@ai-sdk/provider';
import { GatewayModelId } from '@ai-sdk/gateway';
export { GatewayModelId, createGateway, gateway } from '@ai-sdk/gateway';
import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
import { ModelMessage, AssistantModelMessage, ToolModelMessage, ProviderOptions, ToolSet, SystemModelMessage, UserModelMessage, DataContent, FlexibleSchema, InferSchema, Context, Arrayable, InferToolSetContext, InferToolInput, InferToolOutput, ReasoningPart, ReasoningFilePart, Experimental_SandboxSession, Tool, ToolCall, IdGenerator, ToolExecutionOptions, MaybePromiseLike, InferToolContext, HasRequiredKey, TextPart, FilePart, Resolvable, FetchFunction } from '@ai-sdk/provider-utils';
export { AssistantContent, AssistantModelMessage, DataContent, DownloadError, Experimental_SandboxProcess, Experimental_SandboxSession, FilePart, FlexibleSchema, IdGenerator, ImagePart, InferSchema, InferToolInput, InferToolOutput, ModelMessage, Schema, SystemModelMessage, TextPart, Tool, ToolApprovalRequest, ToolApprovalResponse, ToolCallPart, ToolContent, ToolExecuteFunction, ToolExecutionOptions, ToolModelMessage, ToolResultPart, ToolSet, UserContent, UserModelMessage, asSchema, createIdGenerator, dynamicTool, generateId, jsonSchema, parseJsonEventStream, tool, zodSchema } from '@ai-sdk/provider-utils';
import { ServerResponse } from 'node:http';
import { ServerResponse as ServerResponse$1 } from 'http';
import { z } from 'zod/v4';
/**
* Embedding model that is used by the AI SDK.
*/
type EmbeddingModel = string | EmbeddingModelV4 | EmbeddingModelV3 | EmbeddingModelV2<string>;
/**
* Embedding.
*/
type Embedding = EmbeddingModelV4Embedding;
/**
* Middleware for embedding models.
* Accepts both V3 and V4 middleware types for backward compatibility.
*
* Uses EmbeddingModelV4Middleware as the base but relaxes specificationVersion
* to accept any string (including 'v3') and makes it optional.
*/
type EmbeddingModelMiddleware = Omit<EmbeddingModelV4Middleware, 'specificationVersion'> & {
readonly specificationVersion?: string;
};
/**
* Image model that is used by the AI SDK.
*/
type ImageModel = string | ImageModelV4 | ImageModelV3 | ImageModelV2;
/**
* Metadata from the model provider for this call.
*/
type ImageModelProviderMetadata = ImageModelV4ProviderMetadata | ImageModelV2ProviderMetadata;
/**
* Middleware for image models.
* Accepts both V3 and V4 middleware types for backward compatibility.
*
* Uses ImageModelV4Middleware as the base but relaxes specificationVersion
* to accept any string (including 'v3') and makes it optional.
*/
type ImageModelMiddleware = Omit<ImageModelV4Middleware, 'specificationVersion'> & {
readonly specificationVersion?: string;
};
type ImageModelResponseMetadata = {
/**
* Timestamp for the start of the generated response.
*/
timestamp: Date;
/**
* The ID of the response model that was used to generate the response.
*/
modelId: string;
/**
* Response headers.
*/
headers?: Record<string, string>;
};
type JSONValue = JSONValue$1;
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>;
};
/**
* Middleware for language models.
* Accepts both V3 and V4 middleware types for backward compatibility.
*
* Uses LanguageModelV4Middleware as the base but relaxes specificationVersion
* to accept any string (including 'v3') and makes it optional.
*/
type LanguageModelMiddleware = Omit<LanguageModelV4Middleware, 'specificationVersion'> & {
readonly specificationVersion?: 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;
};
/**
* Reranking model that is used by the AI SDK.
*/
type RerankingModel = string | RerankingModelV4 | RerankingModelV3;
/**
* Provider for language, text embedding, and image models.
*/
type Provider = {
/**
* Returns the language model with the given id.
* The model id is then passed to the provider function to get the model.
*
* @param {string} modelId - The id of the model to return.
*
* @returns {LanguageModel} The language model associated with the id
*
* @throws {NoSuchModelError} If no such model exists.
*/
languageModel(modelId: string): LanguageModel;
/**
* Returns the text embedding model with the given id.
* The model id is then passed to the provider function to get the model.
*
* @param {string} modelId - The id of the model to return.
*
* @returns {EmbeddingModel} The embedding model associated with the id
*
* @throws {NoSuchModelError} If no such model exists.
*/
embeddingModel(modelId: string): EmbeddingModel;
/**
* Returns the image model with the given id.
* The model id is then passed to the provider function to get the model.
*
* @param {string} modelId - The id of the model to return.
*
* @returns {ImageModel} The image model associated with the id
*/
imageModel(modelId: string): ImageModel;
/**
* Returns the reranking model with the given id.
* The model id is then passed to the provider function to get the model.
*
* @param {string} modelId - The id of the model to return.
*
* @returns {RerankingModel} The reranking model associated with the id
*
* @throws {NoSuchModelError} If no such model exists.
*/
rerankingModel(modelId: string): RerankingModel;
};
/**
* 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;
type ProviderReference = SharedV4ProviderReference;
/**
* Speech model that is used by the AI SDK.
*/
type SpeechModel = string | SpeechModelV4 | SpeechModelV3 | SpeechModelV2;
type SpeechModelResponseMetadata = {
/**
* Timestamp for the start of the generated response.
*/
timestamp: Date;
/**
* The ID of the response model that was used to generate the response.
*/
modelId: string;
/**
* Response headers.
*/
headers?: Record<string, string>;
/**
* Response body.
*/
body?: unknown;
};
/**
* Transcription model that is used by the AI SDK.
*/
type TranscriptionModel = string | TranscriptionModelV4 | TranscriptionModelV3 | TranscriptionModelV2;
type TranscriptionModelResponseMetadata = {
/**
* Timestamp for the start of the generated response.
*/
timestamp: Date;
/**
* The ID of the response model that was used to generate the response.
*/
modelId: string;
/**
* Response headers.
*/
headers?: Record<string, string>;
};
/**
* 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;
};
/**
* Usage information for an image model call.
*/
type ImageModelUsage = ImageModelV4Usage;
/**
* 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>>;
};
/**
* Extracts the total timeout value in milliseconds from a TimeoutConfiguration.
*
* @param timeout - The timeout configuration.
* @returns The total timeout in milliseconds, or undefined if no timeout is configured.
*/
declare function getTotalTimeoutMs(timeout: TimeoutConfiguration<any> | undefined): number | undefined;
/**
* Extracts the step timeout value in milliseconds from a TimeoutConfiguration.
*
* @param timeout - The timeout configuration.
* @returns The step timeout in milliseconds, or undefined if no step timeout is configured.
*/
declare function getStepTimeoutMs(timeout: TimeoutConfiguration<any> | undefined): number | undefined;
/**
* Extracts the chunk timeout value in milliseconds from a TimeoutConfiguration.
* This timeout is for streaming only - it aborts if no new chunk is received within the specified duration.
*
* @param timeout - The timeout configuration.
* @returns The chunk timeout in milliseconds, or undefined if no chunk timeout is configured.
*/
declare function getChunkTimeoutMs(timeout: TimeoutConfiguration<any> | undefined): number | undefined;
declare function getToolTimeoutMs<TOOLS extends ToolSet>(timeout: TimeoutConfiguration<TOOLS> | undefined, toolName: keyof TOOLS & string): number | undefined;
/**
* Request-facing controls. These settings affect transport, retries,
* cancellation, headers, and timeout – not model generation behavior.
*/
type RequestOptions<TOOLS extends ToolSet = ToolSet> = {
/**
* Maximum number of retries. Set to 0 to disable retries.
*
* @default 2
*/
maxRetries?: number;
/**
* Abort signal.
*/
abortSignal?: AbortSignal;
/**
* Additional HTTP headers to be sent with the request.
* Only applicable for HTTP-based providers.
*/
headers?: Record<string, string | undefined>;
/**
* Timeout configuration for the request.
*/
timeout?: TimeoutConfiguration<TOOLS>;
};
declare const systemModelMessageSchema: z.ZodType<SystemModelMessage>;
declare const userModelMessageSchema: z.ZodType<UserModelMessage>;
declare const assistantModelMessageSchema: z.ZodType<AssistantModelMessage>;
declare const toolModelMessageSchema: z.ZodType<ToolModelMessage>;
declare const modelMessageSchema: z.ZodType<ModelMessage>;
/**
* 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;
});
/**
* Converts data content to a base64-encoded string.
*
* @param content - Data content to convert.
* @returns Base64-encoded string.
*/
declare function convertDataContentToBase64String(content: DataContent): string;
/** @deprecated Use `LanguageModelCallOptions` combined with `RequestOptions` instead. */
type CallSettings = LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>;
/**
* 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[];
};
/**
* 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;
/**
* Create a type from an object with all keys and nested keys set to optional.
* The helper supports normal objects and schemas (which are resolved automatically).
* It always recurses into arrays.
*
* Adopted from [type-fest](https://github.com/sindresorhus/type-fest/tree/main) PartialDeep.
*/
type DeepPartial<T> = T extends FlexibleSchema ? DeepPartialInternal<InferSchema<T>> : DeepPartialInternal<T>;
type DeepPartialInternal<T> = T extends null | undefined | string | number | boolean | symbol | bigint | void | Date | RegExp | ((...arguments_: any[]) => unknown) | (new (...arguments_: any[]) => unknown) ? T : T extends Map<infer KeyType, infer ValueType> ? PartialMap<KeyType, ValueType> : T extends Set<infer ItemType> ? PartialSet<ItemType> : T extends ReadonlyMap<infer KeyType, infer ValueType> ? PartialReadonlyMap<KeyType, ValueType> : T extends ReadonlySet<infer ItemType> ? PartialReadonlySet<ItemType> : T extends object ? T extends ReadonlyArray<infer ItemType> ? ItemType[] extends T ? readonly ItemType[] extends T ? ReadonlyArray<DeepPartialInternal<ItemType | undefined>> : Array<DeepPartialInternal<ItemType | undefined>> : PartialObject<T> : PartialObject<T> : unknown;
type PartialMap<KeyType, ValueType> = {} & Map<DeepPartialInternal<KeyType>, DeepPartialInternal<ValueType>>;
type PartialSet<T> = {} & Set<DeepPartialInternal<T>>;
type PartialReadonlyMap<KeyType, ValueType> = {} & ReadonlyMap<DeepPartialInternal<KeyType>, DeepPartialInternal<ValueType>>;
type PartialReadonlySet<T> = {} & ReadonlySet<DeepPartialInternal<T>>;
type PartialObject<ObjectType extends object> = {
[KeyType in keyof ObjectType]?: DeepPartialInternal<ObjectType[KeyType]>;
};
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>;
};
/**
* 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>>;
/**
* 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;
}
declare class DefaultGeneratedFile implements GeneratedFile {
private base64Data;
private uint8ArrayData;
readonly mediaType: string;
constructor({ data, mediaType, }: {
data: string | Uint8Array;
mediaType: string;
});
get base64(): string;
get uint8Array(): Uint8Array<ArrayBufferLike>;
}
/**
* 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 stre