npm / @ai-sdk/provider
@ai-sdk/provider
What changed in @ai-sdk/provider 2 to 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-12.
19 breaking2 security35 new APIs and options9 behavior and defaults12 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@ai-sdk/provider 446 changes
Breaking changes 4
Adds a typed streaming heartbeat part. Consumers with exhaustive stream-part switches must handle the new union variant, even when the opt-in is disabled.
mediaType can be undefined when a provider fetches an audio URL natively, so telemetry integrations should check for missing values before using it as a string.
Arrays passed directly as state are interpreted as decision state parts; wrap JSON arrays in an object or a json part.
Decision refusals are reported as refusal answers, changing how providers represent refusals.
Security 2
Optional request metadata and model-call end events report the actual OpenAI Chat HTTP endpoint; generation results, callbacks, and OpenTelemetry spans expose only sanitized endpoint information.
@ai-sdk/provider-utils has an Uncontrolled Resource Consumption issue
New APIs and options 25
Provider metadata now exposes structured Score legends.
Accepts an optional intent so server-side callers can align session serialization with endpoint selection.
An optional createTransport interface and provider connection capability support provider-owned realtime transports.
The optional method returns upstream WebSocket connection details for a server-initiated connection and can select an endpoint using intent.
Enables Anthropic streaming heartbeat parts; pings are disabled by default.
Capability catalogs can include video, reranking, and decision sections, including provider options for those operations.
Providers can transcribe audio from a URL natively; Groq sends HTTP(S) URLs without downloading and re-uploading them. A custom download function retains local download behavior.
Adds an exported server connection type for the experimental realtime model specification.
Adds an exported session intent type for the experimental realtime model specification.
Adds a normalized usage type for realtime events, keeping gross totals and modality buckets separate and reporting duration in seconds.
Accepts an optional intent so server-side callers can align event serialization with endpoint selection.
Accepts shared timestamp granularity settings; explicit provider timing settings take precedence. OpenAI sends timestamp_granularities only with verbose_json.
Optional word timings are exposed separately from transcription segments.
Video generation reports videos delivered directly to caller-managed storage without downloading or synthesizing video bytes.
Introduces named capability sections and request configuration for model entries; provider catalogs also declare accepted options and which models support them.
Adds an experimental SpeechModelV4 extension whose doStream() accepts streamed text parts with optional per-part voice and providerOptions, and returns streamed audio parts.
Adds interrupted to the public finish-reason types. Exhaustive switches, mappings, and custom validation must handle it; interrupted responses preserve partial output without an error solely for the interruption.
Experimental decision calls accept maxOutputTokens and forward it to language-model-backed decisions.
Experimental decision calls accept reasoning and forward it to language-model-backed decisions; language-model adapters keep reasoning disabled when omitted.
Adds support for the Perplexity decisions API.
Adds the box decision question type with image bounds for TypeSafe AI.
Adds an optional shared citation representation to generated text and text-end stream events, preserving citations in core result content and UI message text parts, including validation and persistence.
Embedding functions accept a top-level dimensions setting.
Decision state can contain ordered text, file, and JSON parts.
OpenAI Decisions and language model adapters support image input.
Behavior and default changes 4
byteLength can be undefined when a provider fetches an audio URL natively, so telemetry integrations should check for missing values before using it as a number.
Native decision providers warn when maxOutputTokens or reasoning is unsupported.
Public state forms are normalized into an array of parts before provider calls, with text and JSON objects passed as text and json parts.
Decision file bytes are serialized as base64 in state attributes; model-call spans record normalized state parts while outer spans retain public state inputs.
Fixes and other changes 11
Boolean criteria may be null in experimental decision question types.
Box instructions may be omitted or null in experimental decision question types.
Empty criteria and null or undefined Score levels are rejected before a request is sent.
TypeSafe decision requests serialize primitive JSON state values as text.
Groq strips media fragments from URLs and falls back to secure local download and file upload if a redirect is rejected.
Access video only when videos is nonempty when generation reports an uploaded outcome.
Non-streaming structured output now handles multiple assistant messages containing JSON by allowing providers to supply separate parsing text, preserving generated content, annotations, conversation history, and token usage.
Streamed input is marked as text so UI clients can display it progressively without JSON parsing; the encoding is preserved when partial UI messages are saved and resumed.
Raw custom-tool input deltas are restored for consumers that forward them to Responses API clients.
Gateway keeps its existing string and JSON request format and rejects files.
Shared state is labeled in language-model decision prompts.
@ai-sdk/provider 231 changes
Breaking changes 15
doGenerate returns a content array.
Image parts are removed from the provider specification.
logprobs are removed from the provider specification.
maxTokens is renamed to maxOutputTokens.
The mimeType field is renamed to mediaType.
Object generation mode is removed.
The prompt type is removed from the LanguageModelV2 specification.
providerMetadata inputs are renamed to providerOptions.
rawRequest is merged into request, so integrations should use request instead.
The embedding model v2 response gains a body field.
Speech models are upgraded to the v2 specification.
getSupportedUrls is renamed to supportedUrls for LanguageModelV2.
Tool values use input and output instead of args and result.
Transcription models are upgraded to the v2 specification.
V1 providers are removed.
New APIs and options 10
A v2 embedding model interface is added.
Speech generation is available through experimental_generateSpeech.
Transcription is available through experimental_transcribe.
ImageModelV2 gains providerMetadata.
Middleware can change the provider, model, and supported URLs.
Provider-defined tools now have a name for future validation.
Raw chunk support is added.
Tool results support arbitrary media types.
The provider registry adds support for transcription and speech models.
Usage information is refactored and supports reasoning tokens, cached input tokens, and total tokens.
Behavior and default changes 5
File content can be provided as binary data or base64, allowing Uint8Array input without manual conversion.
maxImagesPerCall can be a function returning a number or undefined, optionally as a promise.
Provider-defined tools are collapsed into a single definition.
Warnings are moved into the stream-start part.
Content block streaming now forwards block IDs and streaming start and end events.
Fixes and other changes 1
Reasoning parts are refactored and reasoning support is restructured.