configuration & providers

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

ModelMessage Zod schema access

The Zod schema for ModelMessage and its subtypes can be accessed using the following exports: modelMessageSchema (for ModelMessage), systemModelMessageSchema (for SystemModelMessage), userModelMessageSchema (for UserModelMessage), assistantModelMessageSchema (for AssistantModelMessage), and toolModelMessageSchema (for ToolModelMessage).

Provider import pattern

Provider implementations are imported from @ai-sdk/<provider> packages. For example, @ai-sdk/openai for OpenAI, @ai-sdk/anthropic for Anthropic, @ai-sdk/google for Google, @ai-sdk/azure for Azure, @ai-sdk/amazon-bedrock for Amazon Bedrock.

AI SDK package structure

The AI SDK is a monorepo using pnpm workspaces and Turborepo. Core packages include ai (main SDK), @ai-sdk/provider (interface specifications), @ai-sdk/provider-utils (shared utilities), individual @ai-sdk/<provider> packages for each AI provider, and @ai-sdk/<framework> packages for UI framework integrations (react, vue, svelte, angular, rsc).

AI SDK provider architecture

The SDK uses a layered provider architecture following the adapter pattern with four layers: Specifications (@ai-sdk/provider) define interfaces like LanguageModelV4; Utilities (@ai-sdk/provider-utils) provide shared implementation code; Providers (@ai-sdk/<provider>) are concrete implementations for each AI service; Core (ai package) provides high-level functions like generateText and streamText.

Error handling pattern in AI SDK

Errors extend AISDKError from @ai-sdk/provider and use a marker pattern for instanceof checks. The error class defines a name string and a marker symbol created with Symbol.for('vercel.ai.error.<name>'). The class implements a static isInstance method that uses AISDKError.hasMarker to check if an error is an instance of the specific error type.

JSON parsing in AI SDK

Never use JSON.parse directly in production code to prevent security risks. Instead use parseJSON or safeParseJSON from @ai-sdk/provider-utils.

Provider options and response schemas in AI SDK

Provider options schemas (user-facing) should use .optional() unless null is meaningful and be as restrictive as possible. Response schemas (from API responses) should use .nullish() instead of .optional(), be kept minimal with only needed properties, and allow flexibility for provider API changes.

URL validation in provider implementations

Every getFromApi call in the repository must set validateUrl explicitly. Use validateUrl: true when the URL comes from a provider response body (for image/audio/video downloads or polling URLs). Use validateUrl: false only for URLs built from a configured baseURL. Pass credentialedOrigin when a response URL may carry the API key on its first hop to withhold credentials off-origin.

AI SDK development requirements

Development requires Node.js v22, v24, or v26 (v22 recommended) and pnpm v10 or higher.

Core AI SDK build and test commands

Root-level commands: pnpm install (install dependencies), pnpm build (build all packages), pnpm test (run all tests excluding examples), pnpm check (run linting with oxlint and formatting checks with oxfmt), pnpm fix (fix linting and formatting issues), pnpm type-check:full (TypeScript type checking including examples), pnpm changeset (add changeset for PR), pnpm update-references (update tsconfig.json references after adding package dependencies).

Package-level AI SDK commands

Package-level commands run from within a package directory: pnpm build (build the package), pnpm build:watch (build with watch mode), pnpm test (run all tests for node and edge), pnpm test:node (run Node.js tests only), pnpm test:edge (run Edge runtime tests only), pnpm test:watch (run tests in watch mode).

AI SDK testing framework and conventions

The SDK uses Vitest for testing. Test files are named *.test.ts alongside source files. Type-level tests use *.test-d.ts extension. Test fixtures are stored in __fixtures__ subfolders and snapshots in __snapshots__ subfolders.

AI SDK file naming conventions

Source files use kebab-case.ts naming. Test files are kebab-case.test.ts. Type test files are kebab-case.test-d.ts. React/UI components use kebab-case.tsx.

AI SDK code formatting and linting

The SDK uses oxfmt for formatting (configured via .oxfmtrc.jsonc) and oxlint for linting (configured via .oxlintrc.json). Use pnpm fix or ultracite fix for formatting and pnpm check or ultracite check for linting. A pre-commit hook runs pnpm install if package.json changes are staged.

Changeset requirements in AI SDK

Every PR modifying production code requires a changeset. Use patch for non-breaking changes by default. Run pnpm changeset in workspace root to add a changeset. Do not select example packages as they are not published.

Bug fix task completion in AI SDK

A complete bug fix includes: a reproduction example created or updated in examples/ that demonstrates the bug before fixing; unit tests that would fail without the fix (regression tests); the implementation fix; manual verification by running the reproduction example; and a changeset describing what was broken and how it is fixed.

New feature task completion in AI SDK

A complete feature includes: implementation of the feature; usage examples in examples/ demonstrating the feature; comprehensive unit test coverage; documentation updates in content/ for public APIs; and a changeset describing the feature for release notes.

Refactoring task completion in AI SDK

Refactoring and internal changes require unit tests for any changed behavior. Documentation is not needed for internal-only changes. Add a changeset only if it affects published packages.

Give your agent this brain