OpenWikivercel/ai

Overview

The AI SDK repository is the source for Vercel’s provider-agnostic TypeScript toolkit for building AI applications and agents. Its public promise is that application code should use one set of primitives while remaining free to choose among model providers, frameworks, and runtime environments. The main package is named ai, and the documentation describes the SDK as useful with React, Next.js, Vue, Svelte, Node.js, and more. That means the repository is not only a model wrapper; it is a coordinated ecosystem for model calls, streaming interfaces, structured outputs, tool use, agent loops, and framework-facing user interfaces. Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

Purpose and Scope

Use this page when you need a first map of the repository before choosing a provider, installing packages, or deciding which API family to study. The SDK’s central design is provider independence: a developer can call a model through a uniform API, then move between Vercel AI Gateway model strings and direct provider packages as requirements change. The README shows both paths: passing a model string for Gateway-backed access, or installing provider packages such as OpenAI, Anthropic, and Google and importing provider instances directly. Sources: packages/ai/README.md

The product scope is broader than one-shot text generation. The introduction documentation names three primary surfaces: AI SDK Core for generating text, structured objects, tool calls, and agents; AI SDK UI for framework-agnostic hooks that support chat and generative interfaces; and AI SDK Harnesses for running established agent harnesses through a uniform HarnessAgent style surface. Read together, those surfaces explain why the repository contains core packages, provider packages, UI integrations, harness packages, examples, tools, and documentation rather than a single runtime library. Sources: content/docs/00-introduction/index.mdx, pnpm-workspace.yaml

Relevant Source Files

  • packages/ai/README.md — Describes the public AI SDK package, installation requirement, provider-agnostic positioning, Gateway and direct-provider examples, core usage examples, agents, UI integration, and the coding-agent skill.
  • content/docs/00-introduction/index.mdx — Provides the documentation-site introduction, explains why standardizing across providers matters, and names the primary public surfaces: Core, UI, and Harnesses.
  • package.json — Defines the root workspace as a private repository, records Node engine support, package manager version, documentation homepage, repository metadata, and the main build, test, type-check, release, and docs validation scripts.
  • pnpm-workspace.yaml — Defines the monorepo package layout for packages, tools, examples, and a Next.js RSC end-to-end test workspace entry.

Package Ecosystem and Repository Shape

The workspace manifest shows that this is a monorepo organized around packages/*, tools/*, and examples/*, with an additional end-to-end workspace entry for an RSC Next.js server test. That layout matches the public docs: the ecosystem includes the main ai package, individual provider packages, UI framework packages, harness packages, and supporting tools. The root package is private, so consumers normally install published workspace packages rather than the repository root. The package manager is pnpm, and the root scripts use Turborepo to coordinate builds, tests, publishing checks, documentation validation, and type checking across packages. Sources: package.json, pnpm-workspace.yaml

This structure matters because readers often arrive with different goals. A product engineer building a streaming chatbot usually starts with the main ai package plus a framework integration. A backend engineer writing retrieval, classification, or automation code may stay in AI SDK Core and call generation, embedding, or tool APIs directly. A platform engineer evaluating provider strategy may focus on Gateway, provider packages, custom provider management, and provider options. An agent developer may combine models, tools, loop control, runtime state, approvals, subagents, and possibly external harnesses. The repository supports all of those paths through shared primitives rather than isolated vertical products. Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

Core Primitives

The README’s examples introduce the most important primitive families. Text generation uses generateText from ai, with a model and prompt. Structured data generation uses the same generation surface with an Output.object schema, showing that typed outputs are a first-class workflow rather than a post-processing convention. Agent usage is represented with ToolLoopAgent, where a model receives a system instruction and tools extend what the model can do. UI integration adds framework packages such as @ai-sdk/react, allowing application state, streaming responses, and user-facing chat experiences to sit on top of the same model and message concepts. Sources: packages/ai/README.md

Agents deserve special attention in the overview because the docs frame them as language models that use tools in a loop to accomplish tasks. In the repository-facing README, the agent example wires a shell-like tool to an execution environment, showing the practical pattern: the model decides when to call a tool, application code executes the tool, and the loop continues until the task is complete or stopped. Related official docs also cover Model Context Protocol tools, where a provider tool can connect a model to remote MCP servers or service connectors. Treat MCP and Connections as extension surfaces for tools and provider capabilities, not replacements for the local tool contract shown in core examples. Sources: packages/ai/README.md

Provider-Agnostic Model Access

Provider choice is intentionally decoupled from most application code. By default, the README says the AI SDK uses Vercel AI Gateway so developers can pass model identifiers such as an OpenAI, Anthropic, or Google model string without installing every provider package first. When an application needs direct provider configuration, specialized packages expose provider instances such as an Anthropic instance imported from @ai-sdk/anthropic. The introduction documentation reinforces the reason for this design: integrating large language models is complicated and provider-dependent, so standardization lets teams focus on application behavior instead of constantly rewriting request and response plumbing. Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

A useful mental model is to separate the model selector from the operation being performed. The operation may be text generation, structured output generation, streaming chat, tool calling, image generation, embeddings, or an agent loop. The model selector tells the SDK which provider and model capability should handle that operation. Gateway model strings are convenient for fast setup and provider switching, while direct provider packages are appropriate when you need provider-specific authentication, options, or tools. This split is why later pages in this wiki distinguish foundations, provider selection, core function references, provider-specific packages, and UI transport behavior. Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

Development and Operations Signals

The root scripts show how maintainers operate the repository. build, build:packages, and build:examples delegate work to Turborepo filters. Type checking is available for the repository and a fuller configuration that includes examples. Test scripts exclude examples by default and define a stricter CI path that also excludes selected packages. Release scripts combine cleaning, building, Changesets versioning, and publishing. There are also scripts for documentation validation, consistency checks, formatting, linting, and worktree setup. The Node engines field requires modern Node releases, and the README specifically tells local users they need Node.js 22 or newer before installing the SDK. Sources: package.json, packages/ai/README.md

Next Steps

Start with the installation page if you are setting up a new project, then choose a provider path before writing production model calls. If you are still orienting yourself, read the library navigation page to understand which package family matches your framework or runtime. For backend tasks, continue to the AI SDK Core overview and generation guides. For user-facing streaming applications, move to the UI overview and transport pages. For autonomous workflows, read the agents overview, loop control, tool approvals, subagents, and harness reference pages. This page should give you enough context to choose the right next document rather than treating the monorepo as a flat list of packages. Sources: packages/ai/README.md, content/docs/00-introduction/index.mdx

Ask a question...