通过

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

本文介绍声明性代理清单使用的 1.3 架构。 清单是一个计算机可读文档，它提供大型语言模型 (LLM) ，以及专门解决一组选定用户问题所需的说明、知识和作。 声明性代理清单由应用包内的 Microsoft 365 应用清单引用。 有关详细信息，请参阅 Microsoft 365 应用清单参考。

重要

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

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

与以前版本相比的更改

此架构版本引入了 版本 1.2 中的以下更改：

  • Dataverse 功能将添加到 的列表中capabilities。 它支持包含 Dataverse 实例的 knowledge_sources 字段中的对象数组。
  • Teams 消息功能将添加到 的列表中capabilities。 它支持字段中的一组对象，这些对象 urls 包含指向团队频道、团队或会议聊天的格式正确的 Teams URL。
  • Email功能将添加到 列表中capabilities。 它支持共享邮箱和供代理搜索的文件夹 ID 数组。
  • 人员功能将添加到 列表中capabilities。 此功能是无作用域的，允许代理搜索有关组织中人员的信息。

JSON 架构

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

约定

URL 中的相对引用

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

字符串长度

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

无法识别的属性

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

字符串本地化

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

声明性代理清单对象

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

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

属性 类型 说明
version String 必需。 架构版本。 必须设置为 v1.3。
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 属性中的 对象的基类型。 可能的对象类型包括：

注意

具有除 Web 搜索以外的任何功能的声明性代理仅适用于允许按流量计费的租户中的用户或具有智能 Microsoft 365 Copilot 副驾驶®许可证的租户。

Capabilities 对象示例

{
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com"
        }
      ]
    },
    {
      "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"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "People"
    }
  ]
}

Web 搜索对象

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

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

属性 类型 说明
name String 必需。 必须设置为 WebSearch。
sites Site 对象的数组 可选。 对象数组，用于标识允许代理搜索的站点。 如果省略此属性，则允许所有代理搜索所有网站。 数组不能包含四个以上的项。

注意

有关智能 Microsoft 365 Copilot 副驾驶® 对话助手和智能 Microsoft 365 Copilot 副驾驶®中 Web 搜索的数据、隐私和安全性的详细信息，请参阅 Web 搜索的数据、隐私和安全性。

网站对象

指示声明性代理可以搜索内容的网站。

站点对象包含以下属性。

属性 类型 说明
url String 必填。 要搜索内容的网站的绝对 URL。 URL 不能包含两个以上的路径段 (例如有效 https://contoso.com/projects/mark-8 ， https://contoso.com/projects/mark-8/beta-program) 无效。 URL 不能包含任何查询参数。

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 源都可供声明性代理使用。

有关如何优化 Copilot 的 SharePoint 内容的信息，请参阅 优化 SharePoint 内容检索。

SharePoint ID 对象的项目

SharePoint ID 对象的项目包含以下属性。

属性 类型 说明
site_id String 可选。 SharePoint 或 OneDrive 网站的唯一 GUID 标识符。
web_id String 可选。 SharePoint 或 OneDrive 网站中特定 Web 的唯一 GUID 标识符。
list_id String 可选。 SharePoint 或 OneDrive 网站中列表的唯一 GUID 标识符。
unique_id String 可选。 用于表示特定实体或资源的唯一 GUID 标识符。
search_associated_sites 布尔值 可选。 指示是否启用搜索关联网站。 仅当该值引用 SharePoint HubSite 时， site_id 此值才适用。

提示

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

按 URL 对象排序的项目

按 URL 对象排序的项包含以下属性。

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

Copilot 连接器对象

指示声明性代理可以搜索所选智能 Microsoft 365 Copilot 副驾驶®连接器 (以前Microsoft Graph 连接器) 获取地面信息。

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

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

标识 Copilot 连接器。

连接对象包含以下属性。

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

提示

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

图形艺术对象

指示声明性代理可以根据用户输入的文本创建图像和艺术。 有关详细信息，请参阅 映像生成器。

图形艺术对象包含以下属性。

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

代码解释器对象

指示声明性代理可以生成和执行 Python 代码来解决复杂的数学问题、分析数据、生成可视化效果等。 有关详细信息，请参阅 代码解释器。

代码解释器对象包含以下属性。

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

Dataverse 对象

指示声明性代理可以从 Microsoft Dataverse 中的表中搜索数据。

Dataverse 对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 Dataverse。
knowledge_sources 知识源数组 可选。 对象的数组，其中包含要作为知识包含的 Dataverse 实例的标识符、技能和表名称。
知识源对象

包含有关要作为知识包含的 Dataverse 实例的信息。

知识源对象包含以下属性。

属性 类型 说明
host_name String 必填。 Dataverse 中主机的唯一标识符。
skill String 一个唯一标识符，用于定义代理如何与 Dataverse 知识交互的配置。
tables 表数组 用于限定代理知识范围的表数组。
Tables 对象

包含用于限定代理知识范围的表。

tables 对象包含以下属性。

属性 类型 说明
table String 必填。 表的唯一标识符。

Teams 消息对象

指示声明性代理可以搜索 Teams 频道、团队、会议、1：1 聊天和群组聊天。

Teams 消息对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 TeamsMessages。
urls Teams URL 数组 可选。 对象数组，用于标识可用于声明性代理的 Teams 频道、团队或会议聊天的 URL。 数组中的对象不能超过五个。 省略此属性允许跨所有频道、团队、会议、1：1 聊天和群组聊天进行无作用域搜索。
Teams URL 对象

标识 Teams 频道、团队或会议聊天。

Teams URL 对象包含以下属性。

属性 类型 说明
url String 必填。 格式良好的 Teams URL，链接到团队频道、团队或会议聊天。

Email 对象

指示声明性代理可以在用户有权访问的邮箱中搜索电子邮件。

电子邮件对象包含以下属性。

属性 类型 说明
name String 必需。 必须设置为 Email。
shared_mailbox String 可选。 共享邮箱的 SMTP 地址。
folders String 可选。 folder_id 对象的数组。
Folders 对象

包含用于确定代理知识范围的文件夹。

folders 对象包含以下属性。

属性 类型 说明
folder_id String 必填。 要引用的文件夹的已知文件夹名称或文件夹 ID。

用户对象

指示声明性代理可以搜索有关组织中人员的信息。

people 对象包含以下属性。

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

对话初学者对象

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

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

属性 类型 说明
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.3/schema.json",
  "version": "v1.3",
  "name": "Microsoft 365 Agents Toolkit declarative copilot",
  "description": "Declarative copilot created with Agents 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 Agents Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Agents Toolkit?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "capabilities": [
    {
      "name": "WebSearch",
      "sites": [
        {
          "url": "https://contoso.com/projects/mark-8"
        }
      ]
    },
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "foodStore"
        }
      ]
    },
    {
      "name": "GraphicArt"
    },
    {
      "name": "CodeInterpreter"
    },
    {
      "name": "Dataverse",
      "knowledge_sources": [
        {
          "host_name": "organization.crm.dynamics.com",
          "skill": "DVCopilotSkillName",
          "tables": [
            {
              "table_name": "account"
            },
            {
              "table_name": "opportunity"
            }
          ]
        }
      ]
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3ApO0102YGEBRSH6RziXCxEgB4mtb7-5hIlDzAjtxs_dg1%40thread.tacv2/G%C3%A9n%C3%A9ral?groupId=2670cf94-acf5-48f4-96d4-c58dd8937afc&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
      ]
    },
    {
      "name": "Email",
      "shared_mailbox": "sample@service.microsoft.com",
      "folders": [
        {
         "folder_id": "sentitems"
        }
     ]
    },
    {
      "name": "People"
    }
  ]
}

相关内容