REST API からツールを使用してエージェントを拡張する (プレビュー)

[この記事はプレリリース ドキュメントであり、変更されることがあります。]

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 サイトやその他のチャネルに統合することで、カスタム エージェントを直接使用できます。

前提条件

コネクタ アクションで Microsoft ブランドのエージェント エクスペリエンスを拡張するには、いくつかの前提条件が必要です。

すべてのエージェント エクスペリエンスのタイプでは、作成者レベルの資格情報と Copilot Studio ライセンスが必要です。

また、OpenAPI 仕様のコピー、必要な認証の種類に関する知識、認証の詳細情報も必要です。

エージェントに REST API アクションを追加する

REST API をエージェントに追加するには、いくつかの手順が必要です。 以下のセクションでは、そのプロセスを順を追って説明します。

REST API を追加するプロセスは、カスタム エージェントと Copilot エージェントの両方で同じです。

プロセスにはいくつかのステップがあります。

エージェントにアクションを追加する

1. エージェントの 概要 ページから開始します。

   

2. [ ツール ] セクションで、[ ツールの追加] を選択します。 [ ツール ] タブに移動し、[ツールの 追加] を選択することもできます。

   [ ツールの追加] ページが表示されます。

3. [新しいツール>REST API] を選択します。

API の仕様、説明、ソリューションを提供する

1. 接続する REST API の OpenAPI 仕様ファイルをアップロードします。 仕様ファイルを REST APIのアップロードする 画面にドラッグ アンド ドロップするか、システムを参照して使用するファイルを見つけることができます。

   

   注意

   OpenAPI の仕様は、v2 形式の JSONフ ァイルである必要があります。 v3 仕様が送信された場合、作成プロセス中に自動的に v2 仕様に変換されます。

   仕様をアップロードすると、画面が更新され、仕様ファイル名と詳細が表示されます。

   

   次の手順では、ADO チケット管理システムである SunnyADO の具体例で手順を説明します。 この例では、ユーザーがエージェントを介してチケットを取得および更新できるようにすることを目的としています。

2. 詳細を確認し、次へを選択します。

   API に関する追加情報を入力できる API プラグインの詳細 ページが表示されます。

   

   説明フィールドは、アップロードした API 仕様の説明に基づいて最初に入力されます。 詳細な説明を提供します。エージェントオーケストレーションがその説明を用いて、特定のツールを使用するタイミングを決定するためです。 同義語を含む詳細を提供して、エージェントの選択プロセスに役立ててください。

   たとえば、最初に提供される説明は、「チケットを管理する簡単なサービス」です。

   より適切な説明は、「SunnyADO から既存のチケットを取得、検索、表示するためのシステム」です。 これにより、ユーザーはチケットを更新、変更、管理して、より多くのデータを提供してレコードを改善できます。

3. 説明フィールドに改善された説明を入力します。

4. ソリューション配下のドロップダウンには、現在の環境内で利用可能なすべてのソリューションが一覧表示されます。 使用するソリューションを選択します。 ソリューションの詳細については、ソリューションの概念を参照してください。

   

   優先するソリューションがある場合、または選択したコネクタがすでにソリューションに含まれている場合は、そのソリューションが自動的に選択されます。

   ソリューションを選択するか、空白のままにしておくことができます。 ソリューションを空白のままにすると、アクション名と既定の発行元を使用してソリューションが作成されます。 アクションをソリューションに保存すると、環境間の移動が簡単になります。

   注意

   この場合、既定のソリューションまたは CDS の既定のソリューションがオプションとして表示されない場合は、管理を容易にするためにカスタム ソリューションを用意することをお勧めします。 詳細情報は、既定のソリューションとカスタム ソリューションを参照してください。

5. ソリューションを選択した状態で、次へ を選択して続行します。

AAD 認証の詳細を提供する

認証 ページが表示され、API に使用する認証のタイプを選択できます。

1. 一覧から認証方法を選択します。

2. 認証方法の必須フィールドに入力します。 フィールドは、認証方法によって異なります。

   • なし: 他のフィールドは必須ではありません。
   • API キー:
     • パラメータ ラベル: API パラメータのテキスト ラベル。
     • パラメータ名: API パラメータのテキスト名。
     • パラメーター 場所: パラメーター が見つかる位置。
   • 認証 2.0:
     • クライアント ID: ターゲット サービスのクライアント GUID。
     • クライアント シークレット – クライアントのシークレット値。 ユーザーが後で編集パネルを開いたときに、シークレットは表示されません。 ただし、さらに編集を行う場合は必要になるため、シークレットは保存しておいてください。
     • 認証 URL: ソース システムの認可に使用される URL。
     • トークン URL: トークンを取得できる URL。
     • 更新 URL: 更新シナリオでリダイレクトされる URL。
     • スコープ: Microsoft Entra アプリ の API に割り当てられたスコープ URL。
     • エンドポイントにアクセスする Microsoft 365 組織: ソースへのアクセスを、作成者の組織またはすべての組織に制限します。
     • エンドポイントを使用できるアプリ (クライアント): このデータへのアクセスに使用できるクライアント システムを定義する GUID。 アプリには、Microsoft 365、Power Automate、およびその他のオプションを含めることができます。

3. すべてのフィールドに入力したら、次へ を選択します。

   [ Select and configure your plugin tool]\(選択して構成 \) ツール ページが表示されます。このページでは、API に対して有効にするツールを選択できます。

   

API のツールを選択する

有効にする API でサポートされているツールを選択します。 一般に、REST API は、API 仕様で定義されているエンドポイントと HTTP メソッド (get、put、post、delete など) のさまざまな組み合わせを通じて、さまざまなツールを提供します。 場合によっては、エージェント のユーザーが API で一般的に提供される すべてのアクション 実行できないようにしたいことがあります。 たとえば、API 仕様に更新と削除のアクションが含まれているが、エージェント のユーザのみがレコードを作成できるようにすることができます。

1. 構成するツールを一覧から選択します。

   プラグイン アクションの構成 ページが表示されます。

   

2. 選択されたアクションを構成します。 API 全体と同様に、 ツール名とツール の 説明を指定するように求められます。 説明は、最初は API 仕様の説明から事前入力されています。 名前は一意である必要はありませんが、ツール自体を表す必要があります。 API の全体的な説明と同様に、クエリがこの特定のツールと一致していることをより適切に識別するために、言語モデルに詳細を提供するのに十分な具体的な記述が必要です。

3. フィールドに入力したら、次へを選択します。

   [ツールのパラメーターの確認] ページが表示されます。

   

   このページには、可能な入力値と出力値の一部として提供される値が表示されます。 これらの値は変更できませんが、入力と出力の 説明 は更新できます。 このページのすべてのコンテンツは、アップロードされた API の仕様から直接取得されます。

4. 説明に必要な値を入力します。 説明は、値の使用目的を定義します。 説明のいずれかが空白の場合は、先に進む前に完了する必要があります。 適切な説明がない場合は、名前を貼り付けることができます。

5. 説明が完了したら、次へを選択します。

   1 つ目のツールが構成され、[プラグイン ツールの選択と構成] ページの [選択したツール] の一覧に表示されます。

   

6. この時点で、含めたい他のアクションを追加します。 エージェントでサポートするツールの追加が完了したら、[ 次へ] を選択します。

   [ ツールの確認] ページが表示されます。 このページには、構成された REST API ツールの詳細が表示されます。

   

レビューをして公開する

1. 更新を行う必要がある場合は、戻る を選択し、変更を加えることができます。 それ以外の場合は、次へを選択します。

   プロセスの完了中にツールが公開されていることを示す画面が表示されます。 公開が完了すると、通知されます。

2. 発行が完了すると、[ ツールの選択 ] 画面に戻ります。 ここでは、新しく構成した REST API を Copilot エージェント またはカスタム エージェント に追加して、コンポーネントの構成を完了できます。

   

REST API ツールをエージェントで使用できるようになりました。