/add-provider-package

name: add-provider-package
description: Guide for adding first-party AI provider packages to the AI SDK. Use when creating a provider package under packages/ to integrate an external AI service.
metadata:
  internal: true

Add a Provider Package

Add a complete first-party `@ai-sdk/<provider>` package that follows the current provider interfaces, repository conventions, security requirements, and release process.

Read the Current Sources of Truth

Before implementing anything, read:

• [Add new provider](../../contributing/add-new-provider.md) for current package and release requirements
• [Provider development notes](../../contributing/providers.md) for naming, schemas, and workflow serialization
• [Provider architecture](../../contributing/provider-architecture.md) for the provider abstraction
• [Secure URL handling](../../contributing/secure-url-handling.md) when the provider fetches polling, image, audio, video, or other URLs

Use [PR #18595](https://github.com/vercel/ai/pull/18595/changes) as a recent end-to-end example, but choose the current provider package whose API shape and model types most closely resemble the new provider as the implementation reference.

Third parties can publish provider packages outside this repository. A new first-party `@ai-sdk/<provider>` package requires prior discussion in an issue. Confirm that agreement exists before implementing the package.

Discover the API Contract

Before designing model classes, look for an official, versioned OpenAPI or Swagger specification in the provider's documentation or repositories. Prefer first-party specifications and record the source URL plus its version, publication date, or commit in the implementation notes or pull request.

Use the specification and official documentation to identify:

• base URLs and authentication schemes
• supported endpoints, model types, and capabilities
• request parameters and response shapes
• streaming transports and event formats
• error response envelopes
• asynchronous polling and download URL flows

Treat an OpenAPI specification as implementation evidence, not unquestioned truth. Specifications are often incomplete for server-sent events, streaming deltas, polymorphic content, tool calls, nullable fields, and errors. Do not add a generated client or generated production types by default. Implement minimal hand-written types and Zod schemas, then verify them against official documentation and captured API responses.

If no official specification exists, derive the contract from official documentation and real response fixtures, and note that limitation in the pull request.

Plan the Provider Shape

Determine which AI SDK model interfaces the provider supports, such as `LanguageModelV4`, `EmbeddingModelV4`, `ImageModelV4`, `SpeechModelV4`, `TranscriptionModelV4`, `RerankingModelV4`, or `Experimental_VideoModelV4`.

Before introducing a dependency, public API pattern, or new abstraction, read `contributing/decisions/README.md` and relevant accepted ADRs. Prefer existing provider utilities and implementation patterns.

Scaffold the Package

Create `packages/<provider>/` by adapting a current, comparable provider package. A typical package contains:

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<model-type>-model.ts
│   ├── <provider>-<model-type>-model.test.ts
│   └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js

Preserve current package conventions rather than recreating configuration from memory:

• Set the repository package version to exactly `2.0.0`, with no prerelease suffix.
• Create `CHANGELOG.md` with an initial `# @ai-sdk/<provider>` heading.
• Use the shared tsdown configuration and the current package-version injection pattern from a comparable provider package.
• Extend `./node_modules/@vercel/ai-tsconfig/ts-library.json`, enable a composite project, and add package references for workspace dependencies.
• Include the standard build, clean, type-check, Node test, and Edge test scripts.
• Include the standard `files`, documentation prepack, repository, bugs, engines, and public provenance publishing metadata.
• Use `workspace:*` for AI SDK workspace dependencies. Add `@ai-sdk/test-server` only when tests use it.
• Support the repository's Zod 3 and Zod 4 peer dependency range and use `zod/v4` for new implementation schemas.

Run `pnpm update-references` after adding or changing workspace dependencies.

Implement the Provider Factory

Follow the current provider factory pattern:

• Define a provider interface that extends `ProviderV4`.
• Export `create<Provider>(settings)` and a default provider instance.
• Make the provider callable when it has a meaningful default model type and comparable providers follow that pattern; otherwise return a provider object.
• Set `provider.specificationVersion = 'v4'`.
• Implement the fully specified factory methods required by `ProviderV4`, such as `languageModel`, `embeddingModel`, and `imageModel`.
• Add short aliases such as `chat`, `embedding`, or `image` only when they improve the provider's API.
• Throw `NoSuchModelError` from unsupported required model factories.
• Support provider-appropriate settings such as `apiKey`, `baseURL`, `headers`, and a custom `fetch` implementation.
• Load credentials with `loadApiKey` or the appropriate shared utility, normalize configurable base URLs, and include the package version in the user-agent suffix.
• Export the provider factory, default instance, public option types, model ID types, and `VERSION` from `src/index.ts`.

Implement Model Classes

Implement each supported model using the appropriate interface from `@ai-sdk/provider` and shared utilities from `@ai-sdk/provider-utils`.

P