ContextQMD
Back to Mastra

Azure OpenAI | Gateways | Mastra

docs/src/content/en/models/gateways/azure-openai.mdx

2025-12-184.2 KB
Original Source

Azure OpenAI

Azure OpenAI provides enterprise-grade access to OpenAI models through dedicated deployments with security, compliance, and SLA guarantees.

Unlike other providers that have fixed model names, Azure uses deployment names that you configure in the Azure Portal.

How Azure Deployments Work

Azure model IDs follow this pattern: azure-openai/your-deployment-name

The deployment name is specific to your Azure account and chosen when you create a deployment in Azure Portal. Common examples:

  • azure-openai/my-gpt4-deployment
  • azure-openai/production-gpt-35-turbo
  • azure-openai/staging-gpt-4o

Setup

Create deployments in Azure OpenAI Studio. The resource name and API key are in Azure Portal under "Keys and Endpoint".

Configuration

Instantiate the gateway and pass it to Mastra. Three configuration modes are available.

Static Deployments

Provide deployment names from Azure Portal.

typescript
import { Mastra } from "@mastra/core";
import { AzureOpenAIGateway } from "@mastra/core/llm";

export const mastra = new Mastra({
  gateways: [
    new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
      deployments: ["gpt-4-prod", "gpt-35-turbo-dev"],
    }),
  ],
});

Dynamic Discovery

Provide Management API credentials. The gateway queries Azure Management API to list deployments.

typescript
import { Mastra } from "@mastra/core";
import { AzureOpenAIGateway } from "@mastra/core/llm";

export const mastra = new Mastra({
  gateways: [
    new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
      management: {
        tenantId: process.env.AZURE_TENANT_ID!,
        clientId: process.env.AZURE_CLIENT_ID!,
        clientSecret: process.env.AZURE_CLIENT_SECRET!,
        subscriptionId: process.env.AZURE_SUBSCRIPTION_ID!,
        resourceGroup: "my-resource-group",
      },
    }),
  ],
});

The Service Principal requires "Cognitive Services User" role. See Azure documentation.

Manual Deployment Names

Provide resource name and API key only. Specify deployment names when creating agents. No IDE autocomplete.

typescript
import { Mastra } from "@mastra/core";
import { AzureOpenAIGateway } from "@mastra/core/llm";

export const mastra = new Mastra({
  gateways: [
    new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
    }),
  ],
});

Configuration Reference

OptionTypeRequiredDescription
resourceNamestringYesAzure OpenAI resource name
apiKeystringYesAPI key from "Keys and Endpoint"
apiVersionstringNoAPI version (default: 2024-04-01-preview)
deploymentsstring[]NoDeployment names for static mode
managementobjectNoManagement API credentials
management.tenantIdstringYes*Azure AD tenant ID
management.clientIdstringYes*Service Principal client ID
management.clientSecretstringYes*Service Principal secret
management.subscriptionIdstringYes*Azure subscription ID
management.resourceGroupstringYes*Resource group name

* Required if management is provided

Usage

typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "azure-openai/my-gpt4-deployment"  // Use your Azure deployment name (autocompleted in dev mode)
});

// Generate a response
const response = await agent.generate("Hello!");

// Stream a response
const stream = await agent.stream("Tell me a story");
for await (const chunk of stream) {
  console.log(chunk);
}

Check Azure OpenAI model availability for region-specific options.