# How to Configure Azure OpenAI for OpenMAIC: Complete Environment Variable Setup

> Configure Azure OpenAI for OpenMAIC by setting essential environment variables. Learn how to set AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_<DEPLOYMENT> for seamless integration and model selection.

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

---

**Configure Azure OpenAI for OpenMAIC by setting `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, and `AZURE_OPENAI_<DEPLOYMENT>` environment variables, where each deployment name becomes a selectable model ID in the UI.**

OpenMAIC treats **Azure OpenAI** as a first-class LLM provider through a streamlined configuration system based on environment variables. This guide explains how the platform normalizes endpoints, registers deployments, and exposes Azure models to users—based on the actual implementation in `THU-MAIC/OpenMAIC`.

## Required Environment Variables for Azure OpenAI

All Azure-related settings use the **`AZURE_OPENAI_`** prefix. OpenMAIC reads these at startup to initialize the provider and populate the model selector.

| Variable | Purpose | Example |
|----------|---------|---------|
| `AZURE_OPENAI_ENDPOINT` | Base URL of your Azure OpenAI resource | `https://myresource.openai.azure.com` |
| `AZURE_OPENAI_API_KEY` | API key from Azure Portal | `YOUR_AZURE_API_KEY` |
| `AZURE_OPENAI_<DEPLOYMENT>` | Deployment name to expose as a model | `AZURE_OPENAI_GPT35_TURBO=gpt-35-turbo` |

Unlike other providers, Azure OpenAI has no fixed model IDs—**each deployment name becomes a selectable model** in the OpenMAIC interface.

## Azure Endpoint Normalization

Azure Portal displays full inference URLs like:

```

https://myresource.openai.azure.com/openai/deployments/gpt-35-turbo/chat/completions

```

The Vercel AI SDK expects only the base URL. OpenMAIC's `normalizeAzureBaseUrl` function in [`lib/ai/azure.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/azure.ts) handles this conversion automatically by:

- Stripping `/chat/completions`, `/responses`, and `/deployments/<name>` segments
- Adding `/openai` to the path when needed for classic Azure hosts
- Removing trailing slashes

```ts
// lib/ai/azure.ts — endpoint normalization logic
import { normalizeAzureBaseUrl } from '@/lib/ai/azure';

const rawEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
// Input:  "https://myresource.openai.azure.com/openai/deployments/gpt-35-turbo/chat/completions"
// Output: "https://myresource.openai.azure.com/openai"
const baseUrl = normalizeAzureBaseUrl(rawEndpoint);

```

## Step-by-Step Configuration

### 1. Create Your Environment File

```bash

# .env.local — Azure OpenAI configuration for OpenMAIC

# Required: Base endpoint (no operation paths)

AZURE_OPENAI_ENDPOINT=https://myresource.openai.azure.com

# Required: API key from Azure Portal

AZURE_OPENAI_API_KEY=sk-abc123...

# Required: Register each deployment as a model

# Format: AZURE_OPENAI_<LABEL>=<deployment-name>

AZURE_OPENAI_GPT35_TURBO=gpt-35-turbo
AZURE_OPENAI_GPT4=gpt-4
AZURE_OPENAI_GPT4_TURBO=gpt-4-turbo

```

The label after `AZURE_OPENAI_` (e.g., `GPT35_TURBO`) is used for display purposes; the value (e.g., `gpt-35-turbo`) is the actual **deployment name** sent to Azure.

### 2. How OpenMAIC Registers Azure Models at Startup

During initialization, OpenMAIC performs four steps as implemented in the provider configuration system:

1. **Read** `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY`
2. **Normalize** the endpoint via `normalizeAzureBaseUrl`
3. **Parse** all `AZURE_OPENAI_<DEPLOYMENT>` variables to build the model list
4. **Register** each deployment as a selectable model in the UI

```ts
// Illustrative structure from the provider initialization
import { AzureOpenAI } from '@ai-sdk/azure';
import { normalizeAzureBaseUrl } from '@/lib/ai/azure';

const baseUrl = normalizeAzureBaseUrl(process.env.AZURE_OPENAI_ENDPOINT);
const apiKey = process.env.AZURE_OPENAI_API_KEY;

const azureProvider = new AzureOpenAI({
  apiKey,
  endpoint: baseUrl,
});

// Extract deployment names from environment variables
const azureModels = Object.entries(process.env)
  .filter(([key]) => 
    key.startsWith('AZURE_OPENAI_') && 
    !key.endsWith('_ENDPOINT') && 
    !key.endsWith('_API_KEY')
  )
  .map(([key, deploymentName]) => ({
    id: deploymentName,        // sent to Azure as deployment name
    name: key.replace('AZURE_OPENAI_', ''),  // display label
    provider: azureProvider,
  }));

```

### 3. Runtime Behavior

When a user selects a model like "GPT4" in the OpenMAIC UI:

- The **deployment name** (`gpt-4`) is passed to the Vercel AI SDK
- The SDK constructs the final URL: `<endpoint>/openai/deployments/gpt-4/chat/completions`
- Azure routes the request to the appropriate model deployment

This design allows multiple Azure deployments to coexist as independent model options without code changes.

## Key Source Files

| File | Role |
|------|------|
| [[`lib/ai/azure.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/azure.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/azure.ts) | `normalizeAzureBaseUrl` function for endpoint sanitization |
| [`packages/docs/content/docs/configuration.mdx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/docs/content/docs/configuration.mdx) | Documents `AZURE_OPENAI_` prefix and environment variable scheme |
| [`packages/docs/content/docs/supported-models.mdx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/docs/content/docs/supported-models.mdx) | Explains deployment-name-as-model-ID behavior |

## Common Configuration Patterns

### Multiple Azure Regions

Use environment-specific `.env` files or prefixed variables if running multiple OpenMAIC instances:

```bash

# .env.production — East US deployment

AZURE_OPENAI_ENDPOINT=https://myapp-eastus.openai.azure.com
AZURE_OPENAI_API_KEY=key-for-eastus

# .env.staging — West Europe deployment  

AZURE_OPENAI_ENDPOINT=https://myapp-westeurope.openai.azure.com
AZURE_OPENAI_API_KEY=key-for-westeurope

```

### Fallback to Other Providers

Azure OpenAI can coexist with Ollama, Lemonade, or other providers. OpenMAIC's configuration loader treats each `*_ENDPOINT` pattern independently:

```bash

# Azure + Local Ollama configuration

AZURE_OPENAI_ENDPOINT=https://myresource.openai.azure.com
AZURE_OPENAI_API_KEY=azure-key
AZURE_OPENAI_GPT4=gpt-4

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

```

## Azure OpenAI vs. Standard OpenAI Configuration

| Aspect | Azure OpenAI | Standard OpenAI |
|--------|-------------|-----------------|
| **Endpoint format** | Regional resource URL | `https://api.openai.com/v1` |
| **Model identification** | Deployment names | Fixed model IDs (`gpt-4`, etc.) |
| **Environment prefix** | `AZURE_OPENAI_` | `OPENAI_` |
| **Endpoint normalization** | `normalizeAzureBaseUrl` required | Direct usage |
| **Authentication** | API key per resource | Single API key |

As documented in `packages/docs/content/docs/supported-models.mdx`, this distinction is why Azure requires the additional configuration layer for deployment mapping.

## Summary

- **Use `AZURE_OPENAI_` prefix** for all Azure-related environment variables
- **Provide the base endpoint only**—`normalizeAzureBaseUrl` in [`lib/ai/azure.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/azure.ts) handles path cleanup
- **Register deployments as models** via `AZURE_OPENAI_<LABEL>=<deployment-name>` variables
- **Deployment names become model IDs** in the OpenMAIC UI, not fixed model names
- **Multiple deployments** can be exposed by adding more environment variables

## Frequently Asked Questions

### What happens if I paste the full Azure Portal URL into `AZURE_OPENAI_ENDPOINT`?

OpenMAIC's `normalizeAzureBaseUrl` function automatically strips operation paths like `/chat/completions` and deployment segments. However, providing the clean base URL (`https://myresource.openai.azure.com`) is recommended for clarity.

### Why does OpenMAIC use deployment names instead of model IDs?

Azure OpenAI deployments are user-defined and region-specific—there is no global `gpt-4` identifier. OpenMAIC treats each deployment name as a unique model ID to match Azure's architecture, as implemented in the provider registration logic.

### Can I use Azure Active Directory authentication instead of API keys?

The current implementation in [`lib/ai/azure.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/azure.ts) uses `AzureOpenAI` from the Vercel AI SDK with `apiKey` configuration. Azure AD token-based authentication would require extending the provider initialization to support `az identity` or token credentials.

### How do I verify my Azure configuration is working?

Check the OpenMAIC startup logs for registered providers. The model selector should display your deployment labels. If models are missing, verify that environment variables follow the `AZURE_OPENAI_<DEPLOYMENT>` pattern and that `AZURE_OPENAI_ENDPOINT` excludes operation paths.