> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # ![Azure OpenAI ロゴ](https://models.dev/logos/azure.svg)Azure OpenAI Azure OpenAI は、セキュリティ、コンプライアンス、SLA が保証された専用 deployment を通じて、OpenAI モデルへのエンタープライズ向けアクセスを提供します。 固定されたモデル名を使う他の Provider と異なり、Azure では Azure Portal で設定した **deployment 名**を使用します。 ## 使用方法 ```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); } ``` リージョンごとの選択肢は、[Azure OpenAI のモデル提供状況](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)を確認してください。 ## 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](https://oai.azure.com/) で deployment を作成します。resource 名と API key は Azure Portal の「Keys and Endpoint」にあります。 ## 設定 Gateway をインスタンス化して Mastra に渡します。一般的な設定方法を以下に示します。 ### 静的 deployment Azure Portal の deployment 名を指定します。 ```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"], }), }, }); ``` ### 動的検出 Management API の認証情報を指定します。Gateway が Azure Management API に問い合わせて deployment の一覧を取得します。 ```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", }, }), }, }); ``` Service Principal には「Cognitive Services User」role が必要です。[Azure のドキュメント](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal)を参照してください。 ### Microsoft Entra ID 認証 Azure OpenAI resource で API key が無効な場合は、Microsoft Entra ID 認証を使用します。`@azure/identity` の `DefaultAzureCredential` など、Azure SDK 互換の credential を渡します。 `DefaultAzureCredential` を使用する場合は、Mastra project に `@azure/identity` をインストールします。 ```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"], }), }, }); ``` identity には、`Cognitive Services OpenAI User` role など Azure OpenAI を呼び出す権限が必要です。 特定の managed identity を使用する場合は、代わりに `ManagedIdentityCredential` を渡します。 ```typescript import { ManagedIdentityCredential } from "@azure/identity"; const credential = new ManagedIdentityCredential("client-id"); ``` ### deployment 名の手動指定 resource 名と API key だけを指定します。Agent の作成時に deployment 名を指定します。IDE の自動補完は利用できません。 ```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 は、AI SDK Azure Provider が使用する `v1` API path で Responses API に対応しています。Azure resource と deployment がこの route に対応している場合は、`useResponsesAPI: true` を設定します。Gateway はデフォルトで `apiVersion: "v1"` と `useDeploymentBasedUrls: false` を使用します。 ```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"], }), }, }); ``` 既存の 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 OpenAI は Responses API の WebSocket mode にも対応しています。モデルと Tool の往復が多い Agent や Tool loop で使用します。単発のリクエストや短い会話では、標準の HTTP transport を使用してください。 Azure は WebSocket transport を `v1` Responses path で提供するため、`useResponsesAPI: true` が必要です。そのうえで、stream リクエストごとに `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(); ``` 後続 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 が完了するまで待ってください。 ## 設定リファレンス | option | type | 必須 | 説明 | | --------------------------- | ----------------- | ---- | -------------------------------------------------------------------------------------------------------------------- | | `resourceName` | `string` | はい | Azure OpenAI resource 名 | | `apiKey` | `string` | はい\* | 「Keys and Endpoint」の API key | | `authentication` | `object` | いいえ | Microsoft Entra ID 認証 | | `authentication.type` | `"entraId"` | はい\* | 認証 mode | | `authentication.credential` | `TokenCredential` | はい\* | `entraId` 認証 mode 用の Azure SDK 互換 credential | | `authentication.scope` | `string` | いいえ | token scope（デフォルト: `https://cognitiveservices.azure.com/.default`） | | `apiVersion` | `string` | いいえ | API version（デフォルト: `2024-04-01-preview`。`useResponsesAPI` が `true` または `useDeploymentBasedUrls` が `false` の場合は `v1`） | | `useResponsesAPI` | `boolean` | いいえ | Azure OpenAI Responses API 経由で deployment を解決（デフォルト: `false`） | | `useDeploymentBasedUrls` | `boolean` | いいえ | Azure の deployment ベース URL を使用（デフォルト: `true`。`useResponsesAPI` が `true` の場合は `false`） | | `deployments` | `string[]` | いいえ | 静的 mode の deployment 名 | | `management` | `object` | いいえ | Management API の認証情報 | | `management.tenantId` | `string` | はい\* | Azure AD tenant ID | | `management.clientId` | `string` | はい\* | Service Principal client ID | | `management.clientSecret` | `string` | はい\* | Service Principal secret | | `management.subscriptionId` | `string` | はい\* | Azure subscription ID | | `management.resourceGroup` | `string` | はい\* | resource group 名 | \* `apiKey` または `authentication.type: "entraId"` のいずれかを指定します。`management` を指定する場合は Management フィールドが必須です。