コネクタ AI プラグインを作成する (プレビュー)

[アーティクル]
11/30/2023

このトピックはプレリリースドキュメントであり、変更される場合があります。

ユーザーが Microsoft 365 チャットの一部として追加できる AI プラグイン機能を使用して、認定 Power Platform コネクタを新規作成または既存のコネクタを拡張することができます。 Microsoft 365 Copilotを使用すると、これらの AI プラグインは、AI を通じてユーザーをデータソースに接続し、対話に役立ちます。

この記事では、コネクタで AI プラグイン機能を有効し、ベストプラクティスを確認して、Microsoft 365 Chatでコネクタを AI プラグインとして有効にする一般的なレコメンデーションを適用する方法について説明します。

重要

これはプレビュー機能です。
プレビュー機能は運用環境での使用を想定しておらず、機能が制限されている可能性があります。これらの機能を公式リリースの前に使用できるようにすることで、顧客が一足先にアクセスし、そこからフィードバックを得ることができます。

開始する前に

AI プラグイン機能を使用した、新しいコネクタの作成、または既存のコネクタの拡張を開始する前に、設計原則と対象ユーザーを必ず理解してください。また、システムの機能についても確認してください。

AI プラグインのユーザーを理解する

コネクタベースの AI プラグインの開発者または作成者は、プラグイン操作を呼び出すペルソナを知っておく必要があります。ペルソナに応じて、AI プラグインとして有効にする適切なコネクタアクションを選択する必要があります。

注意

コネクタの対象ユーザーは通常、作成者と開発者です。ただし、コネクタ AI プラグインは基幹業務従事者が利用できる必要があります。

適切なコネクタアクションのみを有効にする

ユーザーのペルソナを理解した上で、ユーザーが Copilot にリクエストを入力するときにどのような情報を持っている可能性があるかを知る必要があります。提供できる内容は、対応するプラグイン操作が呼び出されたときにリレーされます。したがって、Copilot ユーザーが必要な入力を提供できるアクションのみを選択する必要があります。

例については、認定コネクタでサポートされているクエリを参照してください。

コネクタ認定

Copilot AI プラグインの拡張機能を備えたコネクタは、ユーザーが Microsoft 365 Copilot で AI プラグインを使用する前に、認定コネクタとして公開する必要があります。現時点では、カスタムコネクタを AI プラグインとして使用することはできません。AI プラグインの公開には認定が必須要件です。

コネクタの認定の詳細については、コネクタの認定を受けるを参照してください。

AI プラグイン機能を使用してコネクタを作成または拡張する

コネクタに AI プラグイン機能を提供し、ユーザーが Microsoft 365 Copilot 内で (Microsoft 365 チャットエクスペリエンスなどで) AI プラグインとして使用できるようにするには、次の手順に従います:

新しいコネクタを作成するか、Copilot 機能を追加して既存のコネクタを編集します。詳細: コネクタを使用して外部データに関する回答を更新または取得する
新しいコネクタまたは編集されたコネクタを Copilot 機能で認証します。詳細: コネクタの認定を受ける

サポートされる機能とされない機能

AI オーケストレーターと AI プラグインの機能は、急速に進化する状況の一部であるため、最初はいくつかの制限が予想されますが、これらは今後解決されるでしょう。ただし、何がサポートされていて、何がサポートされていないのかを知ることは重要です。

読み取り専用コネクタアクションは AI プラグイン操作としてサポートされている

現時点では、クエリ (読み取り専用) シナリオのみがサポートされています。これらは通常、REST API Swagger 定義の GET メソッドによって公開されています。

アトミックコネクタアクションは AI プラグイン操作としてサポートされている

現在、AI プラグイン呼び出しの一部として呼び出すことができるのは、アトミックコネクタアクション (単一の基礎となる API アクション) のみです。

コネクタアクションをまたぐ複数ステップオーケストレーションは制限される

これは、コネクタアクション間でデータを結合する場合に問題になります。 2 つの異なるコネクタアクションとして公開される 2 つの API パスがあるシナリオを考えてみましょう。

ListTickets: 次のフィールドでリクエストを行ったユーザーをスコープした複数のチケットレコードを返すAPI: Ticket\_Id、Ticket\_Title、Ticket\_Priority、Ticket\_Status。
DisplayTicket DetailsByTicketId: APIは Ticket\_Id、Ticket\_Title、Ticket\_Priority、Ticket\_Status、Ticket\_Assigned\_To、Ticket\_Opened\_By、Ticket\_Expected\_Close\_Date、Ticket\_Close\_Date、Ticket\_Open Date、その他の詳細を含む包括的なチケットデータを返します。

ユーザーが Copilot で システム送信エラーチケットの詳細を表示する というクエリを発行すると、現在のオーケストレーターは、次の 2 つの API アクションにまたがるプランをオーケストレーションできるとは限りません: 1) チケットを検索して、「システム送信エラー」という名前と一致するチケットの Ticket_ID を特定するために、チケットを一覧表示する、および 2) ステップ 1 の Id に基づいてチケット詳細アクションを呼び出す。

この場合、ユーザーがまず AI プラグインにチケットの一覧表示を要求し、チケット id を取得してから、そのチケットの詳細を要求する、または API 開発者が、チケットのタイトルに基づいてチケットの詳細を表示する新しい API を作成する必要があります。その後、この API を新しいコネクタアクションとして公開し、プラグイン操作として有効にすることができます。 API 開発者には、Copilot ユーザーが直接利用できる API を公開することを強くお勧めします。

必要な入力を推測するための Copilot の限界

Copilot が必要な入力を推測できると思わないでください。ユーザープロンプトについて考えるときは、必要な入力を Copilot への指示の一部にする必要があることを想定してください。

LLM (大規模な言語モデル) が入力を推測できるシナリオは限られています。ただし、これはルールというよりむしろ例外でした。例として、2 つの入力 (1) 位置 (2) 温度の単位を必要とする天気コネクタの場合、ユーザーが ワシントン州シアトルの天気を表示 するように指示して測定単位を指定しなかった場合、Copilot は AI プラグインを呼び出すときに、測定単位として華氏を追加しました。 Copilot は、ユーザーが華氏が一般的に使用される温度の単位である米国の場所について質問しているため、華氏の測定値を使用する必要があると推測した可能性があります。

ただし、一部のシナリオでは、Copilot が入力を推測できなかったり、誤って推測したりすることがありました。このような場合は、動作が想定どおりであることを確認するために、Copilot に対するロバストなテストを行うことを強くお勧めします。

コネクタからの応答に対する推論の限界

AI プラグインの応答に対する推論の観点から、Copilot がどのような操作を実行できるかを検証することが重要です。

出力を推論するいくつかの基本的な機能は可能です。これには、シナリオに基づいた検証が必要です。たとえば、営業アプリの AI プラグイン、クローズ確率が高い営業案件を表示 では、LLM は返された営業案件と、クローズの確率が >50% で表示されたものをフィルターすることができました。データフィールドのクローズ確率を利用してデータをフィルターすることができました。応答のフィールドが LLM によって使用されるとは限りません。 50% という選択も LLM による任意のものですが、ユーザー入力がないことを考えると妥当です。ただし、LLM は、このシナリオで 100％の確率でクローズした営業案件も表示しましたが、これはユーザーが望んでいたものではない可能性があります。このシナリオの場合、ユーザーは要求を変更して、クローズ確率が高い対応中の営業案件を表示 する可能性があります。

レコメンデーションとベストプラクティス

シンプルさと正確さは、LLM が AI プラグインをいつどのように呼び出すかを把握するために重要です。例:
- これは営業アプリから営業案件、リード、取引先担当者を戻す営業アプリプラグインです のような AI プラグインのマニフェストの説明は、単なる 営業アプリプラグイン よりも優れています。
- これは重要な Sales エンティティからデータを取得するために使用できる Dynamics 365 Sales プラグインです のような AI プラグインアクションの説明は誤解を招きます。代わりに、これは営業アプリから営業案件、リード、取引先担当者を戻す Dynamics 365 Sales プラグインです を検討してください。
- AI プラグインアクションパラメーターの説明: 各コネクタアクションの説明では、特定のアクションを説明する必要があります。たとえば、このアクションは、MM/DD/YYYY 形式のリード作成日範囲に基づいて Dynamics 365 Sales リードを戻します。入力の詳細を提供すると、LLM はアクションを調査するための可能な方法を知ることができます。また、ユーザー入力のデータフィールドを、基盤となる AI プラグインや公開している API アクションで必要なデータフィールドにマップするのにも役立ちます。パラメーターの書式設定情報を提供すると、Copilot が API の呼び出し時に送信する入力を適合させるのに役立ちます。
AI プラグイン、プラグインの操作、パラメーターに一般的な説明を使用しないでください。
- AI プラグインの作成者は、プラグインが何を行い、何を行わないかを正確に記述する必要があります。 AI プラグインが Copilot で使用される可能性を実証するために追加情報を追加することは魅力的ですが (Web ページの検索エンジン最適化と同様)、これにより次のような重大な問題が発生する可能性があります。
  - 汎用プラグインの説明では、ジョブに適切な AI プラグインが選択されない可能性があります。これが頻繁に発生する場合は、ユーザーはそのようなプラグインをオフにすることができます。
  - 選択を誤ると、AI プラグインの実行や応答が失敗する可能性があります。 Copilot は、エラー率の高い AI プラグインを検出できません。エンドユーザーは、Copilot からの応答に反対票を投じることもできます。時間が経つにつれて、このデータを使用して、問題のあるプラグインを特定し、管理者や Copilot が対処することができます。

AI プラグインをテストする

LLM が目的のプロンプトに対して適切な実行プランを作成できることを確認するには、検証が重要です。場合によっては、プロンプトの修正バージョンのみが成功することがあります。

サポートされる機能とされない機能を必ず確認してください。この記事で以前に説明した考慮事項も確認してください。

プラグイン検証ツールを使用すると、カスタムコネクタ UI で行われたプラグイン関連の変更がターゲットのユースケースに十分であることをユーザーが検証できます。このツールは、Semantic Kernel (SK) を使用して構築されており、ユーザーはプラグインレベルの注釈を含む swagger を入力できます。また、AI がプラグインを使用して応答することを期待するプロンプトの健全性テストも行います。

前提条件

プラグイン検証ツールのダウンロード。
Azure OpenAI Service または OpenAI サブスクリプションの使用。詳細: AI プラットフォームへようこそ

その後、以下の詳細が必要です:
- OpenAI キー
- OpenAI organizationId
- 使用する OpenAI モデル。 gpt-3.5-turbo-16k を推奨します。
コネクタの Swagger json ファイル (プラグインレベルの注釈が入力されました)。これは、カスタムコネクタページでコネクタのダウンロードを選択することで取得できます。 Swagger ファイルへのパスは、ツールへの入力として使用されます。

重要

現在、さまざまなオーケストレーションエンジンが使用されています。違いがあり、エクスペリエンスが異なる場合がありますが、AI オーケストレーターを使用してテストすることは、Copilot 対応コネクタをテストしない場合よりも常に大きな価値をもたらします。

プラグイン検証ツールを実行する

次の手順に従って、プラグイン検証ツールを実行し、Copilot 対応コネクタをテストします。

次の引数でツールを実行します:

タイプ: OpenAI または AzureOpenAI (OpenAI を使用)
OpenAI キー: {insert key}
OpenAI 組織 ID: {insert orgId}
使用するモデル: {gpt-3.5-turbo-16k}
Swagger ファイルのパス: "C:\\Users\\abe\\OneDrive - Microsoft\\Documents\\apiDefinition.swagger.json"

用例:

plugin-validator.exe OpenAI id-abc org-abc gpt-3.5-turbo-16k "C:\\Users\\abe\\OneDrive - Microsoft\\Documents\\apiDefinition.swagger.json"

ツールは、渡された Swagger を読み取ります。 swagger 内のプラグイン関連の注釈を使用して、元の swagger ファイルのディレクトリに最終的なプラグイン swagger ファイルを作成します。このディレクトリは、プロンプトのテストに使用されます。新しいファイルの名前は、plugin-swagger.json です。

ツールは、ループ内で次のアクションを実行します:

ツールは、ユーザーにプロンプトをテストするように求めます。
ユーザーはプロンプトを入力します (例: 営業アプリの営業案件トップ 10 を表示する)。
ツールは、次の JSON 構造を出力します:
- OperationId: プロンプトへの応答に使用されるアクションの operationId。
- Url: データの取得に使用される URL (クエリパラメーターを含む)。
- 本文: 要求で使用される本文パラメーター。
- ヘッダー: 要求で使用されるヘッダー。
- MissingParameters: アクションに必要ですが、ユーザーがクエリで指定しなかったパラメーター。

以下に、SK ツールの例を示します。現在のバージョンを使用していますが、すぐに変更される可能性があります。

Enter prompt to test plugin (Example: show me open opportunities)
show me tickets that are pending
{
       "operationId": "Tickets_GetAll",
       "url": "https://helpdesk-services-beta.plumsail.com/_flow/v4/Tickets?$filter=Status/InternalName eq 'Pending'",
       "body": {},
       "missingParameters": []
}
 
Enter prompt to test plugin (Example: show me open opportunities)
show me planner tasks in buckat b123
{
       "operationId": "ListTasks_V2",
       "url": "https://graph.microsoft.com/v1.0/planner/buckets/b123/tasks",
       "body": {},
       "missingParameters": []
}
 
Enter prompt to test plugin (Example: show me open opportunities)
get group plans
{
       "operationId": "ListGroupPlans",
       "url": "https://graph.microsoft.com/v1.0/groups/{groupId}/planner/plans",
       "body": {},
       "missingParameters": ["groupId"]

結果を検証および確認する

以下に、結果を解釈し、Swagger に変更が必要かどうかを検証する手順に示します。

選択された operationId が、プロンプトへの応答に使用されると想定される Swagger 定義ファイル内のアクションと一致することを検証します。そうでない場合は、おそらくアクション内の説明が、モデルがどのアクションを使用する必要があるかを解読できるほど詳細ではありません。

ベストプラクティスに従って説明を更新し、再試行してください。
URL 情報を検証します。主なチェックは、どの要求パラメーターが使用されているか、およびパラメーターと値がどのようにフォーマットされているかを検出することです。プロンプトと API の内部動作の解釈に基づいて、このような URL が成功するか失敗するかを判断します。モデルが必要なパラメーターと書式設定をより正確に判断できるようにパラメーター情報を更新する方法については、ベストプラクティスセクションを確認してください。

たとえば、status と category のクエリフィルターパラメーターを受け取る API ルート GET /tickets があるとします。プロンプト 問題として分類されたチケットを表示 をテストすると、ツールには使用する変数として ?category=problem が含まれていると思います。
本文を検証します。 URL クエリセクションで行うのと同様の検証を実行して、必要な本文パラメーターがあるかどうか、それらが含まれているかどうか、適切にフォーマットされているかどうかを確認します。
ヘッダーセクションを検証します。通常、これには検証は必要ありません。ただし、ユーザーがプロンプトに含めるパラメーターがヘッダーセクションに必要な場合があります。そうでない場合は、このセクションをスキップしてください。
missingParameters フィールドが空であることを確認します。そこに値がある場合は、モデルが把握できなかった必須パラメーターがルートに存在することを意味します。そのデータがプロンプトに含まれていないか、プロンプト内のどこにあったかを判断できません。これはおそらく、ユーザーの入力内容に合うようにプロンプトを調整するか、パラメーターの説明を調整する必要があることを意味します。
これらすべての手順の結果が良好であれば、Swagger 内の情報は、試したようなプロンプトに答えるのに十分である可能性があります。そうでない場合は、ベストプラクティスセクションを確認してください。

ツールに関する考慮事項

ツールを実行するたびに (同じプロンプトであっても)、LLM が行う決定に基づいてパラメーターの形式が異なる場合があります。これは予想されることであり、発生する可能性のある違いを理解するために、特定のプロンプトを数回実行することが役立つ場合があります。これにより、それらがまだ有効であることを確認できます。

ツールの各実行はクリーンな状態から開始され、前のプロンプトを参照したり、実行間でデータを取得したりすることはできません。

プラグイン検証ツールには、次の制限があります:

ツールは、プロンプトがアクションと関係ない場合でも、アクションを返すことに偏っています。たとえば、Swagger に 1 つのルート /tickets があり、プロンプトが 事物を取得する である場合でも、使用するルートとして /tickets を返すことがあります。意味不明な (または無意味な) ことを入力すると、ルートが返されることがあります。これは AI コパイロット自体の動作ではなく、このテストツールの制限です。
ツールの現在の日付コンテキストは、正しい日付ではない可能性があります。 先週作成されたチケットを表示する というプロンプトには、OData フィルター値が ge '2021-02-01' に作成 されていることが示されていますが、これは正しくありません。これは他のオーケストレーターでは期待どおりに機能するようですが、ツールでは次のように表示されます。
特定の状況に対するベストプラクティスに従い、説明にコンテキストを提供しているにもかかわらず、ツールが予期しない結果を返す場合、これがツールの根本的な制限である可能性があります。

トラブルシューティングのヒント

シナリオに基づいて Swagger のアクション/パラメーター/応答を更新する例をいくつか示します:

アクション/ルートの説明を更新します。テストツールがプロンプトに使用するアクションを決定できない場合は微調整します。

件名パラメーターを使用してコースを取得するルートをわかりやすくするために、古いルートの説明と新しいルートの説明を比較した例を次に示します:
- 旧: コースの取得
- 新: 指定された件名のコースのリストを取得する
パラメーターの説明を更新します。テストツールに期待されたパラメーターが含まれていない場合、パラメーターが省略されている場合、またはパラメーターが期待したとおりにフォーマットされていない場合は、微調整します:
- 間違ったパラメーターが使用されている場合は、おそらくパラメーターの説明をより明確にするか、プロンプトをより明確にする必要があります。たとえば、作成者と所有者のパラメーターを受け取る /tickets エンドポイントがあり、プロンプトが james のチケットを取得 である場合、どのパラメーターを使用すればよいかわからない可能性があります。プロンプトは、さらに詳細にする必要がある場合があります。
- パラメーターが追加されるべきでないときに追加されている場合、または追加する必要があるときに追加されていない場合は、説明が曖昧すぎるか間違っている可能性があります。パラメーターの説明を更新して、どのような場合に使用する必要があるかについて、詳細なコンテキストを提供します。また、おそらく既定値も含めます。
- パラメーターが値を引用符で囲むことを想定している場合 (たとえば、ODATA $filter の場合):
  - 返されるエントリをフィルターするための ODATA $filter クエリ。フィルター値は一重引用符で囲む必要があります。
- ODATA $filter が限られた機能のみをサポートしている場合は、次のように呼び出します:
  - 返されるエントリをフィルターするための ODATA $filter クエリ。次のフィルターオプションのみをサポートします: <、>、=。
- 日付パラメーターを特定の形式にする必要がある場合 (例: created\_at パラメーターの場合):
  - 特定の日付に作成されたデータを返します。形式は次の形式である必要があります: yyyy-mm-dd。
- field_to_return というパラメーターに特定の大文字が必要な場合:
  - 入力されたフィールドのサブセットを返します。フィールド名は snake_cased である必要があります (例: created\_at)。
- フィルターに使用できる値が限られている場合。たとえば、ステータスでフィルターできる 'status' というパラメーターの場合:
  - 選択したステータスのデータを返します。サポートされている値は、新規、進行中、終了です。
フィルターが必要なパラメーターがあり、見つからない場合に Swagger の応答を更新します:
- ユーザーがフィルターする特定の値を要求できる場合、それらの値が列挙型として応答に含まれていることを確認します。これは、ユーザーが任意のフィールドと値でフィルターできる ODATA `$filter`` の場合に特に役立ちます。
  - 応答にステータス値がある場合は、サポートされている列挙値を必ず含めてください。
  - 例: "enum": \[ "New", "InProgress", "Pending", "Solved"\]
ツールの実行時に次のエラーが発生した場合は、このモデルのコンテキストの最大長は 16385 トークンです。ただし、メッセージの結果は {} トークンでした。メッセージの長さを短くしてください。次の手順を実行してください。コマンドを実行するときに (GPT-3.5-Turbo-16k の代わりに) GPT-4 モデルをパラメーターとして選択してください。
- Azure OpenAI サービスを使用している場合は、 Azure OpenAI サービスクォータの管理でレート制限を設定してクォータを増やす方法を確認できます。
- OpenAI ChatGPT を使用している場合は、モデルで使用する他のモデルを見つけることができます。
- OpenAI 価格で別のモデルを選択する際、価格の考慮事項を評価できます。

AI プラグイン対応コネクタを認証のために提出する

AI プラグインをテストした後、認定のためにコネクタを送信します。

Copilot 対応コネクタを送信する場合は、次の追加情報が必要です:

これらのプロンプトが役立つペルソナおよびシナリオ。
プロンプト (ユーザーがチャットで入力するフレーズ) とプロンプトに対する予想される応答のリスト。
テストツールのプロンプトを使用したテスト結果のスクリーンショット。

送信前に、次の情報を必ず確認してください:

AI プラグインの説明を確認して、正確で許容できることを確認します。
想定される結果を検証します。
追加のセキュリティとコンテンツを確認し、コネクタが責任ある AI ガイドラインに従っていることを確認します。

認定コネクタでサポートされているクエリ

このセクションでは、現在サポートされているファーストパーティコネクタ AI プラグインのクエリの例を示します。

Freshdesk

freshdesk 製品を表示
チケット 6 の freshdesk チケットの詳細を表示
freshdesk エージェントを取得
freshdesk の連絡先を取得
2023 年 3 月以降に作成された freshdesk チケットを表示

セールスフォース

Salesforce から営業案件を取得
Salesforce の営業案件を表示
Smith Mobile Generators という Salesforceの営業案件に関する詳細を表示
この四半期に 75.0 を超える確率でクローズする可能性が高い Salesforce 営業案件を表示
Salesforce のリードを表示
Salesforce のリードの詳細を表示 <First_name Last_name>
過去 120 日間に作成された Salesforce の見込みありと評価されたリードの詳細を表示
Salesforce アカウントを表示
Burlington Any Corp of America の Salesforce アカウントの詳細を表示
年間売上高が $500000000 を超える Salesforce アカウントを表示
クローズされていない accountId 001Hp00002eQ3O1IAK の Salesforce ケースを表示
件名にジェネレーターが含まれる Salesforce のケースは何ですか?
クローズされていない Salesforce ケースを表示

Zendesk

Zendesk アカウントのチケットを表示
チケット 8 の zendesk チケットの詳細を表示しますか?
zendesk チケット 2 のステータスは?
zendesk チケット 2 は誰に割り当てられますか?
zendesk ユーザー 55555555555555 の詳細を表示
55555555555555 によって提出された zendesk ticket 13 に関するコメントを表示
削除されていない zendesk グループを表示

ServiceNow

ServiceNow インシデントのリストを表示
ServiceNow インシデント "INC0010003" の詳細を表示
ServiceNow インシデント "INC0010007" は誰に割り当てられていますか?
10 月に作成された ServiceNow インシデントを表示
xxx.creator によって作成された ServiceNow インシデントを表示
ServiceNow タスクのリストを取得
ServiceNow タスク "INC0010006" の詳細を表示
2023 年 10 月 6 日より前に作成された ServiceNow タスクを表示
ServiceNow ユーザーのリストを取得
ServiceNow ユーザーの詳細をメール john.smith@example.com で取得

Twilio

ネットワーク内のすべての Twilio メッセージを表示
電話番号 "+18445554360" への Twilio メッセージを表示
6785555306 からの Twilio メッセージを表示
2023 年 10 月 6 日に送信された twilio メッセージを表示

GitHub

Sublime が所有するリポジトリスペースに関する問題 200 の詳細を表示
Sublime が所有するリポジトリスペースに関する pull request 150 の詳細を表示
Sublime が所有するリポジトリスペースに関する問題を一覧表示
Sublime が所有するリポジトリスペースに関する pull request を取得
ユーザーが所有する github repos を取得 <ユーザーの GitHub エイリアス>
org Microsoft のパブリック github repos を一覧表示

MailChimp

MailChimp リストを取得
MailChimp キャンペーンを一覧表示

MSN ウェザー

ワシントン州ウェストポートの現在の天気を取得
ジョージア州アテネの今日の天気予報を取得
ジョージア州アトランタの明日の天気予報を取得