REST API ( OpenAI API を含む) を使用して、作成したエージェントを外部システムに接続し、エージェント内で使用できるデータにアクセスできます。 エージェントをREST APIに接続するには、Copilot Studio に次の 3 つのを提供します:
- OpenAPI 仕様で API の機能と使用可能なアクションを定義します
- 必要な認証の種類の詳細と、ユーザーが API に接続して外部システムにアクセスするための認証の詳細
- データを利用するために API を呼び出すタイミングを言語モデルが判断する際に役立つ説明
REST API は、Copilot Studio を通じて Copilot エージェントとカスタム エージェントに追加できます。
Copilot エージェントを使用すると、作成者はコネクタ、API、プロンプト、ナレッジ ソースなどの複数のデータ ソースを 1 つの エージェント に結合できます。 このエージェントを使用して、Microsoft 365 Copilot のようなマイクロソフト ブランドのエージェント エクスペリエンスを拡張できます。
カスタム エージェントは、コネクタ、API、プロンプト、ナレッジ ソースを含むスタンドアロンのエージェントです。 カスタム エージェントを Web サイトやその他のチャネルに統合することで、カスタム エージェントを直接使用できます。
注意
API アクションは OpenAPI v2 仕様から作成する必要があります。 これは、API 仕様を処理する Power Platform の動向によるものです。 v3 仕様が送信された場合、作成プロセス中に自動的に v2 仕様に変換されます。
前提条件
コネクタ アクションで Microsoft ブランドのエージェント エクスペリエンスを拡張するには、いくつかの前提条件が必要です。
すべてのエージェント エクスペリエンスのタイプでは、作成者レベルの資格情報と Copilot Studio ライセンスが必要です。
また、OpenAPI 仕様のコピー、必要な認証の種類に関する知識、認証の詳細情報も必要です。
エージェントに REST API アクションを追加する
REST API をエージェントに追加するには、いくつかの手順が必要です。 以下のセクションでは、そのプロセスを順を追って説明します。
REST API を追加するプロセスは、カスタム エージェントと Copilot エージェントの両方で同じです。
プロセスにはいくつかのステップがあります。
エージェントにアクションを追加する
エージェントの 概要 ページから開始します。
アクション セクションで、アクションの追加を選択します。 また、アクション タブに移動して、アクションの追加を選択することもできます。
アクション作成ウィザードが起動し、アクションの選択 ページが表示されます。
API の仕様、説明、ソリューションを提供する
ページの下部で、カスタムコネクター用 API の追加を選択します。
接続する REST API の OpenAPI 仕様ファイルをアップロードします。 仕様ファイルを REST APIのアップロードする 画面にドラッグ アンド ドロップするか、システムを参照して使用するファイルを見つけることができます。
ヒント
OpenAPI の仕様は、v2 形式の JSONフ ァイルである必要があります。 v3 仕様が送信された場合、作成プロセス中に自動的に v2 仕様に変換されます。
仕様をアップロードすると、画面が更新され、仕様ファイル名と詳細が表示されます。
次の手順では、ADO チケット管理システムである SunnyADO の具体例で手順を説明します。 この例では、ユーザーがエージェントを介してチケットを取得および更新できるようにすることを目的としています。
詳細を確認し、次へを選択します。
API に関する追加情報を入力できる API プラグインの詳細 ページが表示されます。
説明フィールドは、アップロードした API 仕様の説明に基づいて最初に入力されます。 エージェント オーケストレーションでは説明を使用して特定のアクションをいつ使用するかを決定するため、詳細な説明を指定します。 同義語を含む詳細を提供して、エージェントの選択プロセスに役立ててください。
たとえば、最初に提供される説明は、「チケットを管理する簡単なサービス」です。
より適切な説明は、「SunnyADO から既存のチケットを取得、検索、表示するためのシステム」です。 これにより、ユーザーはチケットを更新、変更、管理して、より多くのデータを提供してレコードを改善できます。
説明フィールドに改善された説明を入力します。
ソリューション配下のドロップダウンには、現在の環境内で利用可能なすべてのソリューションが一覧表示されます。 使用するソリューションを選択します。 ソリューションの詳細については、ソリューションの概念を参照してください。
優先するソリューションがある場合、または選択したコネクタがすでにソリューションに含まれている場合は、そのソリューションが自動的に選択されます。
ソリューションを選択するか、空白のままにしておくことができます。 ソリューションを空白のままにすると、アクション名と既定の発行元を使用してソリューションが作成されます。 アクションをソリューションに保存すると、環境間の移動が簡単になります。
注意
この場合、既定のソリューションまたは CDS の既定のソリューションがオプションとして表示されない場合は、管理を容易にするためにカスタム ソリューションを用意することをお勧めします。 詳細情報は、既定のソリューションとカスタム ソリューションを参照してください。
ソリューションを選択した状態で、次へ を選択して続行します。
AAD 認証の詳細を提供する
認証 ページが表示され、API に使用する認証のタイプを選択できます。
注意
現在使用可能なオプションは、なし、OAuth 2.0、API です。
一覧から認証方法を選択します。
認証方法の必須フィールドに入力します。 フィールドは、認証方法によって異なります。
- なし: 他のフィールドは必須ではありません。
-
API キー:
- パラメータ ラベル: API パラメータのテキスト ラベル。
- パラメータ名: API パラメータのテキスト名。
- パラメーター 場所: パラメーター が見つかる位置。
-
認証 2.0:
- クライアント ID: ターゲット サービスのクライアント GUID。
- クライアント シークレット – クライアントのシークレット値。 ユーザーが後で編集パネルを開いたときに、シークレットは表示されません。 ただし、さらに編集を行う場合は必要になるため、シークレットは保存しておいてください。
- 認証 URL: ソース システムの認可に使用される URL。
- トークン URL: トークンを取得できる URL。
- 更新 URL: 更新シナリオでリダイレクトされる URL。
- スコープ: Microsoft Entra アプリ の API に割り当てられたスコープ URL。
- エンドポイントにアクセスする Microsoft 365 組織: ソースへのアクセスを、作成者の組織またはすべての組織に制限します。
- エンドポイントを使用できるアプリ (クライアント): このデータへのアクセスに使用できるクライアント システムを定義する GUID。 アプリには、Microsoft 365、Power Automate、およびその他のオプションを含めることができます。
すべてのフィールドに入力したら、次へ を選択します。
プラグイン アクションの選択と設定 ページが表示され、API に対して有効にするアクションを選択できます。
API のアクションを選択する
有効にする API でサポートされているアクションを選択します。 一般に、REST API は、API 仕様で定義されているエンドポイントと HTTP メソッド (get、put、post、delete など) のさまざまな組み合わせを通じて、さまざまなアクションを提供します。 場合によっては、エージェント のユーザーが API で一般的に提供される すべてのアクション 実行できないようにしたいことがあります。 たとえば、API 仕様に更新と削除のアクションが含まれているが、エージェント のユーザのみがレコードを作成できるようにすることができます。
リストから構成するアクションを選択します。
プラグイン アクションの構成 ページが表示されます。
選択されたアクションを構成します。 全体的な API と同様に、 アクション名 および アクションの説明を指定するように求められます。 説明は、最初は API 仕様の説明から事前入力されています。 名前は一意である必要はありませんが、アクション自体を表している必要があります。 説明は、全体的な API の説明と同様に、クエリがこの特定のアクションと一致していることをより適切に識別できるように、言語モデルに詳細を提供するのに十分な具体性がある必要があります。
フィールドに入力したら、次へを選択します。
アクション パラメータのレビュー ページが表示されます。
このページには、可能な入力値と出力値の一部として提供される値が表示されます。 これらの値は変更できませんが、入力と出力の 説明 は更新できます。 このページのすべてのコンテンツは、アップロードされた API の仕様から直接取得されます。
説明に必要な値を入力します。 説明は、値の使用目的を定義します。 説明のいずれかが空白の場合は、先に進む前に完了する必要があります。 適切な説明がない場合は、名前を貼り付けることができます。
説明が完了したら、次へを選択します。
最初のアクションが構成され、プラグインの選択と構成ページの選択したアクション リストに表示されます。
この時点で、含めたい他のアクションを追加します。 エージェントでサポートするアクションの追加が完了したら、次へを選択します。
アクションの確認 ページが表示されます。 このページには、構成された REST API アクションの詳細が表示されます。
レビューをして公開する
更新を行う必要がある場合は、戻る を選択し、変更を加えることができます。 それ以外の場合は、次へを選択します。
プロセスの完了中にアクションが公開されていることを示す画面が表示されます。 公開が完了すると、通知されます。
公開が完了すると、アクションの選択 画面に戻ります。 ここでは、新しく構成した REST API を Copilot エージェント またはカスタム エージェント に追加して、コンポーネントの構成を完了できます。
以上で、REST API アクションを エージェント で使用できるようになりました。
チップ
アクションをより簡単に見つけるには、検索バーを使用してを探してください。