Copilot 拡張機能を作成またはアップグレードするためのガイドライン
重要
- Microsoft Copilot for Microsoft 365 のプラグインはプレビュー段階であり、Microsoft Teamsの Microsoft 365 Chat でのみ機能します。
- Copilot for Microsoft 365 が組織で利用できることを確認します。 Copilot の開発環境を取得するには、次の 2 つの方法があります。
- Copilot を含むサンドボックス Microsoft 365 テナント ( TAP メンバーシップを通じて限定プレビューで利用できます)。
- Microsoft Copilot for Microsoft 365 ライセンスを使用したエンタープライズ顧客の運用環境。
Microsoft 365 プラグインは、Teams や Outlook など、さまざまな Microsoft 365 製品との統合を提供します。 統合により、ユーザーは外部システムでコンテンツを検索または作成できます。 メッセージ拡張プラグインを使用すると、Microsoft Copilot for Microsoft 365 はボットを介して他のソフトウェアやサービスの API と対話できます。 Microsoft 365 用 Copilot では、次のことができます。
- 最新情報またはレコードを検索します。 たとえば、最新のインシデント チケットやアンケートの結果などです。
- 複数のレコードに基づいて情報を要約します。 たとえば、プロジェクト Northwind に関連するすべてのインシデント チケットを要約します。
既存のメッセージ拡張機能をビルドまたはアップグレードして、Copilot for Microsoft 365 での有用性と使いやすさを最大化することをお勧めします。 Microsoft 365 用 Copilot がユーザーに代わって実行できるスキルとして認識されるため、メッセージ拡張機能は 1 つ以上の検索コマンドをサポートする必要があります。 さらに、拡張機能は、この記事で説明するコンプライアンス、パフォーマンス、セキュリティ、およびユーザー エクスペリエンスの標準を満たす必要があります。
注:
Microsoft 365 用 Copilot 用のカスタム Graph コネクタを構成する場合は、 Graph コネクタを作成またはアップグレードするためのガイドラインに従っていることを確認してください。
必須の要件
Microsoft 365 用 Copilot のメッセージ拡張プラグインを構築するための要件は次のとおりです。
説明を定義する
適切な説明は、アプリの機能の明確で簡潔な概要を提供し、Microsoft 365 用 Copilot が検索操作を効率的に検出して実行できるようにします。 ユーザーが動詞 ( 例: Contoso チケットの検索) と共にアプリ名を入力する場合、メッセージ拡張プラグインは、Microsoft 365 用 Copilot から呼び出す必要があります。
次の表に示す説明ガイドラインに従っていることを確認します。
アクション | 理由 |
---|---|
アンチ競合: 短い説明と長い説明の両方で他のプラグインの名前を使用しないでください。 | |
責任ある AI: 不適切または不快なキーワードの使用を避けます。 | |
プロンプトの挿入: 説明が、アプリケーションの正常な機能をバイパスするアクションを実行するように Copilot に指示しないようにします。 さらに、説明には、プロンプト挿入のコードとして使用できることを示す記号やテキストを含めることはできません。 アプリを繰り返し呼び出すフレーズ、関数、コードは使用しないでください。 |
アプリの説明
長短のアプリの説明を明確にし、アプリのスコープを定義する必要があります。 Copilot for Microsoft 365 でアプリをプラグインとしてレンダリングするには、次のプラグイン要件に合わせてアプリの説明を変更します。
- 長い説明では、Microsoft 365 用 Copilot のメッセージ拡張機能プラグインの機能と使用方法を明確に説明する必要があります。 たとえば、Copilot for Microsoft 365 の Contoso クラウドを使用して、タスクを検索して要約します。
- 簡単な説明では、自然言語でアプリの機能を簡単に説明する必要があり、アプリの名前を含めることができます。
次の表に、各カテゴリの簡単な説明の例を示します。
説明: チケット、バグ、プロジェクトを作成、検索、表示します。
アプリの説明の例:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
"version": "1.0.0",
"manifestVersion": "1.13",
"id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
"name": {
"short": "Tasks",
"full": "Contoso Tasks"
},
"description": {
"short": "Create, search, view tickets, bugs, and projects",
"full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
},
検索コマンドの説明
コマンドの説明は、ユーザーの意図と発話をプラグイン内の検索コマンドにマップし、ユーザーの意図とキーワードの分析に基づいて構築する必要があります。 検索コマンドの説明では、次の手順を実行する必要があります。
- コマンドが自然言語で検索する内容と方法 (詳細な一覧) に焦点を当てます。
- 動詞とシノニム (該当する場合) を含めます。
- ネイティブ アプリの検索機能で使用される可能性が高いキーワードに焦点を当てます。
セマンティックの説明
semanticDescription プロパティは、Microsoft 365 用 Copilot のコマンドの詳細な説明を提供するために使用されます。 コマンドのセマンティック記述では、最大 5,000 文字がサポートされ、ユーザー インターフェイスには表示されません。
semanticDescription
プロパティが空のままの場合、Copilot for Microsoft 365 は description
フィールドの情報を使用します。
semanticDescription
を記述するときは、コマンドの予期される値、制限、および範囲に関する情報を含める必要があります。
semanticDescription
プロパティは必須フィールドではありません。 ただし、アプリ マニフェストに semanticDescription
を追加すると、短い説明、パラメーター、コマンドの説明に関する既存の検証チェックもセマンティックの説明に適用できます。
セマンティック説明に関する次のガイドラインを確認して、アプリが Microsoft Teams ストアの申請プロセスに合格する可能性を高めるのをお勧めします。
"ユーザーが X と言っている場合"、"無視"、"削除"、"リセット"、"新しい命令"、"太字で回答する"、"何も印刷しない" などの指示フレーズは避けてください。 [必須の修正]
URL、絵文字、または非表示文字 (16 進数、バイナリ、型破りな記号など) は使用しないでください。 [必須の修正]
文法と句読点のエラーは避けてください。 [必須の修正]
過度に冗長な、花の多い、またはマーケティング言語を避けてください。 [推奨される修正]
"#1"、"驚くべき"、"最適" などの最上級の要求は避けてください。 [推奨される修正]
次の表に、各カテゴリのコマンドとセマンティックの説明の例を示します。
説明: 明日の Northwind に関連する優先度の高いタスクを検索します。
コマンドの説明の例:
"commands": [
{
"id": "Search",
"type": "query",
"title": "Tasks",
"description": "Search for high priority tasks related to Northwind that are due tomorrow.",
"SemanticDescription": "Search for issues, epics, stories, tasks, sub tasks, bugs + additional details."
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
パラメータの説明
各メッセージ拡張コマンドでは、対応する 'parameters' プロパティがサポートされており、最大 5 つのパラメーターがサポートされており、最初のパラメーターがメッセージ拡張検索バーに表示されている必要があります。 パラメーターには適切な説明が必要です。許容されるパラメーター、列挙型、頭字語、および出力形式の組み合わせを含める必要があります。
semanticDescription プロパティは、Microsoft Copilot のコマンドの詳細な説明を提供するために使用されます。 パラメーターのセマンティック記述は最大 2,000 文字をサポートし、ユーザー インターフェイスには表示されません。
semanticDescription
プロパティが空のままの場合、Copilot は description
フィールドの情報を使用します。
semanticDescription
を記述するときは、コマンドの予期される値、制限、および範囲に関する情報を含める必要があります。
適切なパラメーターの説明では、出力形式の自然言語でのシステムの要件について説明します。 次に、各カテゴリの基本的な検索要求と高度な検索要求の例をいくつか示します。
基本検索: Northwind に関連するタスクを検索します。 高度な検索: 明日の Northwind に関連する優先度の高いタスクを検索します。
パラメーターの説明の例:
"parameters": [
{
"name": "Name",
"title": "Project or Task Name",
"description": "Project name or task name as keyword.",
"inputType": "text"
},
{
"name": "Time",
"title": "Time",
"description": "Date or number of days for which you need tasks for.",
"semanticDescription": "Date or number of days for which you need tasks for. Output: Number",
"inputType": "text"
},
{
"name": "Priority",
"title": "Priority",
"description": "Priority of tasks.",
"semanticDescription": "Priority of tasks. Acceptable values are high, medium, low, NA",
"inputType": "text"
}]
複合発話
注:
Copilot for Microsoft 365 では、ダイアログ (TeamsJS v1.x ではタスク モジュールと呼ばれます) を検索することはできません。
Microsoft 365 用 Copilot の場合、検索ベースのメッセージ拡張機能では、正確な情報を深く取得するために、3 つ以上の一意の複合発話をサポートする必要があります。 複合発話を有効にするには、 アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) を更新して、3 つ以上の検索パラメーターを処理するように検索範囲を拡張し、次のことを確認する必要があります。
複数のパラメーターに基づく検索をサポートするように Web サービスを更新します。 ユーザー要求に応答する方法の詳細については、「 検索コマンドに応答する」を参照してください。
Microsoft 365 の Copilot は、ユーザー発話の一部ではないパラメーターに空の文字列または null 値を渡して、パラメーターを処理するように Web サービスを更新する場合があります。
メッセージ拡張機能は最大 10 個のコマンド (9 個の使用可能) をサポートし、各コマンドには対応する
parameters
プロパティがあり、最大 5 つのパラメーターをサポートします。
次のコードは、アプリ マニフェストで定義されている複数のパラメーターの例です。
"commands": [
{
"id": "inventorySearch",
"context": [
"compose",
"commandBox"
],
"description": "Search products by name, category, inventory status, supplier location, stock level",
"title": "Product inventory",
"type": "query",
"parameters": [
{
"name": "productName",
"title": "Product name",
"description": "Enter a product name here",
"inputType": "text"
},
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category of the product",
"inputType": "text"
},
{
"name": "inventoryStatus",
"title": "Inventory status",
"description": "Enter what status of the product inventory. Possible values are 'in stock', 'low stock', 'on order', or 'out of stock'",
"inputType": "text"
},
{
"name": "supplierCity",
"title": "Supplier city",
"description": "Enter the supplier city of product",
"inputType": "text"
},
{
"name": "stockQuery",
"title": "Stock level",
"description": "Enter a range of integers such as 0-42 or 100- (for >100 items). Only use if you need an exact numeric range.",
"inputType": "text"
}
]
},
{
"id": "discountSearch",
"context": [
"compose",
"commandBox"
],
"description": "Search for discounted products by category",
"title": "Discounts",
"type": "query",
"parameters": [
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category to find discounted products",
"inputType": "text"
}
]
},
{
"id": "revenueSearch",
"context": [
"compose",
"commandBox"
],
"description": "Find products based on their revenue/period",
"title": "Revenue",
"type": "query",
"parameters": [
{
"name": "revenueRange",
"title": "Revenue range",
"description": "Enter 'high' or 'low' or enter a range of integers such as 0-10000 or 5000- using this exact format",
"inputType": "text"
}
]
}
]
検索パラメーターには、許容されるパラメーター、列挙型、頭字語、および出力形式を含む適切な説明が必要です。 詳細と例については、「 パラメーターの説明」を参照してください。
サンプル プロンプト
注:
サンプル プロンプトは、すぐに Copilot for Microsoft 365 で入手できます。
samplePrompts
プロパティは、Copilot 内のさまざまなプラグインを使用する方法についてユーザーにガイドします。 Copilot は、サンプル プロンプトを使用して、ユーザーのプロンプトを表示します。 プロンプトは、異なるロケールに適応でき、異なるコマンド間でクリアする必要があります。 サンプル プロンプトは、Copilot for Microsoft 365 内の次の領域で使用できます。
- First Run Experience (FRE): ユーザーが最初にプラグインをインストールまたは有効にしたとき。
- プロンプト ライブラリまたは Copilot ラボ: ユーザーがプロンプトのヘルプを求めるとき。
- プラグインの提案: より良い発話に向けてユーザーをガイドします。
注:
- アプリ マニフェストで
samplePrompts
プロパティが指定されていない場合、プロンプトは表示されません。 -
samplePrompts
プロパティは、アプリの申請プロセス中にアプリの検証に必須です。 - アプリに複数のコマンドを定義すると、最大 3 つのプロンプト (上位 3 つのコマンドのそれぞれから 1 つ) がユーザーに表示されます。 プロンプトは回転して、さまざまなコマンド間でさまざまなプロンプトセットをユーザーに提供します。
次のガイドラインに従って、アプリがMicrosoft Teamsストアの申請プロセスに合格する可能性を高めすることをお勧めします。
- プラグインには、少なくとも 3 つのプロンプトと、各コマンドに対して最大 5 つのプロンプトが必要です。
- 各プロンプトは 128 文字を超えてはなりません。
- 同じプラグイン内の 2 つのコマンドに、同じプロンプトを含めてはなりません。
- サンプル プロンプトは、本質的にジェネリックであり、カスタム参照を含めないようにする必要があります。 たとえば、プロジェクト名とタスク名です。
- すべてのサンプル プロンプトが機能し、応答を返す必要があります。
- プロンプトはコマンドに関連している必要があります。
次のコードは、アプリ マニフェストの samplePrompts
プロパティの例です。
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "bxxxxxx5-xxxx-xxxx-xxxx-4xxxxxx16599",
"commands": [
{
"id": "orders",
"title": "Orders",
"context": [
"Commandbox",
"Compose"
],
"description": "Search for orders",
"semanticDescription": "Search for orders",
"samplePrompts": [
{
"text": "Search for all orders"
},
{
"text": "Search for orders related to Contoso"
},
{
"text": "Search for all pending orders"
},
{
"text": "Search for all completed ordered for Fabrikam"
}
]
}
]
}
]
アダプティブ カードの応答
メッセージ拡張機能は、アダプティブ カードを使用してユーザー入力に応答します。 メッセージ拡張プラグインのアダプティブ カードは、効果的に機能し、リッチに表示され、次の要件を満たす必要があります。
アダプティブ カードの応答には、同じテンプレートの一部としてアダプティブ カードのコンテンツとプレビュー カード情報が含まれている必要があります。 [必須]
アダプティブ カード応答テンプレートの例
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "${companyName}", "size": "Medium", "wrap": true, "style": "heading" }, { "type": "TextBlock", "text": "${stockExchange} ${stockSymbol}", "isSubtle": true, "spacing": "None", "wrap": true }, { "type": "TextBlock", "text": "${formattedDate} ${formattedTime}", "wrap": true } ] }, { "type": "Container", "spacing": "None", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "width": "stretch", "items": [ { "type": "TextBlock", "text": "${currentPrice} ", "size": "ExtraLarge", "wrap": true }, { "type": "TextBlock", "text": "${priceChange} ${percentChange}", "color": "${changeColor}", "spacing": "None", "wrap": true } ] }, { "type": "Column", "width": "auto", "items": [ { "type": "FactSet", "facts": [ { "title": "Open", "value": "${openPrice} " }, { "title": "High", "value": "${highPrice} " }, { "title": "Low", "value": "${lowPrice} " } ] } ] } ] } ] } ], "previewCard": { "contentType": "application/vnd.microsoft.card.hero", "content": { "title": "${companyName}", "text": "${stockSymbol}" } } }
アプリのロゴ、タイトル、サムネイル、および情報のタイトルとは別に、アダプティブ カード内のデータは少なくとも 2 つの情報を表す必要があります。 最も頻繁に検索される属性 (変更されたデータ、作成者、状態、フラグなど) からフィールドを識別できます。 [必須]
アダプティブ カードは、デスクトップ、Web、モバイル (iOS および Android) で提示できる必要があります。 [必須]
アダプティブ カードには少なくとも 1 つのアクション ボタンが含まれている必要がありますが、4 つ以上のアクション ボタンは含まれません。 [必須]
注:
アクションの種類
imBack
、messageBack
データ オブジェクトではサポートされていません。次のアクションの種類をお勧めします。
-
Action.OpenUrl
: カードから指定した URL を開きます。 -
Action.ToggleVisibility
: カード内の 1 つ以上の要素を表示または非表示にします。 -
Action.Execute
: 入力フィールドを収集し、ボット サービスに要求として送信します。 -
Action.Submit
: データ オブジェクトで型呼び出しを使用して、ダイアログまたは Stageview を開きます。
-
ユーザーがダイアログ、ステージビュー、またはカードから直接カードの情報を変更できる場合は、ユニバーサル アクションと自動更新をサポートするためにアダプティブ カードをお勧めします。 [推奨]
アダプティブ カードには 、メタデータの一部として URL を含める必要があります。これにより、カードをハブ間で簡単にコピーできます。 [推奨]
サムネイルとは別に、アダプティブ カード内の画像には代替テキストが必要です。 [推奨]
ユーザーがダイアログ、ステージビュー、またはカードから直接カードの情報を変更できる場合は、ユニバーサル アクションと自動更新をサポートするためにアダプティブ カードをお勧めします。 [推奨]
アダプティブ カードには 、メタデータの一部として URL を含める必要があります。これにより、カードをハブ間で簡単にコピーできます。 [推奨]
サムネイルとは別に、アダプティブ カード内の画像には代替テキストが必要です。 [推奨]
会議でプラグインを Copilot に拡張する
Microsoft 365 用 Copilot は、Teams 会議で利用できます。 次を実装する必要があります。
アダプティブ カードでは、水平スクロールを表示しないでください。 水平スクロールを回避するには、固定幅を指定しないでください。 [必須の修正]
ColumnSets
- 3 つ以上の列を含む
ColumnSets
を定義しないでください。 - セット内の複数の列に明示的なピクセル幅を使用しないでください。
- 会議チャットや Copilot など、最も狭いカード幅の 4 分の 1 を超えないようにします。
- 一般に、明示的な幅は 48 ピクセルを超えることはできませんが、一部のシナリオでは例外が発生する可能性があります。
- 3 つ以上の列を含む
画像のサイズ設定
- 複数の Column を持つ
ColumnSet
内のイメージを使用する場合は、イメージ自体ではなく、イメージを含む列のサイズを指定します。 - イメージが
ColumnSet
にない場合は、そのサイズをauto
またはstretch
に設定することをお勧めします。 - 明示的な幅をピクセル単位で定義する場合は、最も狭いカード幅の 3/4 を超えないようにします。
- 明示的なサイズをピクセル単位で定義する場合は、幅または高さに対して定義します。 任意の 1 つのパラメーターに明示的なサイズを設定すると、イメージの縦横比が保持されます。
- イメージの幅を設定することをお勧めしますが、一部のシナリオでは例外が発生する可能性があります。
- 複数の Column を持つ
チーム会議用のプラグインを作成する方法の詳細については、「会議の Copilot のプラグインとしてメッセージ拡張機能を有効にする」を参照してください。
技術的要件
プラグインを検証、呼び出し、シームレスに動作させるには、次の条件を満たしていることを確認します。
条件 | 履行 |
---|---|
マニフェストのバージョン | アプリ マニフェストのバージョンは 1.13 以降である必要があります。 [必須] |
Microsoft 365 チャネル | ユーザーが Outlook からメッセージ拡張機能を操作するには、Microsoft 365 チャネルをボットに追加する必要があります。 詳細については、「 Microsoft 365 チャネルの追加」を参照してください。 [必須] |
応答時間 | 応答時間は、99% の場合は 9 秒、75% の場合は 5 秒、50% の場合は 2 秒を超えてはなりません。 [必須] |
信頼性 | アプリは 99.9% の可用性を維持する必要があります。 たとえば、Microsoft 365 Chat がプラグインを 1,000 回呼び出す場合、意味のある応答を 999 回提供する必要があります。 [必須] |
ゼロ回帰 | 検証のためにアプリを再送信する必要がある場合は、以前に動作していた既存のメッセージ拡張機能の機能を中断しないでください。 この要件は、組織向けに構築されたアプリではなく、独立系ソフトウェア ベンダー (ISV) アプリにのみ適用されます。 [必須] |
シングル サインオン (SSO) | 該当する場合は、SSO の Microsoft Entra ID アプリ登録を更新します。 [推奨] |
コンテンツ セキュリティ ポリシー | 該当する場合は、コンテンツ セキュリティ ポリシー ヘッダーを変更します。 [推奨] |
重要
該当する場合は、コンテンツ セキュリティ ポリシー ヘッダーの構成に従ってコンテンツ セキュリティ ポリシー ヘッダーと X-Frame-Options
を更新 します。
コード サンプル
サンプルの名前 | 説明 | TypeScript |
---|---|---|
Northwind インベントリ メッセージ拡張機能 | このサンプルでは、Microsoft Copilot for Microsoft 365 で Teams メッセージ拡張機能をプラグインとして使用する方法を示します。 | 表示 |
関連項目
Platform Docs
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示