ai sdk core

383 notes in this subject, read out of this brain and free to use. This is page 1 of 7.

streamText function for streaming text generation

The streamText function from the 'ai' package enables streaming text generation. It takes a model and prompt as parameters and returns an object with a textStream property. The textStream can be iterated using a for-await loop to consume generated text chunks as they become available. Example usage: const { textStream } = streamText({ model, prompt }); for await (const textPart of textStream) { console.log(textPart); }

Dedicated provider package usage

To use a dedicated provider like Anthropic, install the provider package (@ai-sdk/anthropic), import the provider function (anthropic), and use it with the model string: anthropic('claude-sonnet-4-5').

Custom provider creation

The AI SDK supports building custom providers to integrate any service. Custom providers must follow the Language Model Specification available at https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v3 to ensure compatibility across providers.

Global provider configuration

The default global provider can be changed so that string model references use a preferred provider throughout an application. See the provider management documentation for details.

AI SDK provider types supported

The AI SDK supports three types of model providers: first-party packages, OpenAI-compatible packages, and community packages.

generateText basic usage

generateText accepts a model and prompt parameter. The function returns an object with a text property containing the generated response.

AI Gateway environment variable configuration

The AI Gateway API key is configured using the environment variable AI_GATEWAY_API_KEY.

gateway import options

The gateway function can be imported in two ways: import { gateway } from 'ai' (included by default in the main package), or import { gateway } from '@ai-sdk/gateway' (from a dedicated package).

AI SDK Core environment compatibility

AI SDK Core works in any JavaScript environment including Node.js, Deno, and browsers.

AI SDK Core primary functions

AI SDK Core provides unified API functions for calling any LLM, including generateText and streamText.

Multiple provider options for model configuration

Models can be configured in three equivalent ways: by using a simple string with the default global provider, by importing and using gateway() explicitly from the 'ai' package, or by installing a provider package like '@ai-sdk/gateway' and importing it. Other providers like '@ai-sdk/openai' can be installed and used to reference models without relying on the global provider.

Route handler for chat API

A Next.js route handler at app/api/chat/route.ts exports a POST function that receives a request with a messages body. The messages are extracted from the request JSON as UIMessage[]. The handler calls streamText with the messages converted to ModelMessage[], then returns a streamed response using createUIMessageStreamResponse and toUIMessageStream.

Route Handler location for Next.js Pages Router with streaming

When using Next.js Pages Router, you can create a Route Handler at app/api/chat/route.ts (using the App Router API alongside Pages Router) to enable Web APIs interface and better support for streaming. This creates a POST endpoint at /api/chat.

Vercel AI Gateway as default global provider in Expo quickstart

The quickstart uses Vercel AI Gateway as the default global provider, allowing models to be referenced by simple strings like 'anthropic/claude-sonnet-4.5'. Install 'ai' package and set AI_GATEWAY_API_KEY environment variable in .env.local file.

Vercel AI Gateway provider - model string syntax

When using Vercel AI Gateway as the global provider (the default), models can be accessed using a simple string format like 'anthropic/claude-sonnet-4.5' without explicit imports. This is equivalent to calling gateway('anthropic/claude-sonnet-4.5').

Nuxt API route handler setup

In Nuxt, API routes are created in the server/api/ directory. The file server/api/chat.ts automatically creates an endpoint at /api/chat. Use defineLazyEventHandler to wrap the handler creation, allowing access to runtime config via useRuntimeConfig(). The actual handler is defined with defineEventHandler.

Nuxt runtime config for API keys

In Nuxt, environment variables with the NUXT_ prefix are automatically loaded into runtime config. The pattern is: set NUXT_AI_GATEWAY_API_KEY in .env file, then access it via useRuntimeConfig().aiGatewayApiKey (converts kebab-case to camelCase). This provides better integration with Nuxt's configuration system than direct environment variable access.

Installing and using alternative providers

To use providers other than the Vercel AI Gateway, install the provider-specific package (e.g., '@ai-sdk/openai' for OpenAI) and import the provider function. Then pass model instances created from these providers to streamText, for example: openai('gpt-5.1').

gateway provider from AI SDK

The AI SDK includes a gateway provider that can be imported from the 'ai' package. Models can be specified as a string when using the default global provider configuration, or explicitly imported and called as gateway('provider/model-name'). The Vercel AI Gateway is the default global provider.

AI_GATEWAY_API_KEY environment variable

The Vercel AI Gateway provider defaults to using the AI_GATEWAY_API_KEY environment variable for authentication. This variable should be set in a .env file at the project root.

Launch DevTools viewer

Start the DevTools viewer in a separate terminal with: `npx @ai-sdk/devtools@latest`. Then open http://localhost:4983 to inspect AI SDK interactions in real time.

Install and register DevTools for AI SDK

Install the DevTools package with `npm install @ai-sdk/devtools`. Then register `DevToolsTelemetry` globally to capture all AI SDK calls. Use: `import { registerTelemetry } from 'ai'; import { DevToolsTelemetry } from '@ai-sdk/devtools'; registerTelemetry(DevToolsTelemetry());`. Once registered, telemetry is enabled automatically for all AI SDK calls. DevTools is experimental and intended for local development only; do not use in production.

DevTools captures for all AI SDK calls

DevTools captures the following for every call: input parameters and prompts (the complete input sent to the LLM), output content and tool calls (generated text and tool invocations), token usage and timing (resource consumption and latency per step), and raw provider data (complete request and response payloads). For multi-step agent interactions, DevTools groups everything into runs (a complete interaction) and steps (each individual LLM call within it).

Access AI SDK docs and source in node_modules

After installing the `ai` package, the full AI SDK documentation and source code are available locally inside `node_modules`. Coding agents can read these directly without internet access. The paths are: `node_modules/ai/src/` for full source code organized by module, and `node_modules/ai/docs/` for official documentation with examples. This ensures the agent always uses the version of the SDK that is actually installed in the project.

Install AI SDK skill for coding agents

Install the official AI SDK skill using `npx skills add vercel/ai`. This installs the skill into the agent's specific skills directory (e.g., `.claude/skills`, `.codex/skills`). If you select more than one agent, the CLI creates symlinks so each agent can discover the skill. Use `-a` to specify agents directly, for example `-a amp` installs into the universal `.agents/skills` directory. Use `-y` for non-interactive installation. Once installed, any agent that supports the Agent Skills format will automatically discover and load the skill when working on AI SDK tasks. Skills use progressive disclosure: the agent loads only the skill's name and description at startup, and the full instructions are only pulled into context when the task calls for it.

AI SDK Core simplifies LLM integration

AI SDK Core offers a standardized way of integrating Large Language Models into applications, so developers can focus on building AI applications rather than handling technical details.

AI Gateway normalizes realtime across providers

AI Gateway accepts realtime connections from supported upstream providers and normalizes realtime events server-side. The browser receives only a short-lived client secret. The same client code can work across different upstream providers by routing through AI Gateway.

Realtime feature status

Realtime is an experimental feature in the AI SDK.

Setup endpoint security requirements

In production, authenticate and rate-limit your realtime setup endpoint. The endpoint creates realtime sessions using your server-side API key, so it must be protected.

globalThis.AI_SDK_DEFAULT_PROVIDER sets the global default provider

Set globalThis.AI_SDK_DEFAULT_PROVIDER = providerInstance during application startup to specify a default provider. Once set, you can use model IDs without a provider prefix in streamText, generateText, and other functions. The default global provider is the Vercel AI Gateway if not customized.

registry.skills accesses a provider's skills interface

Call registry.skills('providerId') to get a provider's skills interface from the registry. This allows you to use uploadSkill with a provider's skills API. The provider must have a skills interface defined in its configuration.

registry.files accesses a provider's files interface

Call registry.files('providerId') to get a provider's files interface from the registry. This allows you to use uploadFile with a provider's files API before referencing uploaded files in model requests. The provider must have a files interface defined in its configuration.

customProvider creates custom providers with pre-configured models

The customProvider function lets you create custom providers by specifying languageModels, embeddingModels, and optionally files or skills interfaces. You can pre-configure model settings, provide model name aliases, and limit available models. The function accepts a configuration object with languageModels (required), embeddingModels (optional), files (optional), skills (optional), and fallbackProvider (optional) properties.

customProvider with model aliases reduces configuration duplication

You can create model name aliases in customProvider to simplify future model updates. Define aliases like 'opus', 'sonnet', 'haiku' pointing to full model IDs, then update the alias target in one place when upgrading model versions without changing all references throughout the codebase.

customProvider languageModels property structure and syntax

The languageModels property in customProvider is an object where keys are custom model names (strings) and values are wrapped language models. Models can be created using gateway('provider/model-id') for simple passthrough, or wrapLanguageModel with middleware for custom configuration. Example: { 'gpt-5.1': wrapLanguageModel({ model: gateway('openai/gpt-5.1'), middleware: defaultSettingsMiddleware({ settings: { providerOptions: { openai: { reasoningEffort: 'high' } } } }) }) }

gateway function provides passthrough access to providers

The gateway function is available from 'ai' and provides passthrough access to providers. It can be used directly in registries or customProviders as languageModels values. Call gateway('provider/model-id') for language models or gateway.embeddingModel('provider/model-id') for embedding models.

registry.videoModel accesses video models from the registry

Call registry.videoModel('providerId:modelId') to get a video model. The provider ID is the key in the registry configuration, and modelId is the model name from that provider. Use this result as the model parameter in experimental_generateVideo() or other video generation functions.

registry.imageModel accesses image models from the registry

Call registry.imageModel('providerId:modelId') to get an image model. The provider ID is the key in the registry configuration, and modelId is the model name from that provider. Use this result as the model parameter in generateImage() or other image generation functions.

registry.embeddingModel accesses embedding models from the registry

Call registry.embeddingModel('providerId:modelId') to get an embedding model. The provider ID is the key in the registry configuration, and modelId is the model name from that provider. Use this result as the model parameter in embed() or other embedding functions.

registry.languageModel accesses language models from the registry

Call registry.languageModel('providerId:modelId') to get a language model. The provider ID is the key in the registry configuration, and modelId is the model name from that provider. The separator is ':' by default, or a custom separator if specified during registry creation. Use this result as the model parameter in generateText, streamText, or other functions.

createProviderRegistry creates a registry with multiple providers

The createProviderRegistry function accepts a configuration object where keys are provider names (strings) and values are providers or gateways. It returns a registry object with methods to access models by provider and model ID in the format 'providerId:modelId'. An optional second parameter can specify { separator: customSeparator } to change the default ':' separator.

defaultSettingsMiddleware sets default model configuration

The defaultSettingsMiddleware function takes a settings object containing maxOutputTokens and providerOptions. The providerOptions property is a nested object where keys are provider names (e.g., 'openai', 'anthropic') and values are provider-specific option objects. Example: defaultSettingsMiddleware({ settings: { maxOutputTokens: 100000, providerOptions: { openai: { reasoningEffort: 'high' } } } })

wrapLanguageModel wraps a model with middleware for custom configuration

The wrapLanguageModel function takes an object with model and middleware properties. The model is a language model instance (e.g., from gateway()). The middleware is applied to customize behavior, such as using defaultSettingsMiddleware to set default provider-specific options and other settings.

customProvider fallbackProvider property

The customProvider function accepts an optional fallbackProvider property. If set, the custom provider will use the fallback provider for any models not explicitly defined in languageModels or embeddingModels. If fallbackProvider is configured but files or skills are not explicitly set, the custom provider inherits those interfaces from the fallback.

customProvider files and skills interfaces

The customProvider function accepts optional files and skills properties. The files property is a files interface from a provider (e.g., openai.files()). The skills property is a skills interface from a provider (e.g., anthropic.skills()). These allow uploadFile and uploadSkill functions to work through the custom provider abstraction.

custom provider example with multiple providers and model aliases

Example showing how to combine customProvider and createProviderRegistry: configure gateway as passthrough, add multiple providers with namespaces, set up model name aliases (anthropic > fast, anthropic > reasoning), pre-configure settings with middleware, and limit providers to specific models. Uses separator ' > ' for readability. This pattern allows centralized provider management with per-model customization.

customProvider embeddingModels property structure and syntax

The embeddingModels property in customProvider is an object where keys are custom model names (strings) and values are embedding models. Models are created using gateway.embeddingModel('provider/model-id'). Example: { embedding: gateway.embeddingModel('openai/text-embedding-3-small') }

createProviderRegistry separator option customizes ID format

The createProviderRegistry function accepts an optional second parameter { separator: ' > ' } (or any string) to customize the separator between provider ID and model ID. Default separator is ':'. When set, access models using the custom separator, e.g., 'providerId > modelId' instead of 'providerId:modelId'.

DevTools monorepo usage

When using DevTools in a monorepo setup, start DevTools from the same workspace where your AI SDK code runs. Use the explicit @latest tag to ensure npx installs an executable copy instead of selecting a transitive dependency.

DevTools media preview capabilities

DevTools recognizes file content parts and previews inline image, audio, and video data. The viewer displays at most 8 previews per value, traverses at most 12 nested levels, and embeds inline previews up to 5 MiB. Longer JSON strings are truncated to avoid duplicating large base64 payloads.

DevTools runs and steps organization

DevTools organizes captured data into runs (a complete multi-step AI interaction grouped by initial prompt) and steps (a single LLM call within a run). Multi-step interactions like tool calling or agent loops are grouped as a single run with multiple steps.

Body retention for streamText and ToolLoopAgent.stream

For streamText and ToolLoopAgent.stream(), only the request body can be retained using include: { requestBody: true }. Response body retention is not available for streaming calls.

Enable raw request/response body retention in generateText

For generateText, enable body retention by passing include: { requestBody: true, responseBody: true } to capture raw request and response bodies.

DevTools remote media loading

Remote http and https media is not loaded automatically. Users can select Load preview in the viewer to fetch it with anonymous CORS and no referrer. URLs containing embedded usernames or passwords are rejected.

DevTools captured data categories

DevTools captures input parameters and prompts, output content and tool calls, media previews for images/audio/video, token usage and timing, and raw provider data when body retention is enabled.

DevTools API functions tracked

DevTools captures data from generateText, streamText, generateObject, streamObject calls, and ToolLoopAgent interactions.

DevTools viewer launch command

Start the DevTools viewer with the command: npx @ai-sdk/devtools@latest. This launches a web UI accessible at http://localhost:4983

DevTools per-call telemetry integration

Pass DevToolsTelemetry to individual calls using the telemetry option: telemetry: { integrations: [DevToolsTelemetry()] }

DevTools registration with registerTelemetry

Register DevToolsTelemetry globally using registerTelemetry to capture all AI SDK calls: import { registerTelemetry } from 'ai'; import { DevToolsTelemetry } from '@ai-sdk/devtools'; registerTelemetry(DevToolsTelemetry());

DevTools requirements

DevTools requires AI SDK v7 (ai@latest) and a Node.js compatible runtime.

Give your agent this brain