# How to Add a New Custom AI Provider to Read Frog's Vercel AI SDK Integration

> Learn how to add a custom AI provider to Read Frog using the Vercel AI SDK. Extend type definitions, register UI assets, and wire the factory function with this guide.

- Repository: [MengXi/read-frog](https://github.com/mengxi-ream/read-frog)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Adding a custom AI provider to Read Frog requires extending type definitions in [`src/types/config/provider.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/types/config/provider.ts), registering UI assets and defaults in [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts), and wiring the Vercel AI SDK factory function in [`src/utils/providers/model.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/providers/model.ts) to enable runtime instantiation.**

Read Frog abstracts every LLM service behind a unified **provider-model layer** compatible with the Vercel AI SDK. When you add a new custom AI provider to Read Frog, you extend this abstraction to support additional language model endpoints without modifying the core chat completion logic.

## The Three-Layer Architecture

Read Frog's provider system consists of three distinct layers that handle type safety, user interface rendering, and runtime SDK instantiation. Understanding this architecture ensures your integration remains maintainable and fully type-safe.

### Type Definitions and Validation

The first layer establishes compile-time safety through TypeScript literals and Zod schemas. In [`src/types/config/provider.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/types/config/provider.ts), you must add the provider identifier to `LLM_PROVIDER_TYPES` (or `API_PROVIDER_TYPES` if applicable) and define a validation schema for its models using `createProviderModelSchema`.

This file also exports `ALL_PROVIDER_TYPES`, which aggregates every supported service. Adding your provider literal here enables TypeScript to validate provider strings throughout the codebase.

### Default Configuration and UI Assets

The second layer supplies **user-facing metadata** and fallback configurations. In [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts), you define three critical mappings:

- `DEFAULT_LLM_PROVIDER_MODELS`: Specifies the default model identifier, whether custom models are allowed, and the custom model placeholder
- `PROVIDER_ITEMS`: Contains the logo component, display name, and website URL rendered in the settings UI
- `DEFAULT_PROVIDER_CONFIG`: Provides the complete default provider object including enabled status and localization keys

These constants power the provider selection dropdown in Read Frog's interface.

### Factory Mapping and Runtime Resolution

The third layer handles **SDK instantiation** at runtime. The file [`src/utils/providers/model.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/providers/model.ts) exports `CREATE_AI_MAPPER`, which maps provider ID strings to Vercel AI SDK factory functions.

When a user sends a message, `getModelById()` retrieves the stored configuration, selects the appropriate factory from `CREATE_AI_MAPPER`, builds the SDK instance, and returns `provider.languageModel(modelId)` to the chat engine. If your provider requires special headers (such as beta feature flags), extend `CUSTOM_HEADER_MAP` in the same file.

## Step-by-Step Implementation

Follow these concrete steps to integrate a hypothetical provider named `myai` that ships with its own Vercel-compatible package `@myai/ai-sdk-provider`.

### 1. Install the Provider SDK

Add the provider's package to your dependencies:

```bash
pnpm add @myai/ai-sdk-provider

```

### 2. Update Type Definitions

Extend the provider type unions and model enums in [`src/types/config/provider.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/types/config/provider.ts):

```typescript
// Add to the provider types array
export const LLM_PROVIDER_TYPES = [
  // …existing providers,
  "myai",
] as const;

// Register available models (typically in utils/constants/models.ts)
export const LLM_PROVIDER_MODELS = {
  // …existing entries,
  myai: ["my-model-1", "my-model-2"] as const,
};

// Create the Zod validation schema
baseAPIProviderConfigSchema.extend({
  provider: z.literal("myai"),
  model: createProviderModelSchema<"myai">("myai"),
}),

```

### 3. Register UI Assets and Defaults

Populate the configuration constants in [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts):

```typescript
import myaiLogo from "@/assets/providers/myai.svg";

// Default model configuration
export const DEFAULT_LLM_PROVIDER_MODELS = {
  // …existing entries,
  myai: {
    model: "my-model-1",
    isCustomModel: false,
    customModel: null,
  },
};

// UI display metadata
export const PROVIDER_ITEMS = {
  // …existing entries,
  myai: {
    logo: () => myaiLogo,
    name: "MyAI",
    website: "https://myai.example.com",
  },
};

// Complete default provider entry
export const DEFAULT_PROVIDER_CONFIG = {
  // …existing entries,
  myai: {
    id: "myai-default",
    name: PROVIDER_ITEMS.myai.name,
    description: i18n.t("options.apiProviders.providers.description.myai"),
    enabled: true,
    provider: "myai",
    model: DEFAULT_LLM_PROVIDER_MODELS.myai,
  },
};

```

### 4. Wire the Factory Mapper

Connect the provider to the Vercel AI SDK runtime in [`src/utils/providers/model.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/providers/model.ts):

```typescript
import { createMyAI } from "@myai/ai-sdk-provider";

const CREATE_AI_MAPPER = {
  // …existing entries,
  myai: createMyAI,
} as const;

// Optional: Add custom headers if required
const CUSTOM_HEADER_MAP = {
  // …existing entries,
  myai: { "x-myai-feature": "true" },
};

```

Once these changes are applied, the `myai` provider appears in the Read Frog settings UI, persists user selections to storage, and instantiates correctly when `getModelById("myai")` invokes the factory during chat completion requests.

## Summary

- **Type definitions** in [`src/types/config/provider.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/types/config/provider.ts) enforce compile-time safety through `LLM_PROVIDER_TYPES` and Zod schemas
- **Configuration constants** in [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts) supply default models, UI logos, and provider metadata via `PROVIDER_ITEMS`
- **Factory mapping** in [`src/utils/providers/model.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/providers/model.ts) bridges the provider ID to Vercel AI SDK instantiation via `CREATE_AI_MAPPER`
- The `getModelById()` function orchestrates runtime resolution by selecting the correct factory and returning `provider.languageModel(modelId)`
- Special headers can be injected through `CUSTOM_HEADER_MAP` for provider-specific requirements
- Contributors can reference the internal checklist at [`.cursor/commands/add-provider.md`](https://github.com/mengxi-ream/read-frog/blob/main/.cursor/commands/add-provider.md) for additional validation steps

## Frequently Asked Questions

### Do I need to modify the chat completion logic when adding a new provider?

No. Read Frog's architecture isolates provider-specific code to the three layers described above. The chat engine consumes the generic `LanguageModel` interface returned by `getModelById()`, so once you register the factory in `CREATE_AI_MAPPER`, the existing completion logic handles the new provider automatically according to the Vercel AI SDK specification.

### Can I support custom model IDs that aren't predefined in the enum?

Yes. Set `isCustomModel: true` within `DEFAULT_LLM_PROVIDER_MODELS` for your provider in [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts). This exposes a text input in the UI where users can enter arbitrary model identifiers, bypassing the restricted enum validation while still maintaining type safety for the provider itself.

### What file should I check if my provider isn't appearing in the settings dropdown?

Verify that you have added an entry to `PROVIDER_ITEMS` in [`src/utils/constants/providers.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/constants/providers.ts) and that your provider literal exists in `LLM_PROVIDER_TYPES` within [`src/types/config/provider.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/types/config/provider.ts). Missing either entry will prevent the UI from rendering the provider option, as the dropdown consumes both the type union and the metadata object.

### How does Read Frog handle authentication headers for custom providers?

The Vercel AI SDK factory pattern encapsulates authentication within the factory function (such as `createMyAI`) that you import and map in [`src/utils/providers/model.ts`](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/providers/model.ts). For provider-specific headers unrelated to authentication (such as feature flags or version markers), extend `CUSTOM_HEADER_MAP` in the same file to inject additional headers during SDK instantiation.