API プラグインを使用すると、Microsoft 365 Copilot エージェントは Web サービスと対話し、リアルタイムの情報にアクセスできるようになります。 API プラグインを使用すると、ユーザーは自然言語コマンドを通じて基幹業務 (LOB) システムからのリアルタイム データを Copilot Chat 内のエージェントに操作できます。
API プラグインは、API サービス、OpenAPI の説明、およびマニフェスト ファイルで構成されます。 プラグイン マニフェストは、API の機能について Copilot オーケストレーターに通知します。 プラグイン マニフェストには、API サービスの OpenAPI の説明が含まれています。 OpenAPI の説明は、API に接続する方法を Copilot に説明するため重要です。 Copilot でプラグインの検出可能性とパフォーマンスを最適化するには、明確で意味のある OpenAPI の説明を指定します。
この記事では、Copilot エージェントの機能を拡張するプラグインに対して OpenAPI の説明を効果的にする要素について説明します。
OpenAPI の説明要素
このセクションでは、OpenAPI 記述の要素と、Copilot エージェント用に最適化する方法について説明します。
OpenAPI の検証: 最初のステップは、OpenAPI の説明が OpenAPI 仕様のルールに従っていることを確認することです。 他のユース ケースの中でも特に OpenAPI の記述を検証できるコマンド ライン ツールである Hidi、またはその他の任意のツールを使用できます。 有効な OpenAPI の説明は、Copilot で適切に機能するだけでなく、OpenAPI の説明が他のツールでも動作することを保証します。
info セクション: 説明フィールドは OpenAPI 仕様では省略可能ですが、Copilot のスキルを拡張することを目的とした OpenAPI の説明には不可欠です。 Copilot では、API の機能とプラグインを使用するタイミングを知るために、説明フィールドが必要です。 OpenAPI ドキュメントからプラグイン マニフェストを生成する場合、info セクションの説明はプラグイン マニフェストの説明として使用されます。 したがって、説明フィールドを常に簡潔明瞭にすることが重要です。 たとえば、修理店の OpenAPI の説明の情報セクションを次に示します。
info:
title: Repair Service
description: A simple service to manage repairs for various items
version: 1.0.0
操作 ID: OpenAPI 記述の使いやすさを向上させるための便利な手法は、API によって提供される API パスと HTTP メソッドの組み合わせごとに operationID を追加することです。 操作 ID は、API の操作の一意識別子であり、ユーザーのプロンプトに応答するときに実行される関数を作成するために Copilot によって使用されます。
さらに、API でサポートされている各操作のわかりやすい説明を追加します。 Copilot は、ユーザーのプロンプトとプラグインの説明に基づいてプラグインの使用を選択した後、パスの説明を検索して、ユーザーの要求を満たすために使用するエンドポイントを決定します。
操作 ID は、Copilot が実行しようとしている操作を示す関数としてデバッグ中に表示されます。 OpenAPI ドキュメントのサンプルと、対応するデバッガー出力のサンプルを次に示します。
paths:
/repairs:
get:
operationId: listRepairs
summary: List all repairs
description: Returns a list of repairs with their details and images
デバッガー出力:
パラメータ: API でサポートされている操作がパラメーターを受け取る場合は、OpenAPI の説明にパラメーターを含めます。 各パラメーターの説明フィールドを含めて簡単に説明し、必要に応じてパラメーターの使用例を示します。 パラメーターは、API への要求を行うためのユーザーのプロンプトから必要なすべての情報を取得するために Copilot によって使用されます。
次に例を示します:
parameters:
- name: assignedTo
in: query
description: The name or ID of the person or team to whom the repair is assigned.
schema:
type: string
required: false
応答: 成功と失敗の両方の応答を含め、各操作で考えられるすべての応答を明確に定義します。 各応答には、状態コードと、それが表す内容の説明が必要です。 応答の例を含めると、Copilot が API に何を期待できるかを理解するのに役立ちます。
responses:
'200':
description: A list of repairs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Repair'
examples:
example1:
value:
[
{
"id": "1",
"item": "Laptop",
"status": "In Progress",
"assignedTo": "John Doe"
}
]
'404':
description: No repairs found
'500':
description: Server error