Copilot を拡張する際に OpenAPI ドキュメントを有効にする方法

[アーティクル]
10/03/2024

プラグインを使用すると、Microsoft Copilot Web サービスを操作し、リアルタイムの情報を取得できます。 Copilot は、この情報を使用してスキルを拡張します。プラグインを使用すると、ユーザーは基幹業務 (LOB) システムから Copilot にリアルタイムデータを取り込むことができます。

プラグインは、API サービス、OpenAPI の説明、マニフェストファイルで構成されます。プラグインマニフェストは、API の機能について Copilot に通知します。プラグインマニフェストには、API サービスの OpenAPI の説明が含まれています。 OpenAPI の説明は、API に接続する方法を Copilot に記述するため、重要です。 Copilot で最適なプラグインのパフォーマンスを得るには、明確でわかりやすい OpenAPI の説明を指定します。このドキュメントでは、Copilot を拡張するプラグインに対して OpenAPI の説明を有効にする要素について説明します。

ここでは、API とそれに関する OpenAPI の説明があると仮定します。

OpenAPI 検証: 最初に、OpenAPI の説明が OpenAPI 仕様の規則に従っていることを確認することをお勧めします。 Hidi は、他のユースケースの間で OpenAPI の説明を検証できるコマンドラインツール、またはその他の任意のツールを使用できます。有効な OpenAPI の説明は Copilot とうまく機能するだけでなく、OpenAPI の説明が他のツールと連携できることを確認します。

情報セクション: 説明フィールドは OpenAPI 仕様では省略可能ですが、Copilot スキルを拡張するための OpenAPI 説明には不可欠です。 Copilot では、API の機能とプラグインを使用するタイミングを把握するために説明フィールドが必要です。 OpenAPI ドキュメントからプラグインマニフェストを生成する場合、情報セクションの説明がプラグインマニフェストの説明として使用されます。したがって、簡潔で明確な説明フィールドを常に持つことが重要です。たとえば、修復ショップの 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

次の方法で共有

Copilot を拡張する際に OpenAPI ドキュメントを有効にする方法

フィードバック

その他のリソース