使用 API 插件编写声明式代理的有效说明

声明式代理定制智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®以满足组织的特定需求。 可以通过 API 插件添加自定义操作。 对于受支持的专业代码方案,建议使用 Work IQ Dev Tools 。 这些集成允许您的代理通过 API 查询组织的数据并与之交互;它们不是技能中描述的 可重用指令文件插件功能。

本文介绍代理体系结构,并提供为包含 API 插件的声明性代理编写说明的最佳实践。

具有 API 插件的声明性代理的主要组件

调用 API 插件的声明性代理包括多个确保有效集成和功能的组件。 了解此架构将有助于您有效地设计代理。 体系结构包括以下组件:

  • 应用程序清单 - 描述如何配置应用并引用声明性代理清单。
  • 声明性代理清单 - 定义代理的配置,包括说明、功能、对话发起子和操作。 引用插件清单。
  • 插件清单 - 描述插件配置,包括可用函数和对 OpenAPI 规范的引用。
  • OpenAPI 规范 - 提供 API 终结点的详细定义,包括路径、参数、请求和响应格式以及身份验证。

这些文件共同定义了代理的行为及其与基础 API 交互的方式。

显示四个清单文件的图示,这两个文件相互引用

有关 API 插件的详细信息,请参阅:

插件清单中的函数映射

在插件清单中,每个函数都必须映射到 OpenAPI 规范中相应的 operationId 。 这可确保当代理调用函数 (例如 createTask) 时,代理知道要调用哪个 API 终结点。

以下示例演示插件清单中的映射和 OpenAPI 规范中的映射函数。

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]
paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

代理说明的最佳实践

编写有效的说明对于确保具有 API 插件的声明性代理成功至关重要。 要优化代理,请应用正确的函数映射,使用链接来启用更丰富的交互,并迭代测试和完善代理的行为。

使用 API 插件编写声明式代理说明时,请应用以下最佳做法:

  • 避免模棱两可或消极的指令。 对比或否定指令可能会带来歧义并混淆模型。 重点通过积极的例子定义有效的用例。 如果区分有效和无效查询很重要,请提供明确的标准和示例来定义每个查询的预期代理响应。
  • 使用示例 提供清晰的示例来指导座席行为。 例如:

用户输入:布拉格的天气怎么样? 代理呼叫:getWeather (location=“Prague”) 用户输入:“我明天需要雨伞吗?” 代理呼叫:getWeather (location=user_location, forecast=“tomorrow”)

  • 查看并测试说明。 在各种场景中测试指令,以验证代理是否进行了正确的函数调用。 如果在测试中发现代理意外调用函数,请修改 OpenAPI 规范中的函数描述并阐明代理说明以改进意图映射。

  • 多轮对话的设计说明。 集成 API 插件时,请设计代理处理多轮对话的说明。

例如,如果函数需要多个参数,则除了在 OpenAPI 规范中定义所需的参数外,还可以指示代理在进行 API 调用之前收集所有参数。 这可确保代理按逻辑顺序收集所有必需的信息。

以下示例演示如何指示气象代理进行多轮对话以及由此产生的代理流。

代理说明 代理流
如果用户询问天气:

- 询问用户位置。
- 向用户询问预测日期。
- 向用户询问单位制。
- 仅在收集所有值时调用 getWeather 。
用户:“天气怎么样?”
Agent:“你的位置在哪里?”
用户:“London”
Agent: “您更喜欢公制还是英制单位的天气信息?”
用户:“公制”
代理:“您需要今天的天气还是明天的天气预报?”
用户:“今天”
代理:“我将检查今天伦敦的天气”
代理呼叫:getWeather (location=“London”, forecast=“today”, system=“Metric”)

有关代理说明的常规最佳做法,请参阅 编写有效说明。

在 API 插件中链接函数调用

通过链接函数调用,声明性代理可以将多个 API 操作组合在一个无缝流中。 以下部分介绍常见模式以及如何编写每个模式的说明。

将输出作为输入参数的链接函数调用

使用一个 API 调用的结果作为另一个 API 调用的输入。 当需要第一个函数的结果来执行第二个函数时,这很有用。 这可以跨插件工作。

在下面的示例中,具有天气 API 和待办事项 API 的声明性代理使用天气预报中的数据创建待办事项任务。

代理说明 代理流
要获取天气,请始终使用 getWeather 操作,然后创建一个标题为“temperature in”的任务,并将天气中提到的位置和温度添加到任务标题中。 用户: “获取布拉格的天气”
代理: 调用 getWeather (location=“Prague”, forecast=“today”)
代理: 使用第一次调用的数据创建待办事项任务 createTask (title =“{weather output}”)

基于一个代理内的对话历史记录进行链接

当您使用基于对话历史记录的链接时,代理将使用先前的响应来处理后续操作。 此方法使用对话历史记录来维护上下文。

在以下示例中,代理按名称删除待办事项。

代理说明 代理流
1. 当用户要求列出所有待办事项时,请调用 getTasks 以检索带有标题和 ID 的待办事项列表。
2. 列出待办事项后,如果用户要求删除待办事项,请使用响应中的 ID 调用 deleteTask。
用户: “显示'任务'文件夹中的所有待办事项?”
Agent: alls getTasks (folderId=“Tasks”) 并显示所有带有 ID 的待办事项。
用户: “删除任务大师专业待办”
代理: 使用对话历史信息查找待办事项的ID,并通过调用 deleteTask删除待办事项。

使用 SharePoint 知识链接

链接 API 调用允许代理结合知识源和操作来设计更复杂的工作流。

在以下示例中,代理从 SharePoint 检索项目状态数据,并在微软待办 中创建相应的任务进行跟踪。

代理说明 代理流
- 要获取项目状态,请使用 SharePoint 知识 ProjectDeadlines。
- 始终使用游戏的状态更新为每个项目创建待办事项。
用户:“能否提供所有项目状态的更新?”
Agent: 从 SharePoint 拉取项目状态数据,然后使用 createTask 为每个项目生成待办事项任务。

使用代码解释器链接

还可以链接 API 调用并集成其他功能,例如代码解释器。 这允许代理动态处理 API 输出以启用更高级的工作流。

在以下示例中,代理基于待办事项中的数据创建图表。

代理说明 代理流
当用户要求列出所有待办事项时,请调用 getTasks 以检索带有 title 和 ID 的待办事项列表,同时绘制输出图表。 用户: “检索任务中的所有任务”
代理: 调用 getTasks (folderId=“Tasks”) 并显示所有带有 ID 的待办事项。
Agent: 调用代码解释器,以便基于第一次调用的输出启动图表生成。

此示例还一次运行多个操作。 这对于启动不需要多个用户输入的一系列相关操作非常有用。

当代码解释器生成文件 ((如图表图像或电子表格) )时,Copilot 会自动在响应中提供下载链接,允许用户将文件保存在本地。 有关详细信息,请参阅 生成可下载文件。