OpenAPI Specified Tools (クラシック) で Foundry Agent Service を使用する方法

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 種類の認証がサポートされています。

使用サポート

前提 条件

1. クイックスタートの前提条件とセットアップ手順を完了していることを確認 します。
2. OpenAPI 仕様で次の要件を確認します。
   1. OpenAPI 仕様では必須ではありませんが、各関数には OpenAPI ツールを操作するための operationId が必要です。
   2. operationIdには、文字、-、および_のみを含める必要があります。 この要件を満たすように変更できます。 モデルが使用する関数を効率的に決定するのに役立つわかりやすい名前を使用します。

API キーを使用して認証する

API キー認証を使用すると、API キーやベアラー トークンなど、さまざまな方法で OpenAPI 仕様を認証できます。 各 OpenAPI 仕様では、1 つの API キー セキュリティ スキーマのみがサポートされます。 複数のセキュリティ スキーマが必要な場合は、複数の OpenAPI 仕様ツールを作成します。

1. OpenAPI 仕様のセキュリティ スキーマを更新します。 これには、 securitySchemes セクションと、 apiKey型の 1 つのスキームがあります。 例えば：

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   通常は、接続内のnameの名前に対応するkey フィールドのみを更新する必要があります。 セキュリティ スキームに複数のスキームが含まれている場合は、そのうちの 1 つだけを保持します。

2. security セクションを含むように OpenAPI 仕様を更新します。

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. この記事で後述するように、API キーが格納され、接続経由で渡されるため、API キーが必要な OpenAPI 仕様のパラメーターをすべて削除します。

4. API キーを格納する custom keys 接続を作成します。

   1. Microsoft Foundry ポータルに移動し、左側のナビゲーション ウィンドウから Management center を選択します。

      

   2. 左側のナビゲーション ウィンドウで、AI プロジェクトの下にある [ 接続済みリソース ] を選択します。

   3. [設定] ページで [ + 新しい接続 ] を選択します。

      メモ

      後で API キーを再生成する場合は、新しいキーで接続を更新する必要があります。

      

   4. 他のリソースの種類のカスタム キーを選択します。

      

   5. 次の情報を入力します

      • key: セキュリティ スキームの name フィールド。 この例では、次のようになります。 x-api-key

        "securitySchemes": {
            "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
        

      • value: YOUR_API_KEY

      • 接続名: YOUR_CONNECTION_NAME (次のサンプル コードでは、この接続名を使用します)。

      • アクセス: このプロジェクトのみを 選択するか、 すべてのプロジェクトと共有するかを選択できます。 次のサンプル コードで、接続文字列入力したプロジェクトがこの接続にアクセスできることを確認してください。

5. 接続を作成したら、SDK または REST API を使用して接続を使用します。 この記事の上部にあるタブを使用して、コード例を確認します。

マネージド ID による認証 (Microsoft Entra ID)

Microsoft Entra ID は、従業員が外部リソースへのアクセスに使用できるクラウドベースの ID およびアクセス管理サービスです。 Microsoft Entra IDを使用すると、API キーを使用せずに API を認証するときにセキュリティを強化できます。 マネージド ID 認証を設定すると、エージェントが使用する Foundry ツールによって認証が処理されます。

マネージド ID 認証を構成する場合は、 対象ユーザー の値を指定する必要があります。 対象ユーザーは、マネージド ID がアクセスできる API またはサービスを識別する OAuth2 リソース識別子 (スコープまたはアプリケーション ID URI とも呼ばれます) です。

一般的な対象ユーザーの値:

• Foundry Tools (以前のAzure AI サービスまたは Cognitive Services): https://cognitiveservices.azure.com/
• Azure Resource Manager API: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• Microsoft Entra IDに登録されているカスタム API: API のアプリ登録で見つかった Application ID URI を使用します

マネージド ID を使用して認証を設定するには:

1. Foundry リソースでシステム割り当てマネージド ID が有効になっていることを確認します。

   

2. OpenAPI 仕様を使用して接続するサービスのリソースを作成します。

3. リソースへの適切なアクセス権を割り当てます。

   1. リソースのAccess Controlを選択してください。

   2. [ 追加] を選択し、画面の上部にある ロールの割り当てを追加 します。

      Azure ポータルのロール割り当てセレクターを示すスクリーンショットです。

   3. 必要な適切なロールの割り当てを選択します。 通常、少なくとも 閲覧者 ロールが必要です。 次へを選択します。

   4. [ マネージド ID] を 選択し、[ メンバーの選択] を選択します。

   5. マネージド ID ドロップダウン メニューで Foundry Tools を検索し、エージェントの Foundry ツールを選択します。

   6. [完了] を選択します。

4. セットアップが完了したら、Foundry ポータル、SDK、または REST API を使用してツールを使用できます。 この記事の上部にあるタブを使用して、コード サンプルを確認します。