Migrate azure
Migrate from Azure OpenAI to Merge Gateway. Use when the user wants to switch from Azure OpenAI, replace AzureOpenAI SDK calls, or move off Azure deployments.From its SKILL.md
npx -y skills add merge-api/merge-gateway-skills --skill migrate-azureAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.6 KB, as published. Nobody here has run it
Migrate Azure OpenAI to Merge Gateway
Migrate from the Azure OpenAI SDK to the Merge Gateway SDK.
Language Support
The Merge Gateway SDK is available in both Python and TypeScript/Node:
- Python:
pip3 install merge-gateway-sdk - TypeScript/Node:
npm install merge-gateway-sdk
Detect the user's stack and show the relevant language.
Steps
0. Check for Plugin Updates
Before proceeding, ensure the user has the latest version of the Merge Gateway skills by running:
claude plugin update merge-gateway@merge-gateway-skills
Run this update and wait for it to complete before continuing to Step 1.
1. Search for Azure OpenAI Usage
Search the project for all Azure OpenAI references:
- Imports:
from openai import AzureOpenAI,import { AzureOpenAI },AzureOpenAI - Constructors:
AzureOpenAI(,new AzureOpenAI({ - Parameters:
azure_endpoint,api_version,azure_deployment,azure_ad_token - Env vars:
AZURE_OPENAI_API_KEY,AZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_VERSION,AZURE_OPENAI_DEPLOYMENT,AZURE_API_KEY - Config files:
.env,.env.example,appsettings.json,docker-compose.yml
Report all findings to the user before making changes.
2. Check for Prior Migration
Check if MERGE_GATEWAY or api-gateway.merge.dev already exists in the project. If so, report which parts are already migrated and skip those.
3. Map Azure Deployments to Gateway Model Names
Azure uses custom deployment names that map to underlying models. Ask the user what model each deployment name maps to:
Common mappings:
| Azure Deployment (example) | Gateway Model Name |
|---|---|
gpt-4o / my-gpt4o-deployment | openai/gpt-4o |
gpt-4o-mini / my-gpt4o-mini | openai/gpt-4o-mini |
gpt-4-turbo / my-gpt4-turbo | openai/gpt-4-turbo |
gpt-35-turbo / my-gpt35 | openai/gpt-3.5-turbo |
text-embedding-ada-002 | openai/text-embedding-ada-002 |
IMPORTANT: Azure deployment names are user-defined and may not match the model name. Always ask the user to confirm the mapping.
4. Migrate Client Constructors
Replace AzureOpenAI with the Merge Gateway SDK.
Choose your migration path: Ask the user whether they want the quick migration (Option A) or the full migration (Option B).
STOP here and wait for the user's response. Do NOT proceed until they answer. Once they answer, follow ONLY the matching option below:
Option A — Quick migration (keep OpenAI SDK): Since Azure OpenAI uses the OpenAI SDK, you can keep it and just point at Gateway.
Python:
# Quick path — keep OpenAI SDK, point at Gateway
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MERGE_GATEWAY_API_KEY"],
base_url="https://api-gateway.merge.dev/v1/openai",
)
# Replace deployment names with provider-prefixed models: "my-gpt4o" → "openai/gpt-4o"
TypeScript:
// Quick path — keep OpenAI SDK, point at Gateway
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.MERGE_GATEWAY_API_KEY!,
baseURL: "https://api-gateway.merge.dev/v1/openai",
});
// Replace deployment names with provider-prefixed models: "my-gpt4o" → "openai/gpt-4o"
Option B — Full migration (native Merge Gateway SDK): Switch to the Merge Gateway SDK for full access to tags, routing metadata, and model discovery.
Python:
# Before
from openai import AzureOpenAI
client = AzureOpenAI(
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
api_key=os.environ["AZURE_OPENAI_API_KEY"],
api_version="2024-02-01",
)
# After
from merge_gateway import MergeGateway
client = MergeGateway(
api_key=os.environ["MERGE_GATEWAY_API_KEY"],
)
TypeScript:
// Before
import { AzureOpenAI } from "openai";
const client = new AzureOpenAI({
endpoint: process.env.AZURE_OPENAI_ENDPOINT,
apiKey: process.env.AZURE_OPENAI_API_KEY,
apiVersion: "2024-02-01",
deployment: "my-gpt4o-deployment",
});
// After
import { MergeGateway } from "merge-gateway-sdk";
const client = new MergeGateway({
apiKey: process.env.MERGE_GATEWAY_API_KEY!,
});
5. Update API Calls
Replace Azure deployment names with Gateway model names in all API calls:
Python:
# Before
response = client.chat.completions.create(
model="my-gpt4o-deployment", # Azure deployment name
messages=[{"role": "user", "content": "Hello!"}],
)
# After
response = client.responses.create(
model="openai/gpt-4o", # Gateway provider-prefixed model
input=[{"type": "message", "role": "user", "content": "Hello!"}],
)
If the code passes model as a variable, trace back to where the value is defined and update it there.
6. Remove Azure-Specific Parameters
Remove all Azure-specific configuration:
api_version— not needed with Gatewayazure_deployment— replaced by model name in API callsazure_endpoint— replaced by Gateway base URLazure_ad_token/azure_ad_token_provider— replaced by Gateway API key
If using Azure AD token authentication:
# Before
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
client = AzureOpenAI(
azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
azure_ad_token_provider=token_provider,
)
# After
from merge_gateway import MergeGateway
client = MergeGateway(
api_key=os.environ["MERGE_GATEWAY_API_KEY"],
)
The azure-identity dependency can be removed if only used for Azure OpenAI.
7. Update Environment Variables
Old Azure keys are replaced by a single MERGE_GATEWAY_API_KEY.
First, ask the user: "Are you setting this up for local development or a deployed environment?"
STOP here and wait for the user's response. Do NOT proceed until they answer. Once they answer, follow ONLY the matching path below:
-
Local development: Tell the user to run this in their terminal, replacing
mg_YOUR_KEYwith their actual key from gateway.merge.dev:! echo "MERGE_GATEWAY_API_KEY=mg_YOUR_KEY" >> .envThen verify
.gitignoreincludes.env. Comment out (do NOT delete) old Azure keys in.env:# AZURE_OPENAI_API_KEY=... # Replaced by MERGE_GATEWAY_API_KEY # AZURE_OPENAI_ENDPOINT=... # Replaced by MERGE_GATEWAY_API_KEY # AZURE_OPENAI_API_VERSION=... # Replaced by MERGE_GATEWAY_API_KEY # AZURE_OPENAI_DEPLOYMENT=... # Replaced by MERGE_GATEWAY_API_KEY -
Deployed / CI/CD: Tell the user to add
MERGE_GATEWAY_API_KEYto their secrets manager or CI/CD environment variables, and remove the old Azure keys (AZURE_OPENAI_API_KEY,AZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_VERSION,AZURE_OPENAI_DEPLOYMENT) from their secrets configuration.
Never ask the user to paste their API key into the Claude conversation. Always give them a command or instructions they execute themselves.
8. Verify
Generate a test script:
Python (test_gateway.py):
import os
from dotenv import load_dotenv
from merge_gateway import MergeGateway
load_dotenv()
client = MergeGateway(
api_key=os.environ["MERGE_GATEWAY_API_KEY"],
)
response = client.responses.create(
model="openai/gpt-4o-mini",
input=[{"type": "message", "role": "user", "content": "What is 2 + 2? Reply with just the number."}],
)
print("Gateway response:", response.output[0].content[0].text)
print("Model used:", response.model)
print("Migration verified successfully!")
TypeScript (test_gateway.ts):
import dotenv from "dotenv";
import { MergeGateway } from "merge-gateway-sdk";
dotenv.config();
const client = new MergeGateway({
apiKey: process.env.MERGE_GATEWAY_API_KEY!,
});
async function main() {
const response = await client.responses.create({
model: "openai/gpt-4o-mini",
input: [{ type: "message", role: "user", content: "What is 2 + 2? Reply with just the number." }],
});
console.log("Gateway response:", response.output[0].content[0].text);
console.log("Model used:", response.model);
console.log("Migration verified successfully!");
}
main();
Embeddings migration:
Azure embeddings migrate the same way — just prefix the model name:
# Before (Azure)
response = client.embeddings.create(model="text-embedding-ada-002", input="Hello")
# After (Merge Gateway)
response = client.embeddings.create(model="openai/text-embedding-ada-002", input="Hello")
# Response format is the same: response.data[0].embedding
TypeScript:
// Before (Azure)
const response = await client.embeddings.create({ model: "text-embedding-ada-002", input: "Hello" });
// After (Merge Gateway)
const response = await client.embeddings.create({ model: "openai/text-embedding-ada-002", input: "Hello" });
// Response format is the same: response.data[0].embedding
Cross-Cutting Rules
- Never delete old configuration — comment out old env vars with a note about the replacement.
- Idempotency — Check if migration is already partially applied before making changes.
- Provider-prefixed models — ALL model names must use
provider/modelformat. - Base URL — The SDK defaults to
https://api-gateway.merge.dev/v1. Only passbase_url/baseUrlif the user has a custom gateway endpoint. - Azure deployment names are opaque — Always ask the user to confirm what model each deployment maps to.