OpenAPI 3.0 の指定ツールを使用して Azure AI エージェントを外部 API に接続できるようになりました。これにより、さまざまなアプリケーションとのスケーラブルな相互運用性を実現できます。 セキュリティを強化するために、カスタム ツールでマネージド ID (Microsoft Entra ID) を使用してアクセスと接続を認証できるようにします。これは、既存のインフラストラクチャや Web サービスとの統合に最適です。
OpenAPI Specified ツールにより、エージェントの機能と効率を向上させる標準化された自動化されたスケーラブルな API 統合が提供され、関数呼び出しエクスペリエンスを向上させます。
OpenAPI 仕様 では、HTTP API を記述するための正式な標準が提供されています。 これにより、API のしくみ、一連の API の連携方法、クライアント コードの生成、テストの作成、設計標準の適用などを理解できます。 現在、OpenAPI 3.0 で指定されたツールでは、 anonymous
、 API key
、 managed identity
の 3 種類の認証がサポートされています。
利用サポート
Azure AI Foundry のサポート | Python SDK | C# SDK | REST API | 基本エージェントのセットアップ | 標準エージェントのセットアップ |
---|---|---|---|---|---|
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
[前提条件]
クイック スタートの前提条件とセットアップ手順が完了していることを確認してください。
OpenAPI 仕様で次の要件を確認します:
- OpenAPI 仕様では必須ではありませんが、各関数を OpenAPI ツールで使用するには、
operationId
が必要です。 operationId
には、文字、-
、_
のみを含める必要があります。 要件を満たすように変更できます。 モデルが使用する関数を効率的に決定できるように、わかりやすい名前を使用することをお勧めします。
- OpenAPI 仕様では必須ではありませんが、各関数を OpenAPI ツールで使用するには、
API キーを使用した認証
API キー認証を使用すると、API キーやベアラー トークンなどのさまざまな方法を使用して OpenAPI 仕様を認証できます。 OpenAPI 仕様ごとにサポートされている API キー セキュリティ スキーマは 1 つだけです。複数のセキュリティ スキーマが必要な場合は、複数の OpenAPI 仕様ツールを作成します。
OpenAPI 仕様のセキュリティ スキーマを更新します。
securitySchemes
セクションと、apiKey
型の 1 つのスキームがあります。 例えば次が挙げられます。"securitySchemes": { "apiKeyHeader": { "type": "apiKey", "name": "x-api-key", "in": "header" } }
通常は、接続内の
name
の名前に対応するkey
フィールドのみを更新する必要があります。 セキュリティ スキームに複数のスキームが含まれている場合は、そのうちの 1 つだけを保持することをお勧めします。security
セクションを含むように OpenAPI 仕様を更新します。"security": [ { "apiKeyHeader": [] } ]
この記事の後半で説明するように、API キーが格納され、接続を介して渡されるため、API キーが必要な OpenAPI 仕様のパラメーターを削除します。
API キーを格納する
custom keys
接続を作成します。Azure AI Foundry ポータルに移動し、[AI プロジェクト]を選択します。 [接続されたリソース] をクリックします。
[設定] ページで、[+ 新しい接続] を選択します。
注
後で API キーを生成し直す場合は、その新しいキーで接続を更新する必要があります。
[他のリソースの種類] で [カスタム キー] を選択します。
次の情報を入力します
- key: セキュリティ スキームの
name
フィールド。 この例では、x-api-key
となります"securitySchemes": { "apiKeyHeader": { "type": "apiKey", "name": "x-api-key", "in": "header" } }
- 値: YOUR_API_KEY
- 接続名: YOUR_CONNECTION_NAME (以下のサンプル コードでは、この接続名を使用します)
- アクセス: [このプロジェクトのみ] を選択することも、[すべてのプロジェクトと共有] を選択することもできます。 以下のサンプル コードで、接続文字列を入力したプロジェクトでこの接続へのアクセスが可能であることを確認してください。
- key: セキュリティ スキームの
接続を作成したら、SDK または REST API を使用して接続を使用できます。 この記事の上部にあるタブを使用して、コード例を確認します。
マネージド ID を使用した認証 (Microsoft Entra ID)
Microsoft Entra ID は、従業員が外部リソースへのアクセスに使用できるクラウドベースの ID およびアクセス管理サービスです。 Microsoft Entra ID を使用すると、API キーを渡すことなく、追加のセキュリティで API を認証できます。 マネージド ID 認証を設定すると、エージェントが使用している Azure AI サービスを介して認証されます。
マネージド ID を使用して認証を設定するには:
system assigned managed identity
が有効になっているエージェントの Azure AI サービスを有効にします。OpenAPI 仕様を使用して接続するサービスのリソースを作成します。
リソースへの適切なアクセス権を割り当てます。
セットアップが完了したら、Foundry Portal、SDK、または REST API からツールを使用して続行できます。 この記事の上部にあるタブを使用して、コード サンプルを確認します。