OpenAPI 指定ツールで Azure AI Foundry Agent Service を使用する方法

2025-06-17

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 仕様で次の要件を確認します:
1. OpenAPI 仕様では必須ではありませんが、各関数を OpenAPI ツールで使用するには、 operationId が必要です。
2. operationId には、文字、-、_ のみを含める必要があります。要件を満たすように変更できます。モデルが使用する関数を効率的に決定できるように、わかりやすい名前を使用することをお勧めします。

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 接続を作成します。
1. Azure AI Foundry ポータルに移動し、[AI プロジェクト]を選択します。 [接続されたリソース] をクリックします。
2. [設定] ページで、[+ 新しい接続] を選択します。
  
  注
  
  後で API キーを生成し直す場合は、その新しいキーで接続を更新する必要があります。
3. [他のリソースの種類] で [カスタムキー] を選択します。
4. 次の情報を入力します
  - key: セキュリティスキームの name フィールド。この例では、x-api-key となります
```
       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
```
  - 値: YOUR_API_KEY
  - 接続名: YOUR_CONNECTION_NAME (以下のサンプルコードでは、この接続名を使用します)
  - アクセス: [このプロジェクトのみ] を選択することも、[すべてのプロジェクトと共有] を選択することもできます。以下のサンプルコードで、接続文字列を入力したプロジェクトでこの接続へのアクセスが可能であることを確認してください。
接続を作成したら、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 仕様を使用して接続するサービスのリソースを作成します。
リソースへの適切なアクセス権を割り当てます。
1. リソースの [アクセス制御 ] をクリックする
2. [ 追加] をクリックし、画面の上部にある ロールの割り当てを追加 します。
3. 必要な適切なロールの割り当てを選択します。通常は、少なくとも 閲覧者 ロールが必要です。続けて、 [次へ] をクリックします。
4. [ マネージド ID] を 選択し、[ メンバーの選択] をクリックします。
5. マネージド ID ドロップダウンメニューで、 Azure AI サービス を検索し、エージェントの AI サービスを選択します。
6. [完了] をクリックします。
セットアップが完了したら、Foundry Portal、SDK、または REST API からツールを使用して続行できます。この記事の上部にあるタブを使用して、コードサンプルを確認します。

次の方法で共有

OpenAPI 指定ツールで Azure AI Foundry Agent Service を使用する方法

利用サポート

[前提条件]

API キーを使用した認証

マネージド ID を使用した認証 (Microsoft Entra ID)

フィードバック

その他のリソース