# ![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-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](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-gpt4-deployment`
- `azure-openai/production-gpt-35-turbo`
- `azure-openai/staging-gpt-4o`

## 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. 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](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: [
    new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      authentication: {
        type: "entraId",
        credential: new DefaultAzureCredential(),
      },
      deployments: ["gpt-4-prod", "gpt-35-turbo-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: [
    new AzureOpenAIGateway({
      resourceName: "my-openai-resource",
      apiKey: process.env.AZURE_API_KEY!,
    }),
  ],
});
```

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