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