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

项目
11/19/2024

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

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

与以前版本相比的更改

此架构版本引入了版本 1.0 中的以下更改。

属性 sites 将添加到 Web 搜索对象。这允许将 Web 搜索功能限制为允许的网站。
添加了图形艺术功能。此功能允许声明代理基于用户输入生成图像和艺术。

JSON 架构

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

约定

URL 中的相对引用

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

字符串长度

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

无法识别的属性

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

字符串本地化

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

声明性代理清单对象

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

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

属性	类型	说明
`version`	String	必需。架构版本。必须设置为 `v1.2`。
`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 搜索对象
OneDrive 和 SharePoint 对象
Microsoft Graph 连接器对象
图形艺术对象

功能示例

{
  "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"
    }
  ]
}

Web 搜索对象

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

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

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

网站对象

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

站点对象包含以下属性。

属性	类型	说明
`url`	String	必填。要搜索内容的网站的绝对 URL。 URL 不能包含 2 个以上的路径段 (例如有效 `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 源都可供声明性代理使用。

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。

图形艺术对象

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

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

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

对话初学者对象

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

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

属性	类型	说明
`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.2/schema.json",
  "version": "v1.2",
  "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",
      "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"
    }
  ]
}

编写声明性代理的有效说明

通过

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

与以前版本相比的更改

JSON 架构

约定

URL 中的相对引用

字符串长度

无法识别的属性

字符串本地化

声明性代理清单对象

声明性代理清单对象示例

Capabilities 对象

功能示例

Web 搜索对象

网站对象

OneDrive 和 SharePoint 对象

SharePoint ID 对象的项目

按 URL 对象排序的项目

Microsoft Graph 连接器对象

Connection 对象

图形艺术对象

对话初学者对象

对话初学者对象示例

Actions 对象

Actions 对象示例

声明性代理清单示例

反馈

其他资源

通过

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

与以前版本相比的更改

JSON 架构

约定

URL 中的相对引用

字符串长度

无法识别的属性

字符串本地化

声明性代理清单对象

声明性代理清单对象示例

Capabilities 对象

功能示例

Web 搜索对象

网站对象

OneDrive 和 SharePoint 对象

SharePoint ID 对象的项目

按 URL 对象排序的项目

Microsoft Graph 连接器对象

Connection 对象

图形艺术对象

对话初学者对象

对话初学者对象示例

Actions 对象

Actions 对象示例

声明性代理清单示例

相关内容

反馈

其他资源

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