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

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

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

与以前版本相比的更改

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

• 向 列表capabilities添加了会议功能，允许代理在组织中搜索会议。

JSON 架构

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

约定

URL 中的相对引用

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

字符串长度

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

无法识别的属性

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

字符串本地化

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

声明性代理清单对象

清单文档的根目录是一个 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"
}

@agent(
  "Repairs agent",
  "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"
)
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"
    }
  ]
}

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

  op od_sp is AgentCapabilities.OneDriveAndSharePoint<
    ItemsBySharePointIds = [
      {
        siteId: "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd";
        webId: "a5377427-f041-49b5-a2e9-0d58f4343939";
        listId: "78A4158C-D2E0-4708-A07D-EE751111E462";
        itemId: "304fcfdf-8842-434d-a56f-44a1e54fbed2";
      }
    ],
    ItemsByUrl = [
      {
        url: "https://contoso.sharepoint.com/teams/admins/Documents/Folders1"
      }
    ]
  >;

  op copilotConnectors is AgentCapabilities.CopilotConnectors<Connections = [
    {
        connectionId: "jiraTickets"
    }
  ]>;

  op graphicArt is AgentCapabilities.GraphicArt;

  op codeInterpreter is AgentCapabilities.CodeInterpreter;

  op dataverse is AgentCapabilities.Dataverse<KnowledgeSources = [
    {
      hostName: "organization.crm.dynamics.com";
      skill: "DVCopilotSkillName";
      tables: [
        { tableName: "account" },
        { tableName: "opportunity" }
      ];
    }
  ]>;

  op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [
    {
        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 scenarioModels is AgentCapabilities.ScenarioModels<Models = [
    { id: "model_id" }
  ]>;

  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 对象包含以下属性。

对话初学者对象

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

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

对话初学者对象示例

{
  "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 对象。 代理在会话开始时向用户显示此文本。

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

声明性代理清单示例

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5",
  "name": "Agents Toolkit declarative agent",
  "description": "Declarative agent created with Agents 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 Agents Toolkit?"
    },
    {
      "title": "Getting Help",
      "text": "How can I get help with Agents Toolkit?"
    }
  ],
  "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."
  },
  "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"
    }
  ]
}

相关内容

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