使用声明式代理与 Microsoft 365 应用中的文档交互

在 Microsoft 365 应用中的 Copilot 体验中使用声明性代理时,它们能够与打开的文档交互。 默认情况下,代理可以阅读整个打开的文档。 用户只能向代理提供打开文档的选定部分,代理可以将图像插入打开的文档中。

本文介绍声明式代理的文档交互,不支持 Word 或 PowerPoint 中的完整插件包。 有关更广泛的插件模型,请参阅适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的插件。

注意

仅 Word 支持访问文档选择。 Word 和 PowerPoint 支持访问整个打开的文档和插入图像。

访问整个打开的文档

当用户在提示中引用打开的文档时,文档的内容会自动添加到提示中,允许代理访问它,而无需进一步的用户操作。 例如,用户可以提示代理“汇总此文档”或“在此文件中查找任何操作项”。

文档格式

提供给代理的信息的格式因文件类型而异。

对于 Word 文档,提供给代理的上下文完全由纯文本内容组成,包括标题、正文段落和列表元素。 文档的逻辑流通过顺序分块保留,允许代理根据文本模式推断文档结构。 不会捕获表格、图表、图像、页面格式和样式等非文本元素。 此类视觉对象的提及以及相邻的元数据可作为上下文的一部分提供,但代理无权访问其实际内容。

对于 PowerPoint 演示文稿,提供给代理的上下文包括所有可见的幻灯片标题、正文以及表格和图像的扁平描述(如果可用)。 通过顺序索引来维护幻灯片流和逻辑叙述。 不会捕获图像、复杂图表、背景设计、过渡、超链接和详细的演讲者备注等非文本元素。 因此,虽然代理可以对文本内容和视觉元素的高级描述进行推理,但它无法访问富媒体、详细的视觉布局和结构化图形数据。

在代理中使用打开的文档

默认情况下,声明式代理有权访问打开的文档。 无需更改代理即可启用对此功能的支持。

在 API 插件中使用打开的文档

如果代理将 API 插件 包括为自定义操作,则代理会根据 API 说明和向代理提供的说明来决定将多少打开的文档发送到 API。 有关详细信息,请参阅 文档内容的 API 插件注意事项。

Access 文档选择

文档选择功能允许用户向声明式代理提供打开文档的当前选定部分。 用户可以向代理询问选择,或要求代理根据它采取行动。

例如,用户正在处理职位描述文档,并希望在文档中添加 AI 生成的图像以添加一些视觉吸引力。 用户首先选择文档的一部分作为图像的上下文。 选择文档的一部分会启用 Copilot 聊天窗格中的“ 添加选择 ”按钮。

Word 中的 Copilot 的屏幕截图,其中显示了“添加选择”选项

用户选择添加 选择 ,然后要求代理根据所选内容 生成图像 。

Word 中的 Copilot 的屏幕截图,其中显示了用户提示,包括文档选择

代理生成图像并响应用户。

Word 中的 Copilot 的屏幕截图,其中显示了生成的图像

在智能体中使用文档选择

默认情况下,声明式代理有权访问文档选择。 无需更改代理即可启用对此功能的支持。

在 API 插件中使用文档选择

如果代理将 API 插件 包含为自定义操作,则代理可以向 API 提供文档选择。 代理根据 API 规范翻译文档选择。

文档内容的 API 插件注意事项

对于整个文档或用户选择,代理决定如何最好地将数据传递给 API 插件。 应确保针对 API 正确翻译文档或用户选择。

  1. 首先测试代理,无需向代理添加任何特殊说明。 在大多数情况下,代理应针对你的 API 适当地翻译文档内容或用户选择,而无需任何额外配置。
  2. 如果您的代理未针对您的 API 进行适当的转换,请在插件清单的 reasoning状态对象 中添加说明,以指示代理选择哪种形式。
  3. 测试各种选择,以验证您的代理是否适当地处理不同类型和长度的内容。

以下是一些影响代理如何翻译文档内容或用户选择的说明示例。 获得所需结果所需的实际指令取决于代理和 API。

逐字记录直通示例
You **MUST** pass the exact user's current selection without any modifications as part of the `text` param.
摘要/转换示例
You **MUST** pass the short, summarized version of the user's current selection as `prompt`
instead of the entire selected document context.
结构化提取示例
You **MUST** pass the structured version of the user's current selection as part of the `data` param.
You should get the required context from the user's current selection based on the user's query and
**MUST** structure the context in JSON format.

插入图像

图像插入功能允许用户将代理中的图像插入打开的文档中。 可以在当前光标位置、文档顶部或文档底部插入图像。

例如,从外部图像存储库检索图像的代理可以向用户显示用于插入图像的按钮。

Word 中的 Copilot 的屏幕截图,其中显示了具有插入图像功能的代理

插入代理的图像

在声明式代理中启用图像插入需要使用 自适应卡响应模板的 API 插件。 自适应卡片模板包括 Action.InsertImage 用户选择插入图像的操作。

{
  "type": "ActionSet",
  "actions": [
    {
      "type": "Action.InsertImage",
      "title": "Insert",
      "altText": "An image of people on the beach",
      "url": "https://contoso.com/images/beach.jpeg",
      // fallback MUST be set to "drop"
      "fallback": "drop",
      // Other valid values: "Top", "Bottom"
      "insertPosition": "Selection"
    }
  ]
}

注意

支持的图像类型为 .bmp、.gif、.jpeg、.jpg 和 .png。