ai-sdk/overview

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

AI SDK Core primary functions

AI SDK Core has three main function categories: generateText for text generation and tool calls, streamText for streaming text and tool calls, and functions for structured data generation and tool usage. These functions take a standardized approach to setting up prompts and settings.

AI SDK Core provides standardized LLM integration

AI SDK Core simplifies working with LLMs by offering a standardized way of integrating them into applications, allowing developers to focus on building AI applications rather than managing technical details of different model providers.

UI messages layer location

UI messages are defined in packages/ai/src/ui/ui-messages.ts and contain data parts shaped for UI rendering.

Model messages layer location

Model messages are defined in packages/provider-utils/src/types/model-message.ts and provide an abstracted, user-friendly version used in generate and stream calls.

Language model messages layer location

Language model messages are defined in packages/provider/src/language-model/v4/language-model-v4-prompt.ts and represent a standardized spec intended to be stable.

Provider-specific messages conversion

Provider-specific messages represent the final conversion layer for specific API requirements. For example, in OpenAI provider implementation, this conversion occurs in the getArgs() and doGenerate() methods of OpenAIResponsesLanguageModel.

Four-level message architecture layers

The Vercel AI SDK implements a four-level message architecture: UI messages (contain data parts shaped for UI rendering), Model messages (abstracted user-friendly version for DX, used in generate/stream calls), Language model messages (standardized spec intended to be stable), and Provider-specific messages (final conversion for specific API requirements).

convertToModelMessages transforms UI messages for language models

The convertToModelMessages function from the ai SDK transforms UI message format into the format expected by language models like openai/gpt-4.1.

Package-level development commands

Run from within a package directory (e.g., packages/ai): 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).

Core AI SDK functions

The SDK provides these core functions: generateText (generate text completion), streamText (stream text completion), generateObject (generate structured output), streamObject (stream structured output), embed and embedMany (generate embeddings), generateImage (generate images), tool (define a tool), jsonSchema and zodSchema (define schemas). All are in the 'ai' package except provider implementations.

Import patterns for Vercel AI SDK

Core functions (generateText, streamText) and tool/schema utilities (tool, jsonSchema) are imported from 'ai'. Provider implementations are imported from '@ai-sdk/<provider>' (e.g., '@ai-sdk/openai'). Error classes are imported from 'ai' (re-exported from '@ai-sdk/provider'). Provider type interfaces (LanguageModelV4) are imported from '@ai-sdk/provider'. Provider implementation utilities are imported from '@ai-sdk/provider-utils'.

Code formatting and linting tools

Formatter: oxfmt (run via 'pnpm fix' or 'ultracite fix'). Linter: oxlint (run via 'pnpm check' or 'ultracite check'). Configuration files: .oxfmtrc.jsonc (formatter) and .oxlintrc.json (linter). Pre-commit hook runs 'pnpm install' if package.json changes are staged.

Testing framework and conventions

Testing framework: Vitest. Test files: *.test.ts alongside source files. Type tests: *.test-d.ts for type-level tests. Fixtures stored in __fixtures__ subfolders. Snapshots stored in __snapshots__ subfolders.

Zod version compatibility in AI SDK

The SDK supports both Zod 3 and Zod 4. For Zod 3 (compatibility code only): import * as z3 from 'zod/v3'. For Zod 4: import * as z4 from 'zod/v4'. Use z4.core.$ZodType for type references in Zod 4.

JSON parsing security requirement

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

Type checking requirement

Always run 'pnpm type-check:full' from the workspace root after making code changes to ensure no type errors are introduced across the codebase, including examples.

File naming conventions

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

Error class implementation pattern

Errors extend AISDKError from @ai-sdk/provider and use a marker pattern for instanceof checks. Define a name, marker (vercel.ai.error.${name}), and symbol (Symbol.for(marker)). Implement a private property using the symbol set to true for isInstance checks. Include static isInstance method that uses AISDKError.hasMarker(error, marker).

Provider pattern architecture

The SDK uses a layered provider architecture following the adapter pattern with four layers: Specifications (@ai-sdk/provider) defining interfaces like LanguageModelV4, Utilities (@ai-sdk/provider-utils) providing shared code for implementing providers, Providers (@ai-sdk/<provider>) with concrete implementations for each AI service, and Core (ai) with high-level functions like generateText and streamText.

Provider options schema design guidelines

For user-facing provider options schemas, use .optional() unless null is meaningful. Be as restrictive as possible for future flexibility. For API response schemas, use .nullish() instead of .optional(). Keep response schemas minimal, only including properties needed. Allow flexibility for provider API changes.

URL validation requirement in provider code

Every getFromApi call in the repository must set validateUrl explicitly. Use true when the URL comes from a provider response body (image/audio/video download or polling URL). Use false only for URLs built from a configured baseURL. Pass credentialedOrigin when a response URL may legitimately carry the API key on its first hop. The ai-sdk/require-validate-url oxlint rule enforces this.

Adding new packages to monorepo

To add a new package: create folder under packages/<name>, add to root tsconfig.json references, run 'pnpm update-references' if adding dependencies between packages.

Changesets requirement

Every PR modifying production code requires a changeset. Default to 'patch' for non-breaking changes. Run 'pnpm changeset' from workspace root. Do not select example packages as they are not published.

Bug fix task completion artifacts

A complete bug fix should include: a reproduction example in examples/ demonstrating the bug before fixing, unit tests that fail without the fix (regression tests), the implementation fix, manual verification by running the reproduction example to confirm the fix, and a changeset describing what was broken and how it's fixed.

New feature task completion artifacts

A complete feature should include: implementation of the feature, usage examples in examples/ demonstrating the feature, comprehensive unit tests for new functionality, updated documentation in content/ for public APIs, and a changeset describing the feature for release notes.

Public API documentation requirement

Do not change public APIs without updating documentation.

Code import requirement

Do not use require() for imports. Use ES6 import statements instead.

Documentation and codemod modification restriction

Do not modify content/docs/08-migration-guides or packages/codemod as part of broader codebase changes.

Dependency management requirement

Do not add new dependencies without running pnpm update-references.

Vercel AI SDK project overview and repository structure

The AI SDK by Vercel is a TypeScript/JavaScript SDK for building AI-powered applications with Large Language Models. It provides a unified interface for multiple AI providers and framework integrations. The repository is a monorepo using pnpm workspaces and Turborepo. Key directories include: packages/ai (main SDK package), packages/provider (provider interface specifications), packages/provider-utils (shared utilities), packages/<provider> (AI provider implementations like openai, anthropic, google, azure, amazon-bedrock), packages/<framework> (UI framework integrations like react, vue, svelte, angular, rsc), packages/codemod (automated migrations), examples/ (example applications), content/ (documentation source files in MDX), contributing/ (contributor guides), and tools/ (internal tooling).

Core package dependency structure

The main 'ai' package depends on '@ai-sdk/provider-utils' which depends on '@ai-sdk/provider'. Each '@ai-sdk/<provider>' package also depends on '@ai-sdk/provider-utils' which depends on '@ai-sdk/provider'. This creates a layered architecture where specifications are in @ai-sdk/provider, utilities in @ai-sdk/provider-utils, concrete implementations in @ai-sdk/<provider>, and high-level functions in the main ai package.

Development environment requirements

Node.js v22, v24, or v26 is required (v22 recommended for development). pnpm v10 or higher is required. Installation command: npm install -g pnpm@10

Initial setup commands

Run 'pnpm install' to install all dependencies, then 'pnpm build' to build all packages.

Root-level development commands

Available 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 with oxfmt checks), pnpm fix (fix linting and formatting issues), pnpm type-check:full (TypeScript type checking including examples), pnpm changeset (add a changeset for PR), pnpm update-references (update tsconfig.json references after adding package dependencies).

Give your agent this brain