将 Copilot 代理添加到 Office 外接程序可提供两个好处：
- Copilot 成为加载项功能的自然语言界面。
- 代理可以将参数传递给它调用的 JavaScript，当从按钮或菜单项调用 函数命令 时，这是不可能的。
注意
本文假设你熟悉概述 将 Copilot 代理与 Office 加载项相结合 ，以及它引用的 Copilot 文档。 我们还建议完成快速入门 ，生成第一个加载项作为 Copilot 技能。
重要
此功能需要 Microsoft 365 的统一清单。 如果外接程序使用仅外接程序清单，必须先 将其转换为使用统一清单 ，然后才能向其添加 Copilot 代理。 在继续阅读本文之前，应了解如何将清单和其他文件打包到应用包 zip 文件中，并将其旁加载到 Office 应用程序进行测试。
主要任务
以下是将 Copilot 代理添加到外接程序main任务。 详细信息在小节中。
- 为将实现 Copilot 代理作的代理作创建函数。
- 更新清单
- 创建代理和 API 插件配置
- 创建应用包
- 测试代理
- 在应用中进行更改
为代理的作创建函数
如果外接程序包含一个或多个 函数命令，则项目已有一个 JavaScript 或 TypeScript 文件，该文件定义这些命令的函数 (通常称为 commands.js 或 commands.ts) ，而无 UI 的 HTML 文件 (通常称为 commands.html) ，其中包含 <script> 用于加载函数文件的标记。 建议使用此相同的函数文件来定义代理作的函数。 跳到 更新函数文件部分。
创建源文件
如果项目尚没有此类文件，请使用以下步骤创建这些文件。 这些步骤中的文件夹和文件结构和名称不是必需的，但我们建议在适用的情况下尽量减少与加载项开发工具和配置的不兼容。
确保项目根目录中有一个文件夹 \src ，并且它具有名为 \commands 的子文件夹。
在 \commands 文件夹中创建commands.js(或.ts) 文件。 在后面的步骤中，将内容添加到其中。
在包含以下内容的 \commands 文件夹中创建commands.html文件。 关于此标记，请注意以下几点。
元素
<body>为空，因为该文件没有 UI。 它的唯一用途是加载 JavaScript 文件。将显式加载在上一步中创建的 Office JavaScript 库和 commands.js 文件。
注意
在 Office 外接程序开发中，通常使用 Webpack 及其插件等工具在生成时自动将标记注入
<script>HTML 文件。 如果使用此类工具，则不应在源文件中包含要由该工具插入的任何<script>标记。
<!DOCTYPE html> <html> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <!-- Office JavaScript Library --> <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script> <!-- Function command file --> <script src="commands.js" type="text/javascript"></script> </head> <body> </body> </html>
更新函数文件
使用以下步骤定义代理作的函数。 它们假定最常见的文件夹和文件结构和名称。
通常打开函数文件 ( ，\src\commands\commands.js (或.ts) ) 并添加实现代理作的函数。 在工作时，请记住以下几点。
- 与在 Office JavaScript 库中调用 API 的所有代码一样，文件必须 初始化库，通常通过调用 来初始化
Office.onReady库。 - 代理调用的函数采用一个
message参数，该参数指定 Office 在从 Office JavaScript 库调用函数时将使用的值。 可以使用 方法分析JSON.parse此对象。 对象的值由用户使用自然语言指定。 - 与使用外接程序命令调用的函数不同，这些函数没有
Office.AddinCommands.Event参数，并且不调用Office.AddinCommands.Event.completed方法。 相反，代理调用的函数将结果对象从 JavaScript 运行时返回给 Copilot 运行时。 - 与从函数命令调用的函数相比，从 Copilot 调用的函数完成时间更少。 后者有五分钟时间完成，或者 Office 关闭 JavaScript 运行时。 但是 Copilot 调用的函数只有两分钟的时间返回结果，或者运行时已关闭。
- 对于每个函数，必须调用 Office.actions.associate ，以告知 Office 在调用代理作时应运行文件中的哪个函数。 函数
associate将函数名称映射到在后续步骤的清单中配置的作 ID。 如果在同一文件中定义多个函数，则必须为每个函数调用associate代码。
示例如下。
Office.onReady(function() {
// Add any initialization code here.
});
async function fillColorFromUserData(message) {
const {Cell: cell, Color: color} = JSON.parse(message);
await Excel.run(async (context) => {
context.workbook.worksheets
.getActiveWorksheet()
.getRange(cell).format.fill.color = color;
await context.sync();
});
return "Cell color changed.";
}
Office.actions.associate("FillColor", fillColorFromUserData);
更新清单
配置 Copilot 代理的清单有三个主要部分，如以下小节中所述。
使用预览清单架构
确保清单使用以下步骤引用清单架构的预览版本。
在清单的顶部，确保
"$schema"属性如下所示："$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",确保 属性
"manifestVersion"设置为“devPreview”。
配置运行时
- 在数组中
"extensions.runtimes"，确保有一个面向运行无 UI JavaScript 函数的运行时对象。 至关重要的是，对象具有一个"code.page"属性，该属性指定你在更新函数文件之前创建 (或编辑) 的无 UI HTML 文件的绝对 URL。 -
"actions"在同一运行时对象的数组中，添加一个对象，该"type"对象的属性设置为“executeDataFunction”，其"id"属性与在更新函数文件中创建的函数中调用Office.actions.associate的第一个参数完全匹配。 - 对创建的每个函数重复上述步骤，以实现代理作。
运行时对象应如下所示。 运行时对象的其他属性、数组中的其他 "runtimes" 运行时对象以及数组中的其他 "actions" 作对象。
"runtimes": [
{
"id": "CommandsRuntime",
"type": "general",
"code": {
"page": "https://localhost:3000/commands.html"
},
"lifetime": "short",
"actions": [
{
"id": "FillColor",
"type": "executeDataFunction",
}
]
}
]
声明代理
如果还没有对象，请将 “copilotAgents” 对象添加到清单的根目录，并确保该对象具有子 “declarativeAgents” 数组。
将 对象添加到数组，
"declarativeAgents"并为其指定唯一和描述性"id"。为 对象的
"file"属性分配声明性代理配置文件的相对 URL。 在后面的步骤中创建该文件。示例如下。
"copilotAgents": { "declarativeAgents": [ { "id": "ContosoCopilotAgent", "file": "declarativeAgent.json" } ] },
提示
若要最大程度地提高外接程序开发Microsoft工具的兼容性，建议在项目的根目录中创建名为 appPackage 的文件夹，并将清单移到其中。
创建代理和 API 插件配置
在清单所在的同一文件夹中创建一个文件，并为其指定属性中使用的
"copilot.declarativeAgents.file"名称，例如 declarativeAgent.json。将以下内容粘贴到 文件中。
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json", "version": "v1.4", "name": "Excel Add-in + Agent", "description": "Agent for working with Excel cells.", "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.", "conversation_starters": [ { "title": "Change cell color", "text": "I want to change the color of cell B2 to orange" } ], "actions": [ { "id": "localExcelPlugin", "file": "Office-API-local-plugin.json" } ] }将属性值替换为适合外接程序的新值。 有关这些属性的详细信息，请参阅 声明性代理清单对象。
注意
在下一步中创建在 属性中指定的
"actions.file"文件。 在上面的示例中，这是 文件Office-API-local-plugin.json。使用清单在文件夹中创建另一个文件，并为其指定在上一步中分配给
"actions.file"属性的名称，例如 ，Office-API-local-plugin.json。将以下内容粘贴到 文件中。
{ "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json", "schema_version": "v2.3", "name_for_human": "Excel Add-in + Agent", "description_for_human": "Add-in Actions in Agents", "namespace": "addinfunction", "functions": [ { "name": "FillColor", "description": "fillcolor changes a single cell ___location to a specific color.", "parameters": { "type": "object", "properties": { "Cell": { "type": "string", "description": "A cell ___location in the format of A1, B2, etc.", "default" : "B2" }, "Color": { "type": "string", "description": "A color in hex format, e.g., #30d5c8", "default" : "#30d5c8" } }, "required": ["Cell", "Color"] }, "returns": { "type": "string", "description": "A string indicating the result of the action." }, "states": { "reasoning": { "description": "`FillColor` changes the color of a single cell based on the grid ___location and a color value.", "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format." }, "responding": { "description": "`FillColor` changes the color of a single cell based on the grid ___location and a color value.", "instructions": "If there is no error present, tell the user the cell ___location and color that was set." } } } ], "runtimes": [ { "type": "LocalPlugin", "spec": { "local_endpoint": "Microsoft.Office.Addin", "allowed_host": ["workbook"] }, "run_for_functions": ["FillColor"] } ] }除了稍后介绍的一些例外情况外，请将属性值替换为适合加载项的新值。 有关这些属性的详细信息，请参阅 api 插件清单架构 2.3 for 智能 Microsoft 365 Copilot 副驾驶®。
工作时，请记住以下几点。
请勿更改
"namespace"、"runtimes.type"或"runtimes.spec.local_endpoint"值。必须是
"functions.name"以下两项的完全匹配项：-
"extensions.runtimes.actions.id"清单中的属性 (类型为“executeDataFunction”的作 ) 。 - 在更新函数文件中创建的函数中调用
Office.actions.associate的第一个参数。
-
数组
"runtimes.run_for_functions"必须包含与 相同的字符串"functions.name"或与其匹配的通配符字符串。"reasoning.description"和"reasoning.instructions"引用 JavaScript 函数，而不是 REST API。属性
"runtimes.spec.local_endpoint"是新的，尚未包含在 API 插件架构main参考文档中。 有关详细信息，请参阅下文。 它告知 Copilot 代理在 Office 外接程序中查找函数，而不是在 REST 服务 URL 中查找函数。
创建应用包
重要
若要测试代理，如本文稍后在测试代理中所述，清单中任何绝对 URL 的域段必须是 localhost 域;例如 。 localhost:3000 稍后可以将这些段更改为生产域。
使用任何 zip 实用工具创建包含以下文件的 zip 文件。
- 清单
- 清单的 和 中引用的
"icons.color"图标文件"icons.outline" - 在创建代理和 API 插件配置中创建的两个文件
- 属性中
"localizationInfo.additionalLanguages"引用的任何文件
重要
其中大多数文件在清单中具有相对于清单位置的 URL，因此 zip 文件的文件夹结构必须维护此结构。 例如，如果 "icons.color" 值为“/assets/icon-32.png”，则 zip 文件中必须有一个 /assets 文件夹，其中包含 icon-32.png 文件。
提示
为了最大程度地提高Microsoft工具的兼容性，我们建议在 appPackage 文件夹中创建名为 build 的子文件夹，并在其中创建 zip 文件。
测试代理
以下小节介绍了测试代理的三个主要步骤（旁加载、启动服务器和运行代理）。
旁加载代理和加载项
即使应用中没有 Teams 功能，也可以通过 Teams 完成旁加载。 步骤如下。
- 关闭所有 Office 应用程序，然后按照手动清除缓存中的说明 清除 Office 缓存。
- 打开 Teams，从 应用 栏中选择“应用”，然后选择 “应用 ”窗格底部的“管理 应用 ”。
- 在“应用”对话框中选择“上传应用”，然后在打开的对话框中，选择“上传自定义应用”。
- 在“ 打开 ”对话框中，导航到包 zip 文件并选择包 zip 文件。
- 在打开的对话框中选择“ 添加 ”。
- 当系统提示你添加应用时， 请不要 在 Teams 中打开它。 相反，请关闭 Teams。
启动服务器
你的任务是启动托管项目的 HTML 和 JavaScript 文件的本地 Web 服务器。 如何执行此作取决于多个因素，包括项目的文件夹结构、使用的工具（如捆绑包、任务管理器、服务器应用程序）以及配置这些工具的方式。 由于你要向现有外接程序项目添加代理，因此已经知道如何执行此作。 以下说明仅适用于满足以下条件的项目。
项目的根目录中有一个 webpack.config.js 文件，该文件类似于使用 Yeoman Generator for Office 外接程序 或 Microsoft 365 代理工具包创建的外接程序项目中的文件。
项目的根目录中有一个 package.json 文件，与同一两个工具创建的类似，并且该文件包含一个“脚本”部分，其中包含以下脚本。
"dev-server": "webpack serve --mode development"
在命令提示符或项目根目录中Visual Studio Code终端中，运行 npm run dev-server 以在 localhost 上启动服务器。
运行代理
(Excel、PowerPoint 或组合代理和外接程序目标的Word) 打开 Office 应用程序。 等待加载项加载。 这可能需要多达两分钟的时间。 根据 Office 版本，功能区按钮和其他项目可能会自动显示。 在最新版本中，需要手动激活加载项：选择“主页”功能区上的“加载项”按钮，然后在打开的浮出控件中选择加载项。 它将具有清单中 属性的名称
"name.short"。从功能区中打开 Copilot ，然后在“ Copilot ”窗格中选择汉堡控件。 代理应位于代理列表中。 它具有声明性代理配置文件的 属性中指定的
"name"名称， (可能与清单) 中的属性的名称"name.short"不同，例如 Excel 代理。 可能需要选择“ 查看更多 ”，以确保列出所有代理。 如果未列出代理，请尝试以下一项或两项作。- 等待几分钟，然后重新加载 Copilot。
- 打开 Copilot 到代理列表后，单击 Copilot 窗口上的光标，然后按 Ctrl+R。
列出代理后，将其选中，将打开代理的窗格。 将显示你在声明性代理配置文件的 属性中
"conversation_starters"配置的会话启动程序。选择对话初学者，然后按窗格底部对话框中的 “发送 ”控件。 选择 “确认 ”以响应确认提示。 代理作发生。
尝试输入将提示对话框与对话启动器不同，但代理应该能够执行该作。
在应用中进行更改
预览版期间不支持合并的加载项和代理的实时重载和热重载。 若要进行更改，请先关闭服务器，然后通过以下步骤卸载代理和外接程序。
- 关闭 Office 应用程序。
- 如果 Web 服务器在Visual Studio Code终端中运行，请为终端提供焦点并按 Ctrl+C。 选择“Y”以响应结束进程的提示。 然后转到下一步。 如果 Web 服务器在单独的窗口中运行，请跳过此步骤并转到下一步。
- 在命令提示符下或Visual Studio Code项目根目录中的终端中，运行
npm run stop。 - 按照手动清除缓存中的说明 清除 Office 缓存。
- 打开 Teams，从 应用 栏中选择“应用”，然后选择 “应用 ”窗格底部的“管理 应用 ”。
- 在应用列表中查找代理。 它将具有声明性代理配置文件的 属性中指定的
"name"名称;例如， Excel 外接程序 + 代理。 - 选择名称左侧的箭头以展开其行。
- 选择行右端附近的垃圾桶图标，然后在提示符中选择“ 删除 ”。
进行更改，然后重复 测试代理中的步骤。
疑难解答
请参阅 对组合加载项和代理进行故障排除。