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

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

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

与以前版本相比的更改

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

• 添加了可选 sensitivity_label 属性， 以便仅在代理具有嵌入文件时指定代理的 Purview 敏感度标签。
• 添加了可选 worker_agents 属性以指定此代理可以使用的其他声明性代理。
• 添加了可选 user_overrides 属性，以指定代理用户可以修改的已配置功能。
• 添加了 嵌入式知识 功能，允许代理使用本地文件作为知识。
• items_by_id向会议对象添加了 属性，使代理创建者能够限制代理可用的会议。
• include_related_content向 people 对象添加了 属性，允许代理创建者在搜索人员内容时选择包含相关文档、电子邮件和 Teams 消息。
• group_mailboxes向电子邮件对象添加了 属性。

JSON 架构

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

约定

URL 中的相对引用

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

字符串长度

除非另有说明，否则将所有字符串属性限制为 4,000 个字符。 此字符串长度不会为文档中的所有字符串属性设置可接受的大小。 实现可以对清单长度设置自己的实际限制。

无法识别的属性

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

字符串本地化

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

声明性代理清单对象

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

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

声明性代理清单对象示例

以下代码显示了声明性代理清单中必填字段的示例。

{
  "version": "v1.6",
  "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"
}

@agent(
  "Repairs agent",
  "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
)
@instructions(
  "This declarative agent needs to look at my Service Now and Jira tickets/instances to help me keep track of open items"
)
namespace MyAgent {

}

Capabilities 对象

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

• Web 搜索对象
• OneDrive 和 SharePoint 对象
• Copilot 连接器对象
• 图形艺术对象
• 代码解释器对象
• Dataverse 对象
• Microsoft Teams 消息对象
• Email 对象
• 用户对象
• 方案模型对象
• Meetings 对象
• 嵌入式知识对象

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"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    },
    {
      "name": "Meetings",
      "items_by_id": [
        {
          "id": "010000002300A00045B6C7890D12E0030000000040056F7GH890IJ01000000000000000020000000J3L45M6A7NO8PQ9R0S12TUV340XY5Z00",
          "is_series": true
        }
      ]
    }
  ]
}

namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<TSites = [
    {
        url: "https://contoso.com"
    }
  ]>;

  op od_sp is AgentCapabilities.OneDriveAndSharePoint<
    TItemsBySharePointIds = [
      {
        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";
      }
    ],
    TItemsByUrl = [
      {
        url: "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
      }
    ]
  >;

  op graphConnectors is AgentCapabilities.CopilotConnectors<TConnections = [
    {
        connection_id: "jiraTickets"
    }
  ]>;

  op graphicArt is AgentCapabilities.GraphicArt;

  op codeInterpreter is AgentCapabilities.CodeInterpreter;

  op teamsMessages is AgentCapabilities.TeamsMessages<TUrls = [
    {
        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"
    }
  ]>;

  op people is AgentCapabilities.People;

  op meetings is AgentCapabilities.Meetings;
}

Web 搜索对象

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

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

网站对象

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

站点对象包含以下属性。

OneDrive 和 SharePoint 对象

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

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

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

SharePoint ID 对象的项目

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

按 URL 对象排序的项目

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

Copilot 连接器对象

指示声明性代理可以在所选的 Copilot 连接器中搜索地面信息。

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

Connection 对象

标识 Copilot 连接器。

连接对象包含以下属性。

项目标识符对象

按 ID 标识外部项。

项标识符对象包含以下属性。

Path 对象

按外部项的路径标识外部项。

路径对象包含以下属性。

容器名称对象

按容器名称标识容器。

容器名称对象包含以下属性。

容器 URL 对象

通过容器的 URL 标识容器。

容器 URL 对象包含以下属性。

图形艺术对象

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

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

代码解释器对象

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

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

Dataverse 对象

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

Dataverse 对象包含以下属性。

知识源对象

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

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

若要查找要包括的 Dataverse 知识源的唯一 skill 标识符，

1. 在“Copilot Studio”的左窗格中，选择“适用于 Microsoft 365 的代理>”，然后选择“添加”以创建新代理。
2. 按照 添加 Dataverse 知识源 中的说明添加 Dataverse 知识。
3. 选择“ 发布”，然后下载 .zip 文件。
4. 解压缩并打开declarativeAgent.json文件。
5. 值 skill 包含在 节中 knowledge_sources ，如以下示例所示。

{
  "name": "Dataverse",
  "knowledge_sources": [
    {
      "host_name": "org0f612cfc.crm.dynamics.com",
      "skill": "AIBuilderFileAttachedData_e7eTReDbkX_1t4X1oGoCF",
      "tables": [
        {
          "table_name": "msdyn_aibfileattacheddata"
        }
      ]
    }
  ]
}

Tables 对象

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

tables 对象包含以下属性。

Microsoft Teams 消息对象

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

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

Microsoft Teams URL 对象

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

Microsoft Teams URL 对象包含以下属性。

Email 对象

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

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

Folders 对象

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

folders 对象包含以下属性。

用户对象

指示声明性代理可以搜索有关组织中人员的信息。 有关基本人员功能返回的数据的更多详细信息，请参阅人员知识。

people 对象包含以下属性。

方案模型对象

指示声明性代理可以使用特定于任务的模型。

方案模型对象包含以下属性。

Model 对象

标识特定于任务的模型。

模型对象包含以下属性。

Meetings 对象

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

meetings 对象包含以下属性。

会议标识符对象

标识会议。

会议标识符对象包含以下属性。

嵌入式知识对象

指示声明性代理可以在应用包中本地使用文件。

嵌入式知识文件的最大文件大小为 1 MB，并且必须是以下文档类型之一：

• Word文档 (.doc，.docx)
• PowerPoint 演示文稿 (.ppt、.pptx)
• Excel 工作簿 (.xls，.xlsx)
• 纯文本 (.txt)
• 可移植文档格式 (.pdf)

嵌入式知识对象包含以下属性：

EmbeddedKnowledge 对象示例

{
  "name": "EmbeddedKnowledge",
  "files": [
    { "file": "file1.docx" },
    { "file": "file2.csv" }
  ]
}

File 对象

对话初学者对象

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

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

对话初学者对象示例

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

@conversationStarter(#{
  title: "My Open Repairs",
  text: "What open repairs are assigned to me?"
)}

Actions 对象

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

作对象包含以下属性。

Actions 对象示例

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

@service
@server("https://jsonplaceholder.typicode.com")
@actions(#{
  nameForHuman: "Posts APIs",
  descriptionForHuman: "Manage blog post items on JSON Placeholder APIs.",
  descriptionForModel: "Read, create, update and delete blog post items on the JSON Placeholder APIs."
})
namespace PostsAPI {
  // All operations from the actions
}

行为重写对象

一个可选的 JSON 对象，其中包含替代代理行为的配置设置。

行为重写 对象包含以下属性。

Suggestions 对象

包含建议功能的配置设置的可选 JSON 对象。

suggestions 对象包含以下属性。

特殊指令对象

可选的 JSON 对象，其中包含用于将特殊指令注入提示的设置。

特殊指令对象包含以下属性。

免责声明对象

免责声明是清单中指定免责声明文本的可选 JSON 对象。 代理在会话开始时向用户显示此文本。

免责声明对象包含以下属性。

敏感度标签对象

可选的 JSON 对象，指定代理中嵌入文件的 Microsoft Purview 敏感度标签。 它包含嵌入到 Embedded Knowledge 属性中代理的所有文件的最高保护

敏感度标签对象示例

{
  "sensitivity_label": {
    "id": "<guid>"
  }
}

辅助角色代理对象

标识可由此代理使用的声明性代理。

辅助角色代理对象包含以下属性。

用户重写对象

标识代理中的功能，代理最终用户可以通过 智能 Microsoft 365 Copilot 副驾驶® 中的 UI 控件进行修改。

用户重写对象包含以下属性。

声明性代理清单示例

以下示例演示一个声明性代理清单文件，该文件使用本文中所述的大多数清单属性。

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "Teams Toolkit declarative agent",
  "description": "Declarative agent created with Teams Toolkit",
  "instructions": "You are a repairs expert agent. 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?"
    }
  ],
  "sensitivity_label": {
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "behavior_overrides": {
    "suggestions": {
      "disabled": true
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  },
  "disclaimer": {
    "text": "This declarative agent is a fictional example. You should not take it seriously."
  },
  "worker_agents": [
    {
      "id": "P_2c27ae89-1f78-4ef7-824c-7d83f77eda28"
    }
  ],
  "user_overrides": [
    {
      "path": "$.capabilities[?(@.name == 'OneDriveAndSharePoint')]",
      "allowed_actions": [
        "remove"
      ]
    }
  ],
  "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": "inbox"
        }
      ]
    },
    {
      "name": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    },
    {
      "name": "Meetings",
      "items_by_id": [
        {
          "id": "010000002300A00045B6C7890D12E0030000000040056F7GH890IJ01000000000000000020000000J3L45M6A7NO8PQ9R0S12TUV340XY5Z00",
          "is_series": true
        }
      ]
    },
    {
      "name": "EmbeddedKnowledge",
      "files": [
        { "file": "file1.docx" },
        { "file": "file2.csv" }
      ]
    }
  ]
}

相关内容

• 编写声明性代理的有效说明
• Microsoft 365 应用清单参考