# How to Integrate Custom LLM Providers with OpenMAIC: A Complete Guide

> Integrate custom LLM providers with OpenMAIC using its centralized registry. Learn how to add static code definitions or dynamic UI configurations for OpenAI-compatible APIs.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-01

---

**OpenMAIC integrates custom LLM providers through a centralized registry in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts), supporting both static code definitions and dynamic UI-based configuration for any OpenAI-compatible API.**

OpenMAIC is built on top of the Vercel AI SDK (`generateText` and `streamText`) and provides a flexible abstraction layer for LLM integrations. By leveraging the **provider registry** architecture, you can seamlessly integrate custom LLM providers with OpenMAIC without modifying core application logic, whether you prefer code-controlled deployments or runtime UI configuration.

## Understanding the Provider Architecture

The LLM layer centers on two critical files in the `lib/ai/` directory. The [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) file defines the **provider registry** (`PROVIDERS` object starting at line 75), which stores metadata about each service, including base URLs, authentication requirements, and model capabilities. When the application needs to call an LLM, it routes through [`lib/ai/llm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/llm.ts), where the `callLLM` and `streamLLM` functions (lines 25-33) handle provider resolution and request dispatch.

Every provider entry in the registry must define:

- **ID and name** – Internal identifiers and UI labels
- **Base URL** – Default endpoint or custom URL from environment variables
- **Authentication flag** – Whether an API key is required
- **Model list** – Supported models with capabilities (streaming, tools, vision, thinking)

The system extracts the **model ID** and **provider ID** from the `params.model` object, builds provider-specific payloads via `injectProviderOptions` (lines 47-57), and executes the request through a unified fetch wrapper.

## Method 1: Adding a Static Provider Definition

For code-controlled deployments, hard-code your provider directly into the `PROVIDERS` object. This method provides version control and ensures consistent configuration across deployments.

### Step 1: Define the Provider Entry

Open [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) and add a new key to the `PROVIDERS` map following the existing pattern (reference the `openrouter` entry for structure):

```typescript
// lib/ai/providers.ts
export const PROVIDERS = {
  // ... existing providers
  myai: {
    id: 'myai',
    name: 'My-AI',
    type: 'openai',                     // Uses OpenAI-compatible path
    defaultBaseUrl: 'https://api.my-ai.com/v1',
    requiresApiKey: true,
    icon: '/logos/myai.svg',
    models: [
      {
        id: 'mygpt-4',
        name: 'MyGPT-4',
        contextWindow: 1048576,
        outputWindow: 65536,
        capabilities: {
          streaming: true,
          tools: true,
          vision: true,
          thinking: {
            toggleable: true,
            budgetAdjustable: true,
            defaultEnabled: true,
          },
        },
      },
    ],
  },
};

```

### Step 2: Add the Provider Icon

Place the provider's logo in the `public/logos/` directory and reference it in the `icon` field using a root-relative path.

### Step 3: Handle Custom Thinking Parameters (Optional)

If your service uses non-standard reasoning flags, extend `getCompatThinkingBodyParams` around line 990 to translate OpenMAIC's thinking configuration into vendor-specific payload fields:

```typescript
// lib/ai/providers.ts
function getCompatThinkingBodyParams(
  providerId: ProviderId,
  modelId: string,
  config: ThinkingConfig,
) {
  // ... existing cases ...
  case 'myai': {
    const mode = getThinkingMode(config);
    return mode === 'disabled' 
      ? { enable_thinking: false } 
      : { enable_thinking: true };
  }
}

```

## Method 2: Dynamic Provider Configuration via UI

For environments requiring runtime flexibility without code changes, OpenMAIC supports dynamic provider definitions stored in browser localStorage.

1. Navigate to **Settings** → **LLM Providers** in the UI
2. Click **Add Provider** and submit a JSON object matching the `ProviderConfig` interface (see the runtime loader in [`providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providers.ts) lines 85-92)
3. The UI persists the configuration under the `providersConfig` localStorage key
4. On page load, `getProviderConfig` (lines 85-92) merges this stored configuration with the built-in `PROVIDERS` list

This approach allows non-technical users to integrate custom endpoints without deploying new code, though it requires the custom service to follow the OpenAI API specification.

## Implementing Provider-Specific Features

When integrating providers that support **thinking** or reasoning modes (such as budget-controlled inference or effort levels), you must map OpenMAIC's abstract thinking configuration to the provider's specific API parameters.

The `thinkingContext.run` wrapper in [`lib/ai/llm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/llm.ts) injects vendor-specific body fields through the `injectProviderOptions` function. For providers requiring custom translation logic, add a case to `getCompatThinkingBodyParams` that converts the `ThinkingConfig` object into the expected payload structure. This ensures that toggles in the OpenMAIC UI correctly control reasoning behavior on the backend.

## Calling Your Custom Provider

Once registered (either statically or dynamically), invoke your provider through the unified `callLLM` interface by specifying the provider ID and model ID:

```typescript
import { callLLM } from '@/lib/ai/llm';

const response = await callLLM(
  {
    model: { 
      provider: 'myai', 
      modelId: 'mygpt-4' 
    },
    prompt: 'Explain quantum entanglement in simple terms.',
    maxOutputTokens: 1024,
    // Additional AI SDK parameters (tools, temperature, etc.)
  },
  'my-feature',  // Feature identifier for logging/tracking
);

```

The `callLLM` implementation automatically resolves the provider configuration, injects any thinking options via `buildThinkingProviderOptions`, and routes the request through the appropriate fetch wrapper in [`providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providers.ts).

## Summary

- **All LLM calls funnel through `callLLM` and `streamLLM`** in [`lib/ai/llm.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/llm.ts), providing a single integration point for the entire platform
- **Static provider definitions** in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) (line 75) offer version-controlled, code-based configuration ideal for production deployments
- **Dynamic configuration** via localStorage (lines 85-92) enables UI-driven provider addition without code changes
- **Thinking/reasoning support** requires extending `getCompatThinkingBodyParams` (around line 990) to map abstract configs to vendor-specific API fields
- **OpenAI-compatible APIs** integrate seamlessly using the `type: 'openai'` designation, requiring only base URL and model metadata configuration

## Frequently Asked Questions

### What file do I modify to add a custom LLM provider permanently?

Add your provider definition to the `PROVIDERS` object in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) starting around line 75. This static registry ensures your configuration persists across deployments and version control tracks changes to your provider integration.

### Can users add LLM providers without editing code?

Yes. OpenMAIC supports dynamic provider configuration through the Settings UI, which stores provider JSON in `localStorage` under the key `providersConfig`. The `getProviderConfig` function (lines 85-92) automatically merges these runtime definitions with the built-in registry on page load, enabling non-technical users to configure endpoints.

### How do I handle custom reasoning or thinking parameters for my provider?

Extend the `getCompatThinkingBodyParams` function in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) (around line 990) to translate OpenMAIC's `ThinkingConfig` into your provider's specific API fields. Add a case for your provider ID that returns the appropriate payload structure based on the thinking mode (enabled/disabled) and budget configuration.

### Does OpenMAIC support non-OpenAI API formats?

While OpenMAIC is optimized for OpenAI-compatible APIs (using `type: 'openai'`), you can technically support other formats by modifying the fetch wrapper logic in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts). However, this requires deeper customization of the request building logic beyond the standard provider registry configuration.