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

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 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

// 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

# .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

// 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)	normalizeAzureBaseUrl function for endpoint sanitization
packages/docs/content/docs/configuration.mdx	Documents AZURE_OPENAI_ prefix and environment variable scheme
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:

# .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:

# 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}