通过

适用于 智能 Microsoft 365 Copilot 副驾驶® 的声明性代理架构 1.0

  • 项目

本文介绍声明性代理清单使用的 1.0 架构。 清单是一个计算机可读文档，它提供大型语言模型 (LLM) ，以及专门解决一组选定用户问题所需的说明、知识和操作。

重要

声明性代理清单架构的最新版本是 版本 1.2。 建议新代理使用最新的架构版本。

声明性代理在理解和生成类似人类的文本方面很有价值，因此它们可用于编写和回答问题等任务。 此规范侧重于声明性代理清单，该清单充当结构化框架，以专门化和增强特定用户所需的功能。

JSON 架构

本文档中所述的架构可在此处找到 JSON 架构格式。

约定

URL 中的相对引用

除非另有指定，否则作为 URL 的所有属性都可以是相对引用。 清单文档中的相对引用与清单文档的位置相对。

字符串长度

除非另有说明，否则所有字符串属性应限制为 4K 个字符。 此字符串长度不会为整个文档赋予任何可接受的大小。 实现可以自由地对清单长度施加自己的实际限制。

无法识别的属性

本文档中定义的 JSON 对象仅支持所述的属性。 任何 JSON 对象中无法识别或无关的属性都应使整个文档无效。

字符串本地化

可本地化字符串可以使用本地化键而不是文本值。 语法为 [[key_name]]，其中 key_name 是本地化文件中 属性中的 localizationKeys 键名称。 有关本地化的详细信息，请参阅 本地化代理。

声明性代理清单对象

清单文档的根目录是一个 JSON 对象，它涵盖所需的字段、功能、对话启动器和操作。

声明性代理清单对象包含以下属性。

属性 类型 说明
version String 必需。 架构版本。 必须设置为 v1.0。
id String 可选。
name String 必填。 可本地化。 声明性代理的名称。 它必须至少包含一个非白空间字符，并且必须为 100 个字符或更少。
description String 必填。 可本地化。 声明性代理的说明。 它必须至少包含一个非空白字符，并且必须包含 1,000 个字符或更少。
instructions String 必填。 有关声明性代理的行为方式、其函数以及要避免的任何行为的详细说明或指南。 它必须至少包含一个非空白字符，并且必须包含 8,000 个字符或更少。
capabilities Capabilities 对象的数组 可选。 包含一个对象数组，这些对象定义声明性代理的功能。 数组中每个派生类型的 Capabilities 对象 不得有多个。
conversation_starters Conversation 初学者对象的数组 可选。 标题和文本是可本地化的。 声明性代理可以回答的问题示例列表。 数组中的对象不能超过六个。
actions Action 对象的数组 可选。 对象的列表，这些对象标识 API 插件，这些插件 提供声明性代理可访问的操作。

声明性代理清单对象示例

以下 JSON 是声明性代理清单中必填字段的示例。

{
  "name" : "Repairs agent",
  "description": "This declarative agent is meant to help track any tickets and repairs",
  "instructions": "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
}

Capabilities 对象

capabilities 对象是声明性代理清单对象中 capabilities 属性中的 对象的基类型。 可能的对象类型包括：

功能示例

{
  "capabilities": [
    {
      "name": "WebSearch"
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_sharepoint_ids": [
        {
          "site_id": "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd",
          "web_id": "a5377427-f041-49b5-a2e9-0d58f4343939",
          "list_id": "78A4158C-D2E0-4708-A07D-EE751111E462",
          "unique_id": "304fcfdf-8842-434d-a56f-44a1e54fbed2"
        }
      ],
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "jiraTickets"
        }
      ]
    }
  ]
}

Web 搜索对象

指示声明性代理可以在 Web 中搜索地面信息。

Web 搜索对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 WebSearch。

OneDrive 和 SharePoint 对象

指示声明性代理可以在用户的 SharePoint 和 OneDrive 中搜索地面信息。

OneDrive 和 SharePoint 对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 OneDriveAndSharePoint。
items_by_sharepoint_ids 按 SharePoint ID 对象排列的项目数组 可选。 使用 ID 标识 SharePoint 或 OneDrive 源的对象数组。 items_by_sharepoint_ids如果省略 和 items_by_url 属性，则组织中所有 OneDrive 和 Sharepoint 源都可供声明性代理使用。
items_by_url 按 URL 对象排列的项目数组 可选。 对象的数组，这些对象按 URL 标识 SharePoint 或 OneDrive 源。 items_by_sharepoint_ids如果省略 和 items_by_url 属性，则组织中所有 OneDrive 和 Sharepoint 源都可供声明性代理使用。
SharePoint ID 对象的项目

Items by SharePoint IDs 对象包含以下属性。

属性 类型 说明
site_id String 可选。 SharePoint 或 OneDrive 网站的唯一 GUID 标识符。
web_id String 可选。 SharePoint 或 OneDrive 网站中特定 Web 的唯一 GUID 标识符。
list_id String 可选。 SharePoint 或 OneDrive 网站中列表的唯一 GUID 标识符。
unique_id String 可选。 用于表示特定实体或资源的唯一 GUID 标识符。

提示

有关获取 SharePoint 或 OneDrive 资源的唯一标识符的说明，请参阅 检索声明性代理清单的功能 ID。

按 URL 对象排序的项目

Items by URL 对象包含以下属性。

属性 类型 说明
url String 可选。 SharePoint 或 OneDrive 资源的绝对 URL。

Microsoft Graph 连接器对象

指示声明性代理可以在所选Microsoft Graph 连接器中搜索基础信息。

Microsoft Graph 连接器对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 GraphConnectors。
connections Connection 对象的数组 可选。 对象的数组，这些对象标识可用于声明性代理的 Microsoft Graph 连接器。 如果省略此属性，则组织中所有Microsoft Graph 连接器都可供声明性代理使用。
Connection 对象

标识Microsoft Graph 连接器。

连接对象包含以下属性。

属性 类型 说明
connection_id String 必填。 Microsoft Graph 连接器的唯一标识符。

提示

有关获取 Microsoft Graph 连接器的唯一标识符的说明，请参阅 检索声明性代理清单的功能 ID。

对话初学者对象

会话初学者对象在清单中是可选的。 它包含向用户显示的提示，以演示如何开始使用声明性代理。

对话初学者对象包含以下属性：

属性 类型 说明
text String 必填。 可本地化。 一个建议，用户可以使用 该建议从声明性代理获取所需结果。 它必须至少包含一个非白空间字符。
title String 可选。 可本地化。 对话初学者的唯一标题。 它必须至少包含一个非白空间字符。

对话初学者对象示例

{
  "conversation_starters": [
    {
      "title": "My Open Repairs",
      "text": "What open repairs are assigned to me?"
    }
  ]
}

Actions 对象

操作是清单中的可选 JSON 对象。 它充当开发人员输入，可被视为插件。

操作对象包含以下属性。

属性 类型 说明
id String 必填。 操作的唯一标识符。 它可能是 GUID。
file String 必填。 此操作的 API 插件清单的路径。

Actions 对象示例

{
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "plugin.json"
    }
  ]
}

声明性代理清单示例

下面是声明性代理清单文件的示例，该文件使用本文所述的大多数清单属性。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Teams Toolkit declarative copilot",
  "description": "Declarative copilot created with Teams Toolkit",
  "instructions": "You are a repairs expert copilot. With the response from the listRepairs function, you **must** create a poem out of the repairs listed and always include their title and the assigned person. The poem **must** not use the quote markdown and use regular text. If the user is asking to create a new repair, use the createRepair function and do not add poems.",
  "conversation_starters": [
    {
      "title": "Getting Started",
      "text": "How can I get started with Teams Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Teams Toolkit?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "capabilities": [
    {
      "name": "WebSearch"
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "foodStore"
        }
      ]
    }
  ]
}

相关内容