Install the AI SDK

Purpose and Scope

Use this page when you are adding the AI SDK to a new application, upgrading a local development environment, or preparing a repository so coding agents can follow the project’s AI SDK conventions. The main install target is the ai package, which is the provider-agnostic TypeScript toolkit for building AI-powered applications and agents across React, Next.js, Vue, Svelte, Node.js, and other runtimes. The installation path is intentionally small: install the core package first, choose whether AI Gateway is enough for your provider access, then add framework or direct-provider packages only when your application needs them.

Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

The repository presents the SDK as a way to standardize model integration instead of binding application code to one model vendor’s request and response format. That framing matters during installation because it explains why the first dependency is ai, not a provider-specific package. With the main package installed, you can call core generation APIs and pass AI Gateway model strings. Direct provider packages remain available when you need provider instances, custom settings, provider-specific tools, or provider-specific authentication behavior, but they are not the first step for every project.

Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

Relevant Source Files

• packages/ai/README.md — Documents the public package purpose, Node.js requirement, main install command, coding-agent skill command, AI Gateway model-string usage, optional direct provider packages, examples for text generation, structured output, agents, and UI package installation.
• content/docs/00-introduction/index.mdx — Defines the documentation-site introduction, primary SDK surfaces, provider-standardization rationale, harness abstraction, templates, community links, and the llms.txt workflow for coding assistants.
• package.json — Defines repository-level package manager and engine constraints, including the monorepo’s pnpm version, Node.js engine range, and scripts used by contributors to build, test, type-check, and validate docs.

Requirements and Package Manager Choice

The package README states that local development requires Node.js 22 or newer plus npm or another package manager. The repository root is stricter and more explicit for contributors: its engine range allows Node.js 22, 24, or 26, and its package manager field pins pnpm 10.33.4 for this monorepo. For application consumers, the important rule is to use a modern Node runtime that satisfies the SDK requirement. For repository contributors, match the pinned pnpm version so workspace installs, scripts, and dependency resolution behave like the maintainers expect.

Sources: packages/ai/README.md, package.json

Install the main package with npm when following the README literally:

npm install ai

If your project uses another package manager, use the equivalent add command for the same package. The docs and package ecosystem consistently present npm, pnpm, yarn, and bun as supported package-manager choices for SDK packages, while the repository itself uses pnpm for workspace development. Keep the dependency name unchanged: the public core package is ai. Do not replace it with a provider package unless you are intentionally installing an add-on next to the core package.

Core Primitives Installed by the Main Package

Installing ai gives your application the central SDK surface used by the documentation examples. The README shows generateText for text generation, Output.object with a Zod schema for structured data, and ToolLoopAgent for agent-style tool loops. The introduction page groups the product into AI SDK Core for text, objects, tool calls, and agents; AI SDK UI for framework-agnostic interactive interfaces; and AI SDK Harnesses for running established harnesses through HarnessAgent. These primitives share stream and response concepts, so starting with the main package keeps later choices compatible.

Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

A minimal server-side generation call can use AI Gateway by passing a model string. That is the default path described in the README because AI Gateway provides access to major providers without adding provider SDK packages first. The example model strings use provider prefixes such as OpenAI, Anthropic, and Google. In practical setup terms, this means you can confirm the main dependency and generation flow before deciding whether your application needs a direct provider instance or a framework-specific UI package.

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'openai/gpt-5.4',
  prompt: 'What is an agent?',
});

Optional Provider Packages

Direct provider packages are the next installation layer. The README shows @ai-sdk/openai, @ai-sdk/anthropic, and @ai-sdk/google as examples to install when you want to connect to providers directly instead of only passing AI Gateway model strings. Provider packages expose provider instances, such as anthropic, that can be called with provider-native model identifiers and then passed into the same core APIs. This preserves the SDK’s unified call shape while giving your project direct access to package-specific configuration and provider-specific capabilities.

Sources: packages/ai/README.md

npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';
 
const result = await generateText({
  model: anthropic('claude-opus-4-6'),
  prompt: 'Hello!',
});

Choose AI Gateway model strings when you want the least package setup and a provider-agnostic entry point. Choose direct provider packages when your application code needs a named provider instance, provider settings, provider-defined tools, or behavior documented on that provider package. This distinction is especially useful for teams that prototype with a Gateway model string and later move one model family to a direct provider integration without changing the higher-level generation API. The installation decision should follow the capability you need, not the first provider name you recognize.

UI and Agent Add-ons

For user interfaces, the README points to AI SDK UI and shows @ai-sdk/react as a framework package to install when building chatbots or generative interfaces. The UI layer is described as framework agnostic in purpose, with hooks for chat, completion, and object-generation experiences across frameworks. Installing a UI package is therefore separate from installing ai: the core package handles model calls and agent primitives, while the framework package helps manage frontend state, streaming messages, inputs, loading states, and errors in the application’s UI framework.

Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

npm install @ai-sdk/react

The README also demonstrates agent-oriented usage through ToolLoopAgent, including a shell-like tool that delegates command execution to a sandbox. That example is not an extra install command by itself, but it is an important signal for setup planning. Agent applications often need more than the ai dependency: they may need provider tools, sandbox infrastructure, approval policies, or a UI message type derived from an agent. Install the main package first, then add the provider and framework packages that match the agent’s tools and presentation layer.

Skill for Coding Agents

If you use coding agents such as Claude Code or Cursor, the package README recommends adding the AI SDK skill to your repository. This is an optional repository setup step, not a runtime dependency for your application. The intent is to give coding agents project-specific guidance for AI SDK conventions so they can generate, modify, or review SDK code with better context. The introduction page also documents llms.txt as a way to provide the full AI SDK documentation in Markdown to tools such as Cursor, Windsurf, Copilot, and Claude.

Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

npx skills add vercel/ai

Use the skill command after your repository exists and before you ask an agent to scaffold deeper AI SDK features. For example, install ai, commit the baseline application structure, add the skill, and then ask the coding agent to create a route handler, provider setup, or chatbot UI following AI SDK documentation. If the coding agent needs more context than the skill provides, the docs introduction recommends copying or referencing the llms.txt Markdown documentation and asking questions against that material.

Contributor and Verification Commands

Application developers usually only need their package-manager install command and a small runtime test. Contributors working inside this repository should also be aware of the root scripts because they describe how maintainers validate packages and docs. The root package defines scripts for building packages, building examples, running type checks, running tests, checking formatting or lint rules through Ultracite, validating docs property tables, and running release-related changeset flows. These scripts are not required to install the SDK in an app, but they are the right signals when modifying the SDK itself.

Sources: package.json

pnpm build
pnpm build:packages
pnpm type-check
pnpm test
pnpm validate:docs

A good installation smoke test is intentionally small: import a core function from ai, call it with a Gateway model string or a direct provider instance, and confirm your runtime can execute the request. For UI projects, add the framework package only when you are ready to wire streaming state into the frontend. For agent projects, install the provider packages and infrastructure required by the tools the agent will execute. Next, read the provider-selection and framework setup pages so installation turns into a working model call rather than an unused dependency.