/add-provider-package

name: add-provider-package
description: Guide for adding new AI provider packages to the AI SDK. Use when creating a new @ai-sdk/<provider> package to integrate an AI service into the SDK.
metadata:
  internal: true

Adding a New Provider Package

This guide covers the process of creating a new `@ai-sdk/<provider>` package to integrate an AI service into the AI SDK.

First-Party vs Third-Party Providers

• **Third-party packages**: Any provider can create a third-party package. We're happy to link to it from our documentation.
• **First-party `@ai-sdk/<provider>` packages**: If you prefer a first-party package, please create an issue first to discuss.

Reference Example

See https://github.com/vercel/ai/pull/8136/files for a complete example of adding a new provider.

Provider Architecture

The AI SDK uses a layered provider architecture following the adapter pattern:

1. **Specifications** (`@ai-sdk/provider`): Defines interfaces like `LanguageModelV4`, `EmbeddingModelV4`, etc. 2. **Utilities** (`@ai-sdk/provider-utils`): Shared code for implementing providers 3. **Providers** (`@ai-sdk/<provider>`): Concrete implementations for each AI service 4. **Core** (`ai`): High-level functions like `generateText`, `streamText`, `generateObject`

Step-by-Step Guide

1. Create Package Structure

Create a new folder `packages/<provider>` with the following structure:

packages/<provider>/
├── src/
│   ├── index.ts                  # Main exports
│   ├── version.ts                # Package version
│   ├── <provider>-provider.ts    # Provider implementation
│   ├── <provider>-provider.test.ts
│   ├── <provider>-*-options.ts   # Model-specific options
│   └── <provider>-*-model.ts     # Model implementations (e.g., language, embedding, image)
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsup.config.ts
├── turbo.json
├── vitest.node.config.js
├── vitest.edge.config.js
└── README.md

Do not create a `CHANGELOG.md` file. It will be auto-generated.

2. Configure package.json

Set up your `package.json` with:

• `"name": "@ai-sdk/<provider>"`
• `"version": "0.0.0"` (initial version, will be updated by changeset)
• `"type": "module"`
• `"license": "Apache-2.0"`
• `"sideEffects": false`
• Dependencies on `@ai-sdk/provider` and `@ai-sdk/provider-utils` (use `workspace:*`)
• Dev dependencies: `@ai-sdk/test-server`, `@types/node`, `@vercel/ai-tsconfig`, `tsup`, `typescript`, `zod`
• `"engines": { "node": ">=22" }`
• Peer dependency on `zod` (both v3 and v4): `"zod": "^3.25.76 || ^4.1.8"`

Example package entry point configuration:

{
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

3. Create TypeScript Configurations

**tsconfig.json**:

{
  "extends": "@vercel/ai-tsconfig/base.json",
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

**tsconfig.build.json**:

{
  "extends": "./tsconfig.json",
  "exclude": [
    "**/*.test.ts",
    "**/*.test-d.ts",
    "**/__snapshots__",
    "**/__fixtures__"
  ]
}

4. Configure Build Tool (tsup)

Create `tsup.config.ts`:

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  sourcemap: true,
  clean: true,
});

5. Configure Test Runners

Create both `vitest.node.config.js` and `vitest.edge.config.js` (copy from existing provider like `anthropic`).

6. Implement Provider

**Provider implementation pattern**:

// <provider>-provider.ts
import { NoSuchModelError } from '@ai-sdk/provider';
import { loadApiKey } from '@ai-sdk/provider-utils';

export interface ProviderSettings {
  apiKey?: string;
  baseURL?: string;
  // provider-specific settings
}

export class ProviderInstance {
  readonly apiKey?: string;
  readonly baseURL?: string;

  constructor(options: ProviderSettings = {}) {
    this.apiKey = options.apiKey;
    this.baseURL = options.baseURL;
  }

  private get baseConfig() {
    return {
      apiKey: () =>
        loadApiKey({
          apiKey: this.apiKey,
          environmentVariableName: 'PROVIDER_API_KEY',
          description: 'Provider API key',
        }),
      baseURL: this.baseURL ?? 'https://api.provider.com',
    };
  }

  languageModel(modelId: string) {
    return new ProviderLanguageModel(modelId, this.baseConfig);
  }

  // Shorter alias
  chat(modelId: string) {
    return this.languageModel(modelId);
  }
}

// Export default instance
export const providerName = new ProviderInstance();

7. Implement Model Classes

Each model type (language, embedding, image, etc.) should implement the appropriate interface from `@ai-sdk/provider`:

• `LanguageModelV4` for text generation models
• `EmbeddingModelV4` for embedding models
• `ImageModelV4` for image generation models
• etc.

**Schema guidelines**:

**Provider Options** (user-facing):

• Use `.optional()` unless `null` is meaningful
• Be as restrictive as possible for future flexibility

**Response Schemas** (API responses):

• Use `.nullish()` instead of `.optional()`
• Keep minimal - only include properties you need
• Allow flexibility for provider API changes

8. Create README.md

Include:

• Brief description linking to documentation
• Installation instructions
• Basic usage example
• Link to full documentation

9. Write Tests

• Unit tests for provider logic
• API response parsing tests using fixtures in `__fixtures__` subdirectory
• Both Node.js and Edge runtime tests

See `capture-api-response-test-fixture` skill for capturing real API responses for testing.

10. Add Examples

Create examples in `examples/ai-functions/src/` for each model type the provider supports:

• `generate-text/<provider>.ts` - Basic text generation

-