Декларативная схема агента 1.2 для Microsoft 365 Copilot

Статья
11/19/2024

В этой статье описывается схема версии 1.2, используемая манифестом декларативного агента. Манифест — это документ, доступный для машинного чтения, который предоставляет модель большого языка (LLM) с необходимыми инструкциями, знаниями и действиями, чтобы специализироваться на решении определенного набора проблем пользователей.

Декларативные агенты полезны для понимания и создания текста, подобного человеку, что делает их универсальными для таких задач, как написание и ответы на вопросы. Эта спецификация ориентирована на декларативный манифест агента, который выступает в качестве структурированной платформы для специализации и расширения функциональных возможностей конкретного пользователя.

Изменения предыдущей версии

Эта версия схемы содержит следующие изменения по версии 1.0.

Свойство sites добавляется в объект веб-поиска. Это позволяет ограничить возможность поиска в Интернете разрешенным сайтом.
Добавлена возможность графического искусства . Эта возможность позволяет декларативному агенту создавать изображения и рисунки на основе введенных пользователем данных.

Схема JSON

Схему, описанную в этом документе, можно найти в формате схемы JSON здесь.

Конвенций

Относительные ссылки в URL-адресах

Если не указано иное, все свойства, которые являются URL-адресами, могут быть относительными ссылками. Относительные ссылки в документе манифеста относительно расположения документа манифеста.

Длина строки

Если не указано иное, все строковые свойства должны быть ограничены 4K-символами. Эта длина строки не предоставляет допустимый размер для всего документа. Реализации могут ввести собственные практические ограничения на длину манифеста.

Нераспознанные свойства

Объекты JSON, определенные в этом документе, поддерживают только описанные свойства. Нераспознанные или лишние свойства в любом объекте JSON должны сделать весь документ недействительным.

Локализация строк

Локализуемые строки могут использовать ключ локализации вместо значения литерала. Синтаксис : [[key_name]], где key_name — это имя ключа в свойстве localizationKeys в файлах локализации. Дополнительные сведения о локализации см. в статье Локализация агента.

Объект манифеста декларативного агента

Корень документа манифеста — это объект JSON, который охватывает обязательные поля, возможности, начальные параметры диалога и действия.

Объект манифеста декларативного агента содержит следующие свойства.

Свойство	Тип	Описание
`version`	String	Обязательный. Версия схемы. Необходимо указать значение `v1.2`.
`id`	Строка	Необязательный параметр.
`name`	String	Обязательный. Локализуемый. Имя декларативного агента. Он должен содержать по крайней мере один символ nonwhitespace и должен содержать не более 100 символов.
`description`	String	Обязательный. Локализуемый. Описание декларативного агента. Он должен содержать по крайней мере один символ nonwhitespace и должен содержать не более 1000 символов.
`instructions`	String	Обязательный. Подробные инструкции или рекомендации о том, как должен вести себя декларативный агент, его функции и любые действия, которые следует избежать. Он должен содержать по крайней мере один символ nonwhitespace и должен содержать не более 8000 символов.
`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 объекта манифеста декларативного агента. Возможные типы объектов:

Объект веб-поиска
Объект 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"
    }
  ]
}

Объект веб-поиска

Указывает, что декларативный агент может искать в Интернете заземляющую информацию.

Объект веб-поиска содержит следующие свойства.

Свойство	Тип	Описание
`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	Необязательный параметр. Массив объектов, определяющих источники SharePoint или OneDrive с помощью идентификаторов. Если свойства `items_by_sharepoint_ids` и свойства опущены `items_by_url` , декларативному агенту будут доступны все источники OneDrive и Sharepoint в организации.
`items_by_url`	Массив элементов по объекту URL-адреса	Необязательный параметр. Массив объектов, определяющих источники SharePoint или OneDrive по URL-адресу. Если свойства `items_by_sharepoint_ids` и свойства опущены `items_by_url` , декларативному агенту будут доступны все источники OneDrive и Sharepoint в организации.

Объект Items by SharePoint IDs

Объект Items by SharePoint IDs содержит следующие свойства.

Свойство	Тип	Описание
`site_id`	String	Необязательный параметр. Уникальный идентификатор GUID для сайта SharePoint или OneDrive.
`web_id`	String	Необязательный параметр. Уникальный идентификатор GUID для определенного веб-сайта SharePoint или OneDrive.
`list_id`	String	Необязательный параметр. Уникальный идентификатор GUID для списка на сайте SharePoint или OneDrive.
`unique_id`	String	Необязательный параметр. Уникальный идентификатор GUID, используемый для представления определенной сущности или ресурса.

Совет

Инструкции по получению уникальных идентификаторов для ресурса SharePoint или OneDrive см. в статье Извлечение идентификаторов возможностей для манифеста декларативного агента.

Элементы по объекту URL-адреса

Объект Items by URL содержит следующие свойства.

Свойство	Тип	Описание
`url`	String	Необязательный параметр. Абсолютный URL-адрес ресурса SharePoint или OneDrive.

Объект соединителей Microsoft Graph

Указывает, что декларативный агент может искать в выбранных соединителях Microsoft Graph сведения о заземлениях.

Объект соединителей Microsoft Graph содержит следующие свойства.

Свойство	Тип	Описание
`name`	String	Обязательный. Необходимо указать значение `GraphConnectors`.
`connections`	Массив объекта Connection	Необязательный параметр. Массив объектов, определяющих соединители Microsoft Graph, доступные декларативному агенту. Если это свойство пропущено, декларативному агенту будут доступны все соединители Microsoft Graph в организации.

Объект Connection

Определяет соединитель Microsoft Graph.

Объект connection содержит следующие свойства.

Свойство	Тип	Описание
`connection_id`	String	Обязательный. Уникальный идентификатор соединителя Microsoft Graph.

Совет

Инструкции по получению уникального идентификатора для соединителя Microsoft Graph см. в разделе Извлечение идентификаторов возможностей для манифеста декларативного агента.

Графический арт-объект

Указывает, что декларативный агент может создавать изображения и рисунки на основе текстового ввода от пользователя. Дополнительные сведения см. в разделе Генератор изображений.

Графический арт-объект содержит следующие свойства.

Свойство	Тип	Описание
`name`	String	Обязательный. Необходимо указать значение `GraphicArt`.

Начальный объект conversation

Объект starters диалога является необязательным в манифесте. Он содержит подсказки, отображаемые пользователю, чтобы продемонстрировать, как приступить к работе с декларативным агентом.

Начальный объект диалога содержит следующие свойства:

Свойство	Тип	Описание
`text`	String	Обязательный. Локализуемый. Предложение, которое пользователь может использовать для получения желаемого результата от декларативного агента. Он должен содержать по крайней мере один символ nonwhitespace.
`title`	String	Необязательный параметр. Локализуемый. Уникальное название для начала беседы. Он должен содержать по крайней мере один символ nonwhitespace.

Пример начального объекта conversation

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

Объект Actions

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

Написание действующих инструкций для декларативных агентов

Поделиться через

Декларативная схема агента 1.2 для Microsoft 365 Copilot

Изменения предыдущей версии

Схема JSON

Конвенций

Относительные ссылки в URL-адресах

Длина строки

Нераспознанные свойства

Локализация строк

Объект манифеста декларативного агента

Пример объекта манифеста декларативного агента

Объект Capabilities

Пример возможностей

Объект веб-поиска

Объект сайта

Объект OneDrive и SharePoint

Объект Items by SharePoint IDs

Элементы по объекту URL-адреса

Объект соединителей Microsoft Graph

Объект Connection

Графический арт-объект

Начальный объект conversation

Пример начального объекта conversation

Объект Actions

Пример объекта Actions

Пример манифеста декларативного агента

Обратная связь

Дополнительные ресурсы

Поделиться через

Декларативная схема агента 1.2 для Microsoft 365 Copilot

Изменения предыдущей версии

Схема JSON

Конвенций

Относительные ссылки в URL-адресах

Длина строки

Нераспознанные свойства

Локализация строк

Объект манифеста декларативного агента

Пример объекта манифеста декларативного агента

Объект Capabilities

Пример возможностей

Объект веб-поиска

Объект сайта

Объект OneDrive и SharePoint

Объект Items by SharePoint IDs

Элементы по объекту URL-адреса

Объект соединителей Microsoft Graph

Объект Connection

Графический арт-объект

Начальный объект conversation

Пример начального объекта conversation

Объект Actions

Пример объекта Actions

Пример манифеста декларативного агента

Связанные материалы

Обратная связь

Дополнительные ресурсы