重要
- Microsoft 365 Copilot 的代理处于预览状态，仅在 Microsoft 365 Copilot 中工作。
- 消息扩展代理以预览版提供。
- Microsoft 365 Copilot 中的消息扩展代理以公共预览版提供Microsoft Word和 PowerPoint。
- 确保 Microsoft 365 Copilot 可供组织使用。 可通过两种方式获取 Microsoft 365 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"
}]
下面是定义参数时可以调整的最佳做法：
- 必须明确定义参数，以确保代理的准确响应。 Copilot 使用这些说明来选择最佳命令，并根据用户查询预测参数值。
- 参数说明不得包含语法和标点符号错误。
- 清单中定义的参数不能相同。
增强消息扩展以通过复合言语检索信息
注意
Microsoft 365 Copilot 不支持在 TeamsJS v1.x) 中搜索对话 (称为任务模块。
对于 Microsoft 365 Copilot，基于搜索的消息扩展必须支持三个以上唯一的复合话语才能对准确信息执行深度检索。 若要启用复合陈述，必须通过更新 [应用清单 (以前称为 Teams 应用清单) ]/microsoft-365/extensibility/schema/#composeextensionscommands) ，扩展搜索范围以处理三个或多个参数，并确保以下各项：
更新 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 提供更多技能和知识来自定义和扩展 Microsoft 365 Copilot 体验，从而获得个性化的用户体验。 通过使用代理（代理的子集），用户可以通过与第三方应用程序交互（无论是检索或修改这些应用中的信息）来将其他功能集成到 Microsoft 365 Copilot 中。 例如，消息扩展代理有助于在其他应用程序中搜索数据，以便 Microsoft 365 Copilot 可以在激活代理时根据请求提供它。
如果你已为Teams 中的 Microsoft 365 Copilot或 copilot.microsoft.com 开发了代理，则你已经知道它在其工作流中为用户提供的好处。
代码示例
| 示例名称 | Description | TypeScript |
|---|---|---|
| Northwind 清单消息扩展 | 此示例实现一个 Teams 消息扩展，该扩展可用作 Microsoft 365 Copilot 的插件。 消息扩展允许用户查询 Northwind 数据库。 | View |