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.

Usage

The Azure OpenAI gateway isn't registered by default. Register it on your Mastra instance, and register the agents that use it on the same instance. Otherwise azure-openai/... model IDs fail with Could not find config for provider azure-openai.

Reference your Azure deployment name in the agent's model ID:

src/mastra/agents/my-agent.ts

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

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

Register the gateway and the agent:

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { AzureOpenAIGateway } from "@mastra/core/llm";
import { myAgent } from "./agents/my-agent";

export const mastra = new Mastra({
  gateways: {
    "azure-openai": new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
      deployments: ["my-gpt-5-4-deployment"],
    }),
  },
  agents: { myAgent },
});

Get the agent from the Mastra instance and call it:

const agent = mastra.getAgent("myAgent");

// 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);
}

See Configuration for other authentication and deployment discovery options.

Check Azure OpenAI model availability for region-specific options.

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-gpt-5-4-deployment
• azure-openai/production-gpt-5-4
• azure-openai/staging-gpt-5-4-mini

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. The common configuration modes are shown below.

Static Deployments

Provide deployment names from Azure Portal.

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

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

Dynamic Discovery

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

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

export const mastra = new Mastra({
  gateways: {
    "azure-openai": 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.

Microsoft Entra ID authentication

Use Microsoft Entra ID authentication when API keys are disabled for your Azure OpenAI resource. Pass any Azure SDK-compatible credential, such as DefaultAzureCredential from @azure/identity.

Install @azure/identity in your Mastra project if you use DefaultAzureCredential.

import { DefaultAzureCredential } from "@azure/identity";
import { Mastra } from "@mastra/core";
import { AzureOpenAIGateway } from "@mastra/core/llm";

export const mastra = new Mastra({
  gateways: {
    "azure-openai": new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      authentication: {
        type: "entraId",
        credential: new DefaultAzureCredential(),
      },
      deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"],
    }),
  },
});

The identity needs permission to call Azure OpenAI, such as the Cognitive Services OpenAI User role.

For a specific managed identity, pass ManagedIdentityCredential instead.

import { ManagedIdentityCredential } from "@azure/identity";

const credential = new ManagedIdentityCredential("client-id");

Manual Deployment Names

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

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

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

Azure Responses API

Azure OpenAI supports the Responses API through the v1 API path used by the AI SDK Azure provider. Set useResponsesAPI: true when your Azure resource and deployment support that route. The gateway then uses apiVersion: "v1" and useDeploymentBasedUrls: false by default.

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

export const mastra = new Mastra({
  gateways: {
    "azure-openai": new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
      useResponsesAPI: true,
      deployments: ["my-gpt-5-4-deployment"],
    }),
  },
});

Keep useResponsesAPI omitted or set it to false for the existing Azure chat completions route. That path keeps apiVersion: "2024-04-01-preview" and deployment-based URLs by default for compatibility.

You can still configure apiVersion and useDeploymentBasedUrls directly. For example, set useDeploymentBasedUrls: false to use the Azure v1 URL shape with the chat model constructor; the gateway defaults apiVersion to "v1" for that route. Passing apiVersion: "v1" by itself keeps the existing deployment-based URL default for compatibility.

Do not combine useResponsesAPI: true with useDeploymentBasedUrls: true; the gateway rejects that configuration because Responses API support uses the Azure v1 route.

Use apiVersion: "v1" for the GA v1 route. Microsoft currently exposes preview v1 features through feature-specific headers, such as "aoai-evals": "preview", or through preview/alpha API paths. The gateway still accepts apiVersion: "preview" with useDeploymentBasedUrls: false for Azure provider configurations that require the preview query value. Date-based API versions are only for the legacy deployment-based route, so the gateway rejects them when useResponsesAPI is true or useDeploymentBasedUrls is false.

The same API key and Microsoft Entra ID authentication modes work with the v1 route.

Azure Responses WebSocket transport

Azure OpenAI also supports WebSocket mode on the Responses API. Use it for agent or tool loops with many model-tool round trips. Keep the standard HTTP transport for single-shot requests and short conversations.

WebSocket transport requires useResponsesAPI: true, because Azure exposes it on the v1 Responses path. Then opt in per stream request with providerOptions.azure.transport: "websocket".

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

const agent = new Agent({
  id: "azure-ws-agent",
  name: "Azure WebSocket Agent",
  instructions: "Use tools when they are useful.",
  model: "azure-openai/my-gpt-5-4-deployment",
});

const stream = await agent.stream("Find and improve the slow function.", {
  providerOptions: {
    azure: {
      transport: "websocket",
      store: false,
      websocket: {
        closeOnFinish: false,
      },
    },
  },
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

stream.transport?.close();

Set closeOnFinish: false when you want to keep the socket open across follow-up turns. Azure keeps one response chain in connection-local memory, so continuing from the most recent previous_response_id can reduce continuation latency. The connection runs one response at a time and does not multiplex parallel runs.

Do not send overlapping follow-up requests with previous_response_id on the same WebSocket transport. Mastra rejects overlapping continuation requests because Azure only keeps one in-flight response per connection. Wait for the active stream to finish before continuing the response chain.

Strict structured output

The gateway sends structured output schemas and tool schemas without strict mode by default. Without strict mode the model can leave out keys, and Mastra then fails validation when a required key is missing.

Set providerOptions.azure.strictJsonSchema: true to have Azure enforce your schema:

import { z } from "zod";

const response = await agent.generate("Summarize the ticket.", {
  structuredOutput: {
    schema: z.object({
      summary: z.string(),
      priority: z.enum(["low", "medium", "high"]).optional(),
    }),
  },
  providerOptions: {
    azure: { strictJsonSchema: true },
  },
});

With strict mode on, Mastra prepares the schemas before sending them so Azure accepts them. Every key is listed as required, optional keys accept null and come back as undefined, and validation keywords such as uniqueItems, pattern, and minimum move into the field description. Mastra still validates the result against your original schema.

The setting covers the output schema and every tool in the request, because the gateway's AI SDK 5 Azure provider uses one flag for both. Azure strict mode can't express objects with free-form keys, such as z.record(), so keep strict mode off for agents whose output or tool schemas use them.

The azure key applies when useResponsesAPI is true. On the chat completions route, set providerOptions.openai.strictJsonSchema instead.

Configuration Reference

Option	Type	Required	Description
resourceName	string	Yes	Azure OpenAI resource name
apiKey	string	Yes*	API key from "Keys and Endpoint"
authentication	object	No	Microsoft Entra ID authentication
authentication.type	"entraId"	Yes*	Authentication mode
authentication.credential	TokenCredential	Yes*	Azure SDK-compatible credential for entraId authentication mode
authentication.scope	string	No	Token scope (default: https://cognitiveservices.azure.com/.default)
apiVersion	string	No	API version (default: 2024-04-01-preview, or v1 when useResponsesAPI is true or useDeploymentBasedUrls is false)
useResponsesAPI	boolean	No	Resolve deployments through the Azure OpenAI Responses API (default: false)
useDeploymentBasedUrls	boolean	No	Use Azure deployment-based URLs (default: true, or false when useResponsesAPI is true)
deployments	string[]	No	Deployment names for static mode
management	object	No	Management API credentials
management.tenantId	string	Yes*	Azure AD tenant ID
management.clientId	string	Yes*	Service Principal client ID
management.clientSecret	string	Yes*	Service Principal secret
management.subscriptionId	string	Yes*	Azure subscription ID
management.resourceGroup	string	Yes*	Resource group name

* Provide either apiKey or authentication.type: "entraId". Management fields are required if management is provided.