将 Copilot 代理与 Office 外接程序 (预览版)

2025-06-10

注意

本文假设你熟悉 Copilot 声明性代理。如果不是，请从以下各项开始：

在 Office 外接程序中包含智能 Microsoft 365 Copilot 副驾驶® 代理具有两个优势：

Copilot 成为加载项功能的自然语言界面。
代理可以将参数传递给它调用的 JavaScript，当从按钮或菜单项调用函数命令时，这是不可能的。

还可以将 Office 加载项视为 Copilot 代理中的技能。由于 Office 外接程序使用 Office JavaScript 库对 Office 文档执行读取和写入作，因此这些作将成为 Copilot 代理中的作。

应用场景

以下是添加 Copilot 代理可增强加载项对用户价值的一些选定方法。

了解如何使用加载项：当用户需要通过加载项执行多个步骤或任务来实现某个目标时，Copilot 的聊天界面可以简化加载项入门过程。例如，假设一家法律公司需要有一个关于它准备的每个租约必须回答的问题列表。创建此问题列表可能既耗时又费力。但是，系统可能会提示使用 Office JavaScript 库的 Copilot 代理生成问题的第一个草稿列表，并将其插入到Word文档中。
内容分析：代理可用于分析文档或电子表格的内容，并根据找到的内容采取措施。示例如下。
- 代理分析“建议请求”，然后从后端系统获取 RFP 中问题的答案。用户只需提示代理“填写你知道的问题答案”。
- 代理在文档本身或客户业务系统的其他位置分析文档或电子表格中的表，以查找必须执行某些作的内容。用户可能会说“查看文档以查找我在审核列表中错过的任何项目。
受信任的数据插入：如果提示具有问题的典型 AI 引擎，它将合并它找到的信息并撰写答案;一个可能会引入不准确之处的过程。但是，基于加载项的 Copilot 代理可以插入来自受信任源的 原样数据 。例如：
- 考虑一个加载项，它允许将法律研究插入到Word，然后可以对其进行编辑。一位用户提示代理：“在什么情况下，出租人可以单方面破坏印第安纳州的住宅空间租赁？然后，加载项会从先例和法规中获取未更改的内容。
- 请考虑管理数字资产清单的加载项。在 Copilot 代理聊天中，用户提示：“插入一张彩色照片表，其中包含每个照片的名称、下载次数以及大小（以兆字节为单位），按下载次数排序。”然后，加载项从记录系统提取此数据（未更改），并将表格插入 Excel 电子表格中。

Copilot 代理与外接程序框架的关系

Copilot 代理是外接程序的自然语言界面。

可以将加载项配置为仅是 Copilot 代理中的技能。它不必包括任务窗格、自定义功能区按钮或自定义菜单;但它除了是 Copilot 技能之外，还可以具有其中任何一项。最佳方法取决于加载项应启用的用户方案。

如果外接程序应提供不需要向其传递参数的简单快速作，请在外接程序中包含自定义功能区按钮或菜单（称为外接程序命令）。
如果外接程序需要仪表板体验，需要用户配置设置，需要显示有关 Office 文档内容的元数据，或者出于任何其他原因需要类似页面的体验，请在外接程序中包含任务窗格。
如果外接程序需要提供复杂作，这些作需要在运行时传递参数或需要自然语言界面，请包含 Copilot 代理。

注意

目前，只有 Excel、PowerPoint 和 Word 加载项可以在 Copilot 中配置为技能。我们正在努力支持 Outlook。
Mac 版 Office 当前不支持 Copilot 代理。
外接程序必须使用 Microsoft 365 的统一清单，才能在 Copilot 中配置为技能。
内容加载项不能是 Copilot 中的技能。

主要任务

将加载项配置为 Copilot 技能有两个主要任务，这类似于为外接程序配置函数命令的两个任务。

创建实现代理作的 JavaScript 函数。
使用 JSON 为 Office 指定，JavaScript 运行时会指定这些函数的名称。

JSON 配置

将外接程序配置为 Copilot 技能需要以下小节中所述的三个 JSON 格式的文件。

Microsoft 365 的统一清单

清单有两个部分需要配置。首先，创建一个作对象，该对象标识由作调用的 JavaScript 函数。下面是一个示例 (，) 省略了一些无关标记。对于此代码，请注意以下事项。

“page”属性指定包含嵌入脚本标记的网页的 URL，该标记又指定定义函数的 JavaScript 文件的 URL。同一文件包含 Office.actions.associate 方法的调用，用于将函数映射到作 ID。
"actions.id"清单中的属性是传递给调用的associate相同作 ID。
属性 "actions.type" 设置为“executeDataFunction”，这是可以接受参数并可由 Copilot 调用的类型。

"extensions": [

    ...

    "runtimes": [
        {
            "id": "CommandsRuntime",
            "type": "general",
            "code": {
                "page": "https://localhost:3000/commands.html"
            },
            "lifetime": "short",
            "actions": [
                {
                    "id": "fillcolor",
                    "type": "executeDataFunction",
                }
            ]
        }
    ]
]

其次，创建一个声明性代理对象，该对象标识包含代理的详细配置的文件。示例如下。

"copilotAgents": {
    "declarativeAgents": [
        {
        "id": "ContosoCopilotAgent",
        "file": "declarativeAgent.json"
        }
    ]
}

清单 JSON 的参考文档位于 365 应用清单架构参考Microsoft。

声明性代理配置

代理配置文件包括代理的说明，并指定一个或多个 API 插件配置文件，其中包含代理作的详细配置。示例如下。请注意以下有关此 JSON 的内容。

对话启动器显示在 Copilot 的聊天画布中。
"actions.id"此文件中的属性是在中指定的文件中所有函数的"actions.file"集合 ID。它不必与清单中的匹配 "actions.id" 。

{
    "$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": "Excel-API-local-plugin.json"
        }
    ]
}

声明性代理的参考文档位于声明性代理架构 1.3 中，适用于智能 Microsoft 365 Copilot 副驾驶®。

Copilot API 插件配置

API 插件配置文件指定代理作意义上插件的“函数”，而不是 JavaScript 函数，包括作的说明。它还为 Copilot 配置 JavaScript 运行时。示例如下。关于此 JSON，请注意以下事项：

必须与 "functions.name" 外接程序清单中的属性匹配 "extensions.runtimes.actions.id" 。
"reasoning.description"和 "reasoning.instructions" 引用 JavaScript 函数，而不是 REST API。
属性 "responding.instructions" 仅向 Copilot 提供有关如何响应的指导。它不会对响应施加任何限制或结构要求。
数组 "runtimes.run_for_functions" 必须包含与相同的字符串 "functions.name" 或与其匹配的通配符字符串。
属性"runtimes.spec.local_endpoint"是新的，尚未包含在 API 插件架构main参考文档中。有关详细信息，请参阅下文。在这种情况下，它指定与“fillcolor”字符串关联的 JavaScript 函数在 Office 外接程序中可用，而不是在某些 REST 终结点中可用。 -属性"runtimes.spec.allowed_host"是新的，尚未包含在 API 插件架构的main参考文档中。有关详细信息，请参阅下文。在这种情况下，它指定代理应仅在 Excel 中可见。

{
    "$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 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 插件的参考文档位于 api 插件清单架构 2.3 for 智能 Microsoft 365 Copilot 副驾驶®。下面是属性的两个新属性 "runtimes.spec" 的文档。

属性	类型	说明
`local_endpoint`	String	可选。一组可用 JavaScript 函数的 ID。此属性大致类似于 `"runtimes.spec.url"` 属性，但对于客户端上的本地函数，而不是 REST API。目前，唯一允许的值是“Microsoft.Office.Addin”。
`allowed_host`	String	可选。指定哪些 Office 应用程序 Copilots 可以托管代理。可能的值为“document”、“mail”、“presentation”和“workbook”。

创建 JavaScript 函数

将由 Copilot 代理调用的 JavaScript 函数是在创建函数命令时创建的。示例如下。对于此代码，请注意以下事项。

与函数命令不同，与 Copilot作关联的函数可以采用参数。
方法的第一个参数associate必须与外接程序清单中的属性和 "functions.name" API 插件 JSON 中的属性匹配"extensions.runtimes.actions.id"。

async function fillColor(cell, color) {
    await Excel.run(async (context) => {
        context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
        await context.sync();
    })
}

Office.onReady((info) => {
    Office.actions.associate("fillcolor", async (message) => {
        const {cell, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

创建函数后，创建一个无 UI HTML 文件，该文件包含一个 <script> 标记，用于使用函数加载 JavaScript 文件。此 HTML 文件的 URL 必须与清单中属性的值 "extensions.runtimes.code.page" 匹配。请参阅本文前面的 Microsoft 365 统一清单。

对组合代理和加载项进行故障排除

下面是一些常见问题和建议的解决方案。

代理作失败，并显示一条消息，指示加载项中未找到该作。下面是一些可能的原因。
- "functions.name"插件 JSON 中的属性值与外接程序清单中的任何属性都不匹配"extensions.runtimes.actions.id"。
- 清单中有匹配 "actions.id" 项，但同一作对象的同级 "actions.type" 值不是“executeDataFunction”。
代理作失败，并显示一条消息，指示找不到作处理程序注册。下面是一个可能的原因。
- 加载项的 JavaScript 没有调用，Office.actions.associate第一个参数与插件 JSON 中的属性值完全匹配"functions.name"。

通过