Azure OpenAI

Azure OpenAI fournit un accès aux modèles OpenAI de niveau entreprise via des déploiements dédiés, avec des garanties de sécurité, de conformité et de SLA.

Contrairement aux autres Providers qui utilisent des noms de modèle fixes, Azure emploie des noms de déploiement que vous configurez dans le portail Azure.

Utilisation

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

Consultez la disponibilité des modèles Azure OpenAI pour connaître les options propres à chaque région.

Fonctionnement des déploiements Azure

Les ID de modèle Azure suivent ce format : azure-openai/your-deployment-name

Le nom de déploiement est propre à votre compte Azure et choisi lors de la création d’un déploiement dans le portail Azure. Exemples courants :

• azure-openai/my-gpt-5-4-deployment
• azure-openai/production-gpt-5-4
• azure-openai/staging-gpt-5-4-mini

Configuration

Créez des déploiements dans Azure OpenAI Studio. Le nom de la ressource et la clé API se trouvent dans le portail Azure, sous « Keys and Endpoint ».

Configuration

Instanciez la passerelle et transmettez-la à Mastra. Les modes de configuration courants sont présentés ci-dessous.

Déploiements statiques

Indiquez les noms de déploiement du portail Azure.

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"],
    }),
  },
});

Découverte dynamique

Fournissez les identifiants de l’API Management. La passerelle interroge l’API Azure Management pour lister les déploiements.

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",
      },
    }),
  },
});

Le principal de service nécessite le rôle « Cognitive Services User ». Consultez la documentation Azure.

Authentification Microsoft Entra ID

Utilisez l’authentification Microsoft Entra ID lorsque les clés API sont désactivées pour votre ressource Azure OpenAI. Transmettez tout identifiant compatible avec le SDK Azure, tel que DefaultAzureCredential depuis @azure/identity.

Installez @azure/identity dans votre projet Mastra si vous utilisez 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"],
    }),
  },
});

L’identité doit disposer de l’autorisation d’appeler Azure OpenAI, par exemple via le rôle Cognitive Services OpenAI User.

Pour une identité managée spécifique, transmettez plutôt ManagedIdentityCredential.

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

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

Noms de déploiement manuels

Fournissez uniquement le nom de la ressource et la clé API. Indiquez les noms de déploiement lors de la création des Agents. Aucune autocomplétion IDE n’est disponible.

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!,
    }),
  },
});

API Azure Responses

Azure OpenAI prend en charge l’API Responses via le chemin d’API v1 utilisé par le Provider Azure d’AI SDK. Définissez useResponsesAPI: true lorsque votre ressource et votre déploiement Azure prennent en charge cette route. La passerelle utilise alors par défaut apiVersion: "v1" et useDeploymentBasedUrls: false.

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"],
    }),
  },
});

Omettez useResponsesAPI ou définissez-le sur false pour la route Azure existante des complétions de chat. Cette route conserve par défaut apiVersion: "2024-04-01-preview" et les URL basées sur les déploiements, pour assurer la compatibilité.

Vous pouvez toujours configurer directement apiVersion et useDeploymentBasedUrls. Par exemple, définissez useDeploymentBasedUrls: false pour utiliser le format d’URL Azure v1 avec le constructeur de modèle de chat ; la passerelle utilise par défaut apiVersion: "v1" pour cette route. Transmettre uniquement apiVersion: "v1" conserve l’URL par défaut basée sur les déploiements pour la compatibilité.

Ne combinez pas useResponsesAPI: true et useDeploymentBasedUrls: true : la passerelle rejette cette configuration car la prise en charge de l’API Responses utilise la route Azure v1.

Utilisez apiVersion: "v1" pour la route GA v1. Microsoft expose actuellement les fonctionnalités d’aperçu de v1 via des en-têtes propres aux fonctionnalités, tels que "aoai-evals": "preview", ou via des chemins d’API preview/alpha. La passerelle accepte toujours apiVersion: "preview" avec useDeploymentBasedUrls: false pour les configurations du Provider Azure qui requièrent la valeur de requête preview. Les versions d’API fondées sur une date ne s’appliquent qu’à l’ancienne route basée sur les déploiements ; la passerelle les rejette donc lorsque useResponsesAPI est à true ou useDeploymentBasedUrls à false.

Les mêmes modes d’authentification par clé API et Microsoft Entra ID fonctionnent avec la route v1.

Transport WebSocket Azure Responses

Azure OpenAI prend également en charge le mode WebSocket sur l’API Responses. Utilisez-le pour les boucles d’Agent ou de Tool comportant de nombreux allers-retours entre modèle et Tool. Conservez le transport HTTP standard pour les requêtes uniques et les conversations courtes.

Le transport WebSocket requiert useResponsesAPI: true, car Azure l’expose sur le chemin Responses v1. Activez-le ensuite pour chaque requête de stream avec 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();

Définissez closeOnFinish: false si vous souhaitez garder le socket ouvert entre des tours de suivi. Azure conserve une chaîne de réponses dans la mémoire locale de la connexion ; poursuivre à partir du previous_response_id le plus récent peut donc réduire la latence. La connexion exécute une réponse à la fois et ne multiplexe pas les exécutions parallèles.

N’envoyez pas de requêtes de suivi qui se chevauchent avec previous_response_id sur le même transport WebSocket. Mastra rejette les requêtes de continuation concurrentes, car Azure ne conserve qu’une réponse en cours par connexion. Attendez la fin du stream actif avant de poursuivre la chaîne de réponses.

Référence de configuration

Option	Type	Obligatoire	Description
resourceName	string	Oui	Nom de la ressource Azure OpenAI
apiKey	string	Oui*	Clé API provenant de « Keys and Endpoint »
authentication	object	Non	Authentification Microsoft Entra ID
authentication.type	"entraId"	Oui*	Mode d’authentification
authentication.credential	TokenCredential	Oui*	Identifiant compatible avec le SDK Azure pour le mode d’authentification entraId
authentication.scope	string	Non	Portée du jeton (par défaut : https://cognitiveservices.azure.com/.default)
apiVersion	string	Non	Version de l’API (par défaut : 2024-04-01-preview, ou v1 lorsque useResponsesAPI vaut true ou useDeploymentBasedUrls vaut false)
useResponsesAPI	boolean	Non	Résout les déploiements via l’API Responses d’Azure OpenAI (par défaut : false)
useDeploymentBasedUrls	boolean	Non	Utilise les URL Azure basées sur les déploiements (par défaut : true, ou false lorsque useResponsesAPI vaut true)
deployments	string[]	Non	Noms des déploiements pour le mode statique
management	object	Non	Identifiants de l’API de gestion
management.tenantId	string	Oui*	ID du locataire Azure AD
management.clientId	string	Oui*	ID client du principal de service
management.clientSecret	string	Oui*	Secret du principal de service
management.subscriptionId	string	Oui*	ID de l’abonnement Azure
management.resourceGroup	string	Oui*	Nom du groupe de ressources

* Fournissez soit apiKey, soit authentication.type: "entraId". Les champs de gestion sont obligatoires lorsque management est fourni.