API プラグインを使用すると、Microsoft 365 Copilotの宣言型エージェントは、OpenAPI の説明または MCP サーバーを持つ REST API と対話できます。 API プラグインを使用すると、ユーザーは宣言型エージェントに対して、REST API または MCP サーバーに対して情報の照会を行うだけでなく、データとオブジェクトを作成、更新、削除するように求めることができます。 REST API または MCP サーバーでできることは、自然言語プロンプトを使用してアクセスできます。
注:
REST API または MCP サーバーの呼び出しに加えて、プラグインがローカル ライブラリ内の API を呼び出すプレビュー機能もあります。 この機能を試すのをお勧めしますが、運用環境のプラグインでは使用しないでください。 詳細については、「Office JavaScript ライブラリを使用したMicrosoft 365 Copilot用 API プラグインの構築」を参照してください。
重要
API プラグインは、 宣言型エージェント内のアクションとしてのみサポートされます。 Microsoft 365 Copilotでは有効になっていません。
API プラグインは、OpenAPI 記述ドキュメント (REST API を使用する場合) と、Copilot が API の機能を学習するために使用するプラグイン マニフェストを提供します。 その後、Copilot は、インストールおよび有効化されたプラグインの API が、特定のプロンプトに応答するのに適しているタイミングを決定できます。 API プラグインに必要なマニフェスト ファイルの詳細については、Microsoft 365 Copilotの API プラグイン マニフェスト スキーマに関するページを参照してください。
たとえば、予算の照会と作成、経費の請求、または既存の予算への資金の追加を可能にする予算 API を考えてみましょう。 "Contoso 旅行予算に残っている量" というプロンプトは、予算プラグインをトリガーして、次の API 呼び出しを行う可能性があります。
GET /budgets?name=contoso%20travel
Copilot は API 呼び出しからの応答を使用してその応答を生成します。"Contoso の旅行予算には現在、利用可能な資金が 5,000 ドルです。 あなたが特定のカテゴリに資金を割り当てるか、経費を追跡する必要がある場合は、私もあなたに支援することができます。 私が助けることができる方法を教えてください!
"Megan の航空券の Contoso 旅行予算に $500 を請求する" というプロンプトは、次の API 呼び出しに変換できます。
POST /budgets/charge
Content-Type: application/json
{
"budgetName": "Contoso travel",
"amount": 500,
"description": "Megan's airline ticket"
}
Copilot は、返された情報を使用してユーザーに応答します。"Megan の航空券に対する 500 ドルの料金が正常に処理されました。 Contoso の旅行予算には、利用可能な資金が 4,500 ドル残っています。 これ以上取引を行う必要がある場合や、予算に関するさらなる支援が必要な場合は、お知らせください。
API プラグインのしくみ
ユーザーはエージェントに 「4 番目のコーヒー ロビーの改装予算にいくら残っているか」と尋ねます。
エージェントは、予算に関連するプラグインを、予算の詳細を取得するための関数
GetBudgetを持つ使用可能なプラグインから識別します。 ユーザーの質問の一部を関数のパラメーター (budgetName="") にマップします。エージェントは 、プラグイン に
Fourth Coffee lobby renovationを送信することをユーザーに求めます。ユーザーは、データをプラグインと 1 回共有することを許可するか、この関数のデータの共有を常に許可することを選択します。
プラグインの API で 認証が必要な場合、プラグインはトークン ストアにトークンまたは API キーを要求します。
トークン ストアは、トークンまたはキーを返します。 必要に応じて、トークン ストアによって、ユーザーにサインインを求めるメッセージがエージェントに表示されます。
エージェントは、Microsoft 365 の外部でホストされているプラグインの API に要求を送信します。
GET /budgets?budgetName=Fourth+Coffee+lobby+renovationAPI は、OpenAPI 仕様で指定された形式で API 応答を返します。
{ "name": "Fourth Coffee lobby renovation", "availableFunds": 5000.00 }エージェントは、API 応答に基づいて応答を生成します。
エージェントは、「4 番目のコーヒー ロビーの改装予算に残っている利用可能な資金は$5,000 です」という応答を送信します。
アクションの確認
Copilot は、API プラグインにデータを送信する前にユーザーに質問します。
既定では、データのみを取得する API はユーザーに "常に許可" オプションを提供しますが、データを変更する API は許可しません。 プラグイン開発者は、これらの既定値をオーバーライドできます。 詳細については、「Microsoft 365 Copilotの API プラグインの確認プロンプト」を参照してください。
応答プレゼンテーションのカスタマイズ
Copilot は、API 応答からのデータを使用して会話型応答を生成します。 プラグインは、アダプティブ カード テンプレートを提供して構造化された方法でデータを表示することで、これらの応答をカスタマイズできます。
Copilot オーケストレーター用にプラグインを最適化する
Microsoft 365 Copilotは、レパートリーの多くのスキルから適切なスキルを一意に選択できます。 しかし、Copilotが適切なスキルを提供するために プラグインを 選択することを確認するにはどうすればよいですか?
答えは、プラグイン、そのスキル、スキルの開始のためのパラメータを記述する方法にあります。 プラグイン マニフェストで簡潔で正確な説明を指定して、Copilot オーケストレーターがプラグインを呼び出すタイミングと方法を確実に把握できるようにします。
次の表に示すように、プラグインをオーケストレーターに記述する方法は、ビルドするプラグインの種類によって異なります。
| プラグインの種類 | 説明: | 詳細情報 |
|---|---|---|
| API プラグイン。 | OpenAPI の説明 | Copilot を拡張する際に OpenAPI ドキュメントを有効にする方法 |
| Copilot Studio アクション | 会話マップの名前と説明Copilot Studio | 生成的 AI を使用して副操縦士のトピックとアクションを調整する |
| メッセージ拡張機能プラグイン | アプリ マニフェスト | メッセージ拡張プラグインのガイドライン |
API プラグイン パッケージの生成
開発者が API プラグイン パッケージを生成するために使用できる 2 つのツールがあります。
- Visual Studio または Visual Studio Code の Microsoft 365 Agents Toolkit では、既存の OpenAPI の説明に基づいてプラグイン パッケージを作成できます。 既存の API がない場合、エージェント ツールキットには、API の例と対応するプラグイン パッケージを含むスターター プロジェクトもあります。
- Kiota は、コマンド ライン ツールであり、既存の OpenAPI の説明に基づいてプラグイン パッケージを生成できる Visual Studio Code 拡張機能です。
制限事項
宣言型エージェント プラグイン
宣言型エージェント マニフェストで定義されている最大 5 つのプラグインが 宣言型エージェントに含まれている場合、プラグインは常にプロンプトに挿入されます。 5 つを超えるプラグインが定義されている場合、エージェントはセマンティック マッチングを使用します。 セマンティック マッチングは、プラグイン自体内の個々の関数ではなく、プラグインの説明に基づいています。
プラグインには、無制限の数の関数を含めることができます。 一致する関数が 1 つだけであっても、すべての関数が返されます。 ただし、トークンウィンドウの制限により、10 を超える関数が含まれている場合、応答の品質が低下する可能性があります。
プラグインへの入力とプラグインからの出力のトークン ウィンドウでは、大きなコンテンツが切り捨てられます。 機能制限は、モデルが改善され、システムのオーバーヘッドに応じて変更される可能性があります。 トークンの長さが小さい場合は最適化するか、必要に応じて大きなコンテンツをストリーミングできる機能拡張オプションを選択します。