メインコンテンツへ移動

Azure OpenAI ロゴAzure OpenAI

Azure OpenAI は、セキュリティ、コンプライアンス、SLA が保証された専用 deployment を通じて、OpenAI モデルへのエンタープライズ向けアクセスを提供します。

固定されたモデル名を使う他の Provider と異なり、Azure では Azure Portal で設定した deployment 名を使用します。

使用方法
使用方法への直接リンク

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

リージョンごとの選択肢は、Azure OpenAI のモデル提供状況を確認してください。

Azure deployment の仕組み
Azure deployment の仕組みへの直接リンク

Azure のモデル ID は azure-openai/your-deployment-name 形式です。

deployment 名は Azure account ごとに固有で、Azure Portal で deployment を作成するときに指定します。一般的な例:

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

セットアップ
セットアップへの直接リンク

Azure OpenAI Studio で deployment を作成します。resource 名と API key は Azure Portal の「Keys and Endpoint」にあります。

設定
設定への直接リンク

Gateway をインスタンス化して Mastra に渡します。一般的な設定方法を以下に示します。

静的 deployment
静的 deploymentへの直接リンク

Azure Portal の deployment 名を指定します。

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

動的検出
動的検出への直接リンク

Management API の認証情報を指定します。Gateway が Azure Management API に問い合わせて deployment の一覧を取得します。

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

Service Principal には「Cognitive Services User」role が必要です。Azure のドキュメントを参照してください。

Microsoft Entra ID 認証
Microsoft Entra ID 認証への直接リンク

Azure OpenAI resource で API key が無効な場合は、Microsoft Entra ID 認証を使用します。@azure/identity の DefaultAzureCredential など、Azure SDK 互換の credential を渡します。

DefaultAzureCredential を使用する場合は、Mastra project に @azure/identity をインストールします。

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

identity には、Cognitive Services OpenAI User role など Azure OpenAI を呼び出す権限が必要です。

特定の managed identity を使用する場合は、代わりに ManagedIdentityCredential を渡します。

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

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

deployment 名の手動指定
deployment 名の手動指定への直接リンク

resource 名と API key だけを指定します。Agent の作成時に deployment 名を指定します。IDE の自動補完は利用できません。

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 Responses APIへの直接リンク

Azure OpenAI は、AI SDK Azure Provider が使用する v1 API path で Responses API に対応しています。Azure resource と deployment がこの route に対応している場合は、useResponsesAPI: true を設定します。Gateway はデフォルトで apiVersion: "v1" と 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"],
    }),
  },
});

既存の Azure chat completions route を使う場合は、useResponsesAPI を省略するか false に設定します。互換性のため、この path ではデフォルトで apiVersion: "2024-04-01-preview" と deployment ベースの URL が維持されます。

apiVersion と useDeploymentBasedUrls は直接設定することもできます。たとえば、chat model constructor で Azure v1 URL 形式を使用するには useDeploymentBasedUrls: false を設定します。この route では Gateway の apiVersion がデフォルトで "v1" になります。apiVersion: "v1" だけを渡した場合は、互換性のため既存の deployment ベース URL がデフォルトのままです。

useResponsesAPI: true と useDeploymentBasedUrls: true は併用しないでください。Responses API は Azure v1 route を使用するため、Gateway はこの設定を拒否します。

GA の v1 route には apiVersion: "v1" を使用します。Microsoft は現在、"aoai-evals": "preview" など機能固有の header、または preview/alpha API path で preview v1 機能を提供しています。preview query 値が必要な Azure Provider 設定では、Gateway は useDeploymentBasedUrls: false と apiVersion: "preview" の組み合わせも受け付けます。日付形式の API version は従来の deployment ベース route 専用なので、useResponsesAPI が true または useDeploymentBasedUrls が false の場合、Gateway は拒否します。

v1 route でも、同じ API key と Microsoft Entra ID の認証方式を使用できます。

Azure Responses WebSocket transport
Azure Responses WebSocket transportへの直接リンク

Azure OpenAI は Responses API の WebSocket mode にも対応しています。モデルと Tool の往復が多い Agent や Tool loop で使用します。単発のリクエストや短い会話では、標準の HTTP transport を使用してください。

Azure は WebSocket transport を v1 Responses path で提供するため、useResponsesAPI: true が必要です。そのうえで、stream リクエストごとに 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();

後続 turn の間も socket を開いたままにする場合は、closeOnFinish: false を設定します。Azure は接続ローカルの Memory に 1 つの response chain を保持するため、最新の previous_response_id から続行すると継続時のレイテンシーを抑えられます。1 つの接続で同時に実行される response は 1 件だけで、並列実行は multiplex されません。

同じ WebSocket transport で previous_response_id を指定した後続リクエストを重複して送信しないでください。Azure が接続ごとに保持する処理中のレスポンスは 1 件だけなので、Mastra は重複した継続リクエストを拒否します。レスポンス chain を続ける前に、実行中の stream が完了するまで待ってください。

設定リファレンス
設定リファレンスへの直接リンク

optiontype必須説明
resourceNamestringはいAzure OpenAI resource 名
apiKeystringはい*「Keys and Endpoint」の API key
authenticationobjectいいえMicrosoft Entra ID 認証
authentication.type"entraId"はい*認証 mode
authentication.credentialTokenCredentialはい*entraId 認証 mode 用の Azure SDK 互換 credential
authentication.scopestringいいえtoken scope（デフォルト: https://cognitiveservices.azure.com/.default）
apiVersionstringいいえAPI version（デフォルト: 2024-04-01-preview。useResponsesAPI が true または useDeploymentBasedUrls が false の場合は v1）
useResponsesAPIbooleanいいえAzure OpenAI Responses API 経由で deployment を解決（デフォルト: false）
useDeploymentBasedUrlsbooleanいいえAzure の deployment ベース URL を使用（デフォルト: true。useResponsesAPI が true の場合は false）
deploymentsstring[]いいえ静的 mode の deployment 名
managementobjectいいえManagement API の認証情報
management.tenantIdstringはい*Azure AD tenant ID
management.clientIdstringはい*Service Principal client ID
management.clientSecretstringはい*Service Principal secret
management.subscriptionIdstringはい*Azure subscription ID
management.resourceGroupstringはい*resource group 名

* apiKey または authentication.type: "entraId" のいずれかを指定します。management を指定する場合は Management フィールドが必須です。

On this page