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

2025-04-05

声明性代理根据组织的特定需求定制智能 Microsoft 365 Copilot 副驾驶®。使用 Microsoft 365 Agents Toolkit (Teams 工具包) 演变生成声明性代理时，可以通过 API 插件向代理添加技能。 API 插件使代理能够通过 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 。	用户：“天气如何？” 代理：“你的位置是什么？” 用户：“London” 代理：“你更喜欢公制单位还是英制单位的天气信息？” 用户：“指标” 代理：“你需要今天的天气还是明天的天气预报？” 用户：“Today” 代理：“我将检查今天的伦敦天气” 代理调用：getWeather (___location=“London”， forecast=“today”， system=“Metric”)

代理说明

代理流

如果用户询问天气：

- 询问用户位置。
- 询问用户预测日期。
- 向用户询问单位系统。
- 仅在收集所有值时调用 getWeather 。

用户：“天气如何？”
代理：“你的位置是什么？”
用户：“London”
代理：“你更喜欢公制单位还是英制单位的天气信息？”
用户：“指标”
代理：“你需要今天的天气还是明天的天气预报？”
用户：“Today”
代理：“我将检查今天的伦敦天气”
代理调用：getWeather (___location=“London”， forecast=“today”， system=“Metric”)

有关代理说明的一般最佳做法，请参阅编写有效说明。

链接 API 插件中的函数调用

链接函数调用允许声明性代理在一个无缝流中合并多个 API作。以下部分介绍常见模式以及如何为每个模式编写说明。

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

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

在以下示例中，具有天气 API 和 To-do API 的声明性代理使用天气预报中的数据创建一个任务。

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

基于一个代理中的聊天历史记录链接

使用基于聊天历史记录的链接时，代理会使用先前的响应来处理后续作。此方法使用对话历史记录来维护上下文。

在以下示例中，代理按名称删除一个要办事项。

代理说明	代理流
1. 当用户要求列出所有待办事项时，调用 getTasks 以检索具有标题和 ID 的待办事项列表。 2. 列出待办事项后，如果用户要求删除待办事项，请使用响应中的 ID 调用 deleteTask。	用户： “显示 Tasks 文件夹中的所有任务？” 代理： alls getTasks (folderId=“Tasks”) 并显示所有具有 ID 的要办事项。用户： “删除 TaskMaster Pro 要办事项” 代理：使用对话历史记录中的信息查找要完成的 ID，并通过调用 deleteTask 删除要办事项。

链接与 SharePoint 知识

链接 API 调用允许代理将知识源和作组合在一起，以设计更复杂的工作流。

在以下示例中，代理从 SharePoint 检索项目状态数据，并在 Microsoft To-Do 中创建相应的任务以供跟踪。

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

使用代码解释器链接

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

在以下示例中，代理基于要完成的任务中的数据创建图表。

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

此示例还一次运行多个作。这在启动一系列不需要多个用户输入的相关作时很有用。

通过