创建和升级 Copilot 代理的指南
重要
- 用于智能 Microsoft 365 Copilot 副驾驶®的插件处于预览状态，仅在智能 Microsoft 365 Copilot 副驾驶®中工作。
- 消息扩展插件以预览版提供。
- 智能 Microsoft 365 Copilot 副驾驶® 中的消息扩展插件为 Microsoft Word 和 PowerPoint 的公共预览版。
- 确保智能 Microsoft 365 Copilot 副驾驶®可供组织使用。 可通过两种方式获取用于智能 Microsoft 365 Copilot 副驾驶®的开发人员环境：
- 沙盒Microsoft 365 租户，智能 Microsoft 365 Copilot 副驾驶® (通过 TAP 成员资格) 以有限预览版提供。
- 具有智能 Microsoft 365 Copilot 副驾驶®许可证的企业客户生产环境。 有关 Copilot 代理在 Team Store 上列出的机会的验证指南的详细信息，请参阅 Copilot 代理的验证准则。
Microsoft 365 插件提供与各种Microsoft 365 产品的集成，例如 Teams 和 Outlook。 集成可帮助用户在外部系统中搜索或创建内容。 消息扩展插件允许智能 Microsoft 365 Copilot 副驾驶®通过机器人与其他软件和服务的 API 进行交互。 使用 智能 Microsoft 365 Copilot 副驾驶®，可以：
- 搜索最新信息或记录。 例如，最新的事件票证或调查结果。
- 基于多个记录汇总信息。 例如，汇总与项目 Northwind 相关的所有事件票证。
建议生成或升级现有消息扩展，以在智能 Microsoft 365 Copilot 副驾驶®中最大化其有用性和可用性。 消息扩展必须支持一个或多个搜索命令。 由于智能 Microsoft 365 Copilot 副驾驶®将其识别为技能，因此它可以代表用户执行命令。
定义应用、命令和参数说明
[必须修复]
良好的说明提供对应用功能的清晰而简洁的摘要，并允许智能 Microsoft 365 Copilot 副驾驶®有效地发现和执行搜索操作。 当用户输入应用名称和谓词（例如 Find Contoso 票证）时，必须从 智能 Microsoft 365 Copilot 副驾驶®调用消息扩展插件。
应用说明
长篇和短的应用说明必须清晰明了，并定义了应用的范围。 若要在 智能 Microsoft 365 Copilot 副驾驶® 中将应用呈现为插件，请修改应用说明以满足以下插件要求：
- 长说明必须清楚地说明智能 Microsoft 365 Copilot 副驾驶®中消息扩展插件的功能和用法。 例如，在 智能 Microsoft 365 Copilot 副驾驶® 中使用 Contoso 云搜索和汇总任务。
- 简短说明必须以自然语言简要描述应用的功能，并且可以包含应用的名称。
以下代码片段显示了每个类别的简短说明示例：
说明：创建、搜索、查看票证、bug 和项目。
应用说明示例：
{
"$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留空，智能 Microsoft 365 Copilot 副驾驶®将使用 字段中的信息description。 编写 时， semanticDescription必须包含有关命令的预期值、限制和范围的信息。
属性 semanticDescription 不是必填字段。 但是，如果在 semanticDescription 应用清单中添加，则对简短说明、参数说明和命令说明的现有验证检查也适用于语义说明。
以下代码片段显示了每个类别的命令和语义说明示例：
说明：搜索明天到期的与 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"
],
重要
若要激活插件中的 OAuth 登录链接，请确保将 应用清单中的搜索命令的 属性true设置为 initialRun 。
参数说明
每个消息扩展命令都有一个相应的 parameters 属性，该属性最多支持五个参数。 第一个参数必须在邮件扩展搜索栏中可见。 参数必须具有良好的说明，该说明必须包含可接受的参数、枚举、首字母缩略词和输出格式的组合。
semanticDescription 属性用于为智能 Microsoft 365 Copilot 副驾驶®提供命令的详细说明。 参数的语义说明最多支持 2,000 个字符，并且不会显示在用户界面中。 如果 属性semanticDescription留空，智能 Microsoft 365 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"
}]
增强消息扩展以通过复合言语检索信息
[必须修复]
注意
智能 Microsoft 365 Copilot 副驾驶®不支持通过对话 (TeamsJS v1.x 中称为任务模块) 搜索。
对于智能 Microsoft 365 Copilot 副驾驶®，基于搜索的消息扩展必须支持三个以上唯一的复合话语才能对准确信息执行深入检索。 若要启用复合陈述，必须通过更新 以前称为 Teams 应用清单的应用清单 () 来扩展搜索范围以处理三个或多个参数，并确保以下各项：
更新 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"
}
]
}
]
搜索参数必须具有可接受的参数、枚举、首字母缩略词和输出格式的良好说明。 有关详细信息和示例，请参阅 参数说明。
定义示例提示
[必须修复]
属性samplePrompts指导用户如何使用智能 Microsoft 365 Copilot 副驾驶®中的各种插件。 智能 Microsoft 365 Copilot 副驾驶®使用示例提示显示用户的提示。 提示必须能够适应不同的区域设置，并跨不同的命令清除。 当用户首次安装或启用插件时，智能 Microsoft 365 Copilot 副驾驶®内的首次运行体验 (FRE) 提供了示例提示。
注意
- 如果应用清单未指定
samplePrompts属性，则不会显示提示。 - 在
samplePrompts应用提交过程中，属性对于应用验证是必需的。 - 如果为应用定义多个命令，则最多向用户显示三个提示 (前三个命令中的每一个提示) 。 提示会轮换，以跨不同的命令为用户提供一组不同的提示。
以下代码是应用清单中的 属性的示例 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}" } } }注意
数据对象不支持 操作
messageBack类型和imBack。建议使用以下操作类型：
-
Action.OpenUrl：从卡打开指定的 URL。 -
Action.ToggleVisibility：显示或隐藏卡中的一个或多个元素。 -
Action.Execute：收集输入字段，并将其作为请求发送到机器人服务。 -
Action.Submit：使用数据对象中的类型调用打开对话框或 Stageview。
-
如果用户可以通过对话框、Stageview 或直接从卡更改有关卡的信息，我们建议自适应卡片支持通用操作和自动刷新。 [推荐]
自适应卡片必须包含 URL 作为 元数据的一部分，这允许将卡片从一个中心轻松复制到另一个中心。 [推荐]
除缩略图外，自适应卡片中的任何图像都必须具有替换文字。 [推荐]
智能 Microsoft 365 Copilot 副驾驶®应用中的消息扩展插件
[必须修复]
重要
智能 Microsoft 365 Copilot 副驾驶®应用中的消息扩展插件在 Word 和 PowerPoint 中处于受限的私人预览版中。 公布公共预览版后将发布的更多详细信息。
Copilot 代理通过提供更多技能和知识来自定义和扩展智能 Microsoft 365 Copilot 副驾驶®体验，智能 Microsoft 365 Copilot 副驾驶®个性化用户体验。 通过使用插件（作为 Copilot 代理的子集），用户可以通过与第三方应用程序交互（无论是检索或修改这些应用中的信息）将其他功能集成到智能 Microsoft 365 Copilot 副驾驶®。 例如，消息扩展插件有助于在其他应用程序中搜索数据，以便在激活插件时，智能 Microsoft 365 Copilot 副驾驶®可以根据请求显示数据。
如果你已经为 Teams 或 copilot.microsoft.com 中的智能 Microsoft 365 Copilot 副驾驶®开发了一个插件，则你已经知道它为其工作流中的用户带来的好处。
代码示例
| 示例名称 | Description | TypeScript |
|---|---|---|
| Northwind 清单消息扩展 | 此示例演示如何在 智能 Microsoft 365 Copilot 副驾驶® 中使用 Teams 消息扩展作为插件。 | View |