API 插件使智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®代理能够与 Web 服务交互并访问实时信息。 API 插件允许用户通过自然语言命令与Copilot 对话助手内的代理 (LOB) 系统中的实时数据进行交互。
API 插件由 API 服务、其 OpenAPI 说明和清单文件组成。 插件清单通知 Copilot 业务流程协调程序有关 API 的功能的信息。 插件清单包括 API 服务的 OpenAPI 说明。 OpenAPI 说明很重要,因为它向 Copilot 描述了如何连接到 API。 为了通过 Copilot 实现最佳插件可发现性和性能,请提供清晰而有意义的 OpenAPI 说明。
本文介绍使 OpenAPI 说明对扩展 Copilot 代理功能的插件有效的元素。
OpenAPI 说明元素
本部分介绍 OpenAPI 说明的元素以及如何针对 Copilot 代理优化它们。
OpenAPI 验证:第一步是验证 OpenAPI 说明是否遵循 OpenAPI 规范的规则。 您可以使用 Hidi(一种可以在其他用例中验证 OpenAPI 说明的命令行工具)或任何其他选择工具。 有效的 OpenAPI 说明不仅适用于 Copilot,还可以确保 OpenAPI 说明可以与其他工具配合使用。
信息部分: 说明字段在 OpenAPI 规范中是可选的,但对于旨在扩展 Copilot 技能的 OpenAPI 说明至关重要。 Copilot 需要说明字段来了解 API 的作用以及何时使用插件。 从 OpenAPI 文档生成插件清单时,信息部分中的说明将用作插件清单的说明。 因此,始终具有简短明了的说明字段非常重要。 例如,下面是维修店 OpenAPI 说明的信息部分。
info:
title: Repair Service
description: A simple service to manage repairs for various items
version: 1.0.0
操作 ID: 增强 OpenAPI 说明可用性的一种有用技术是为 API 提供的 API 路径和 HTTP 方法的每种组合添加一个 operationID 。 操作 ID 是 API 中操作的唯一标识符,Copilot 使用它来创建在响应用户提示时执行的函数。
此外,请对 API 支持的每个操作添加有意义的说明。 在 Copilot 根据用户的提示和插件说明选择使用插件后,它会搜索路径的说明来确定用于满足用户请求的终结点。
操作 ID 在调试期间显示为函数,指示 Copilot 尝试执行哪些操作。 下面是 OpenAPI 文档的示例和相应调试器输出的示例:
paths:
/repairs:
get:
operationId: listRepairs
summary: List all repairs
description: Returns a list of repairs with their details and images
调试器输出:
参数: 如果 API 支持的操作采用参数,请在 OpenAPI 说明中包含这些参数。 为每个参数包含一个描述字段以简要描述它,并在必要时提供参数用法的示例。 Copilot 使用参数从用户向 API 发出请求的提示中获取所有必需的信息。
示例如下:
parameters:
- name: assignedTo
in: query
description: The name or ID of the person or team to whom the repair is assigned.
schema:
type: string
required: false
响应: 明确定义每个操作的所有可能响应,包括成功和错误响应。 每个响应必须具有状态代码及其所代表内容的说明。 包含响应示例可帮助 Copilot 了解对 API 的期望。
responses:
'200':
description: A list of repairs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Repair'
examples:
example1:
value:
[
{
"id": "1",
"item": "Laptop",
"status": "In Progress",
"assignedTo": "John Doe"
}
]
'404':
description: No repairs found
'500':
description: Server error