> Discover all available pages from the documentation index: https://mastra.ai/llms.txt # ![Azure OpenAI logo](https://models.dev/logos/azure.svg)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 ```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-gpt-5-4-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](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) 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](https://oai.azure.com/). 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. ```typescript 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. ```typescript 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](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). ### 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`. ```typescript 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. ```typescript 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. ```typescript 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. ```typescript 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"`. ```typescript 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. ## 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.