Copilot 代理是适用于 Microsoft 365 的应用

项目
10/22/2024

重要

API 插件目前仅支持作为声明性代理中的操作。智能 Microsoft 365 Copilot 副驾驶®中未启用它们。有关演示如何将 API 插件添加到声明性代理的示例，请参阅添加插件。
默认情况下，此功能在所有智能 Microsoft 365 Copilot 副驾驶®许可的租户中处于启用状态。管理员可以基于用户和组禁用此功能，并控制各个插件的批准使用方式以及启用哪些插件。有关详细信息，请参阅在集成应用中管理 Copilot 代理。

生成 Copilot 代理时，还会生成适用于 Microsoft 365 的应用。 Microsoft 365 的应用共享通用清单架构和打包格式，以及统一的分发和管理流程和工具。最终结果是你的应用和 Copilot 代理能够覆盖尽可能广泛的受众，并在用户的工作流中以上下文方式显示。

本文将引导你完成用于 Copilot 代理开发的 Microsoft 365 应用模型的关键部分。

Microsoft 365 的应用模型

Microsoft 365 生态系统正在发展成为一个集成的应用平台，你可以在其中使用通用应用模型来定义和打包应用。最初是扩展 Teams 应用以在其他 Microsoft 365 应用程序中运行的一种方式，此后已扩展为支持分发 Microsoft Graph 连接器、 Outlook 外接程序，现在为 Copilot 代理提供支持。

应用包

Microsoft 365 的应用包（包括 Copilot 代理）是一个 zip 文件，其中包含一个或多个配置 (清单) 文件和应用图标。应用逻辑和数据存储托管在其他地方，并由 Microsoft 365 主机应用程序通过 HTTPS 进行访问。你将向管理员提交应用包，以便发布到组织或合作伙伴中心，以发布到 Microsoft AppSource。

应用包至少包含：

应用清单 (manifest.json) ，其中描述了应用配置、功能、所需的资源和重要属性，
一个大的颜色图标 (color.png) ，一个全彩 92x92 图标，用于在Microsoft Copilot UI 和存储中显示代理，以及
) (outline.png一个小轮廓图标，这是一个具有透明背景的 32x32 图标， (当前未在 Copilot 中使用，但需要通过验证)

应用包还可以包含声明性代理和 API 插件定义，以及适用于其他受支持语言的本地化文件。

显示Microsoft 365 应用包剖析的关系图：应用清单 (.json 文件) + 图标 (颜色和轮廓 .png 文件) 包装在 .zip 文件中

应用图标

应用包必须同时包含应用图标的颜色和大纲版本，作为 .png 文件。这些图标具有特定的大小要求，以便通过存储验证。

注意

目前，只有颜色图标用于向最终用户表示 Copilot 代理 (作为其应用商店一览和智能 Microsoft 365 Copilot 副驾驶® UI) ，但在将应用包提交到 Microsoft AppSource 时，仍需要大纲图标。

有关 Microsoft 365 应用包的颜色和大纲图标的进一步设计指南，请参阅 Teams 应用商店的应用图标和应用栏。

彩色图标

颜色图标表示Microsoft Copilot UI 和产品内 (Teams、Outlook Microsoft 365) 应用商店中的代理。

颜色图标：

可以是任何颜色
必须为 192 x 192 像素
符号本身应为 96 x 96 像素， (，以允许 48 像素填充主机方案，其中裁剪)
必须坐在完全纯色或完全透明的正方形背景上

大纲图标

大纲图标用于表示 Teams 应用栏上的固定应用和/或活动应用。它当前不用于 Copilot 代理，但仍需要它才能使应用包通过验证。

大纲图标：

必须为 32 x 32 像素
必须具有透明背景的白色或具有白色背景的透明
不得在符号周围包含其他填充

应用部件清单

Microsoft 365 的应用清单是描述应用的功能和特征的 JSON 文件。 Microsoft 365 的应用清单的核心是用于构建 Teams 应用的架构，但自版本 1.13 起，它已扩展 (，) 除了 Teams 之外，还定义了跨 Microsoft 365 主机运行的应用。

如果使用 Microsoft Copilot Studio 生成声明性代理，则会根据在创建过程中提供的信息为你生成应用清单。

每个应用清单都必须包含以下信息：

清单字段	说明
version	应用的版本号，格式为 MAJOR。次要。PATCH (semver 标准) 。
id	Microsoft应用程序注册门户 (apps.dev.microsoft.com) 生成的唯一标识符，采用 GUID 格式。
开发人员	有关开发人员的信息，包括名称、网站以及隐私策略和使用条款的链接。对于提交到 AppSource 的应用，值必须与合作伙伴中心应用提交表单中提供的值匹配。
名称	应用的名称，显示在应用程序主机中的最终用户。
description	针对用户的应用的简短和长说明。对于提交到 AppSource 的应用，这些值必须与 AppSource 条目中的信息匹配。
图标	颜色和大纲图标文件的相对路径。
accentColor	要与和一起使用的颜色，作为边框图标的背景，以 RGB 十六进制值表示，例如 `#4464ee`。
特定应用功能的定义	每个应用功能的定义，例如个人选项卡 (staticTabs) 、消息扩展 (composeExtensions) 或机器人。声明性代理和 API 插件在 copilotAgents 节点下定义。

以下示例显示了一个应用清单，其中占位符部分位于消息扩展和声明性代理应用功能的末尾：

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

若要了解详细信息，请参阅开发人员预览版应用清单架构参考。

`copilotAgents` 定义

声明性代理和 API 插件都有自己的定义架构。声明性代理的定义文件是从 copilotAgents 应用清单的对象引用的。

以下示例演示如何引用声明性代理：

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

API 插件的定义是从声明性代理定义引用的。

显示引用声明性代理清单和 API 插件清单的应用清单的关系图。声明性代理清单引用另一个 API 插件清单

请注意以下几点：

目前，每个应用清单仅支持一个声明性代理定义。每个声明性代理仅支持一个 API 插件。
使用 Copilot Studio 生成 Copilot 代理时，将为每个代理生成唯id一，作为整个应用清单生成的一部分。使用 Teams 工具包或自己的 IDE 生成代理时，可以根据自己的约定或友好名称自行分配 id 代理。

声明性代理清单

声明性代理清单包括 Copilot 响应说明、会话初学者示例提示、用于地面的数据源，以及代理能够执行的操作 (API 插件技能) 列表。

若要了解详细信息，请参阅智能 Microsoft 365 Copilot 副驾驶®的声明性代理清单架构。

API 插件清单

API 插件清单介绍了插件的功能，包括它支持的 API 及其可执行的操作。它还包括元数据，例如名称、说明、版本，以及对它与之交互的 REST API 的 OpenAPI 定义的引用。可以从声明性代理清单引用 API 插件，以在声明性代理体验中使用。

若要了解详细信息，请参阅智能 Microsoft 365 Copilot 副驾驶®的 API 插件清单架构。

本地化代理

本地化 Copilot 代理的方式与本地化应用清单中 (选项卡、机器人和消息) 扩展等其他功能的方式略有不同。

对于经典 Teams 应用功能和 Copilot 代理，每种语言) 使用相同的本地化文件 (。但是，虽然使用语言文件中的 JSONPath 表达式引用所有其他应用清单字段 () ，但仅使用字典键引用与 Copilot 代理相关的字段。与经典 Teams 应用功能（在应用清单本身中使用默认语言字符串）不同，本地化的 Copilot 代理需要默认语言的语言文件以及每种其他语言的语言文件。

显示应用清单、声明性代理清单和语言文件之间的关系的关系图，以便本地化 Copilot 代理

以下步骤演示如何支持除 Copilot 代理的默认) 之外的其他语言 (。

1. 使用标记化密钥更新 Copilot 代理清单 ()

使用标记化密钥更新声明性代理和/或 API 插件清单， (用双方括号指示，例如 [[PLUGIN_NAME]] ，要本地化的任何字段值) 。本地化键与此正则表达式非常匹配： ^[a-zA-Z_][a-zA-Z0-9_]*$

以下示例显示了声明性代理清单，其中包含其名称和说明的标记化值：

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. 添加到 `localizationInfo` 应用清单

localizationInfo将部分添加到应用清单，其中包含语言标记和应用包中每个受支持的语言文件的相对路径。

如果 Copilot 代理支持多种语言，则必须为每个受支持的语言（ 包括默认语言）指定独立语言文件。

以下示例显示了应用清单中的本地化信息部分：

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

如果 Copilot 代理不支持其他语言，则默认语言字符串在应用清单文件本身中表示。 (单语言应用包不需要为默认语言使用单独的语言文件。)

3. 为每种语言创建本地化文件

使用上一步中为应用清单中) (指定的文件名和file属性，为defaultLanguageFile每种其他受支持的语言创建本地化文件，其中包含标记化密钥的值。

以下示例显示了一个语言文件 fr.json，其中包含 Copilot 代理和个人选项卡的本地化字符串：

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

应用清单中的可本地化字段

对于每个语言文件，请从应用本地化架构中指定需要本地化的以下属性：

清单字段	说明	最大长度	必需
`@schema`	本地化架构的 URL。对于 Copilot 代理，请使用 devPreview： `https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`。应用程序清单和本地化文件的清单架构版本必须相同。		✔️
`name.short`	将应用清单中的短名称替换为提供的值。	30 个字符	✔️
`name.full`	将应用清单中的全名替换为提供的值	100 个字符	✔️
`description.short`	将应用清单中的简短说明替换为提供的值。	80 个字符	✔️
`description.full`	将应用清单中的完整说明替换为提供的值。	4000 个字符	✔️
Copilot 代理中本地化字符串的键值对	对于 Copilot 代理，请使用应用 `manifest.json`中指定的标记化密钥 (，但不使用双方括号) 其本地化值。例如：`"DA_Name": "Agent de Communications"`
任何其他应用组件的本地化字符串的 JSONPath/值对	对于所有其他 (经典 Teams) 应用组件，请使用 JSONPath 表达式作为本地化值的键。例如：`"staticTabs[0].name": "Accueil"`

若要了解详细信息，请参阅本地化应用 (Microsoft Teams) 和本地化架构参考。

声明性代理清单中的可本地化字段

以下字段可在声明性代理清单中本地化：

清单字段	说明	最大长度	必需
`name`	声明性代理的名称。必须至少包含一个非空格字符。	100 个字符	✔️
`description`	声明性代理的说明。必须至少包含一个非空格字符。	1,000 个字符	✔️
`conversation_starters`	一个列表 (数组) 声明性代理可以回答的问题示例，其中每个示例由一个对象`titletext`表示，两者都是可本地化的。	数组中的 6 个对象

若要了解详细信息，请参阅声明性代理清单参考。

API 插件清单中的可本地化字段

以下字段可在 API 插件清单中本地化：

清单字段	说明	最大长度	必需
`name_for_human`	插件的简短用户可读名称。它必须至少包含一个非空格字符。	20 个字符	✔️
`description_for_model`	为模型提供的插件的说明，包括插件的用途，以及其函数在什么情况下相关。	2048 个字符
`description_for_human`	插件的可读说明。	100 个字符	✔️
`logo_url`	用于提取可由业务流程协调程序使用的徽标的 URL。
`legal_info_url`	一个绝对 URL，用于查找包含插件服务条款的文档。
`privacy_policy_url`	一个绝对 URL，用于查找包含插件隐私策略的文档。

若要了解详细信息，请参阅 API 插件清单参考。

通过

Copilot 代理是适用于 Microsoft 365 的应用

Microsoft 365 的应用模型

应用包

应用图标

彩色图标

大纲图标

应用部件清单

`copilotAgents` 定义

声明性代理清单

API 插件清单

本地化代理

1. 使用标记化密钥更新 Copilot 代理清单 ()

2. 添加到 `localizationInfo` 应用清单

3. 为每种语言创建本地化文件

应用清单中的可本地化字段

声明性代理清单中的可本地化字段

API 插件清单中的可本地化字段

另请参阅

反馈

其他资源

通过

Copilot 代理是适用于 Microsoft 365 的应用

Microsoft 365 的应用模型

应用包

应用图标

彩色图标

大纲图标

应用部件清单

copilotAgents 定义

声明性代理清单

API 插件清单

本地化代理

1. 使用标记化密钥更新 Copilot 代理清单 ()

2. 添加到 localizationInfo 应用清单

3. 为每种语言创建本地化文件

应用清单中的可本地化字段

声明性代理清单中的可本地化字段

API 插件清单中的可本地化字段

另请参阅

反馈

其他资源

`copilotAgents` 定义

2. 添加到 `localizationInfo` 应用清单