Агенты Copilot — это приложения для Microsoft 365

Статья
10/03/2024

Важно!

Подключаемые модули API в настоящее время поддерживаются только в качестве действий в декларативных агентах. Они не включены в Microsoft 365 Copilot. Пример добавления подключаемого модуля API к декларативному агенту см. в разделе Добавление подключаемого модуля.
Эта возможность включена по умолчанию во всех клиентах с лицензией Microsoft 365 Copilot. Администраторы могут отключить эту функцию на уровне пользователей и групп, а также контролировать, как отдельные подключаемые модули утверждаются для использования и какие подключаемые модули включены. Дополнительные сведения см. в разделе Управление агентами Copilot в интегрированных приложениях.

При создании агента Copilot вы также создаете приложение для Microsoft 365. Приложения для Microsoft 365 используют общую схему манифеста и формат упаковки, а также унифицированные процессы и средства распространения и управления. В конечном итоге ваши приложения и агенты Copilot достигают максимально широкой аудитории и отображаются контекстно в рабочем процессе пользователей.

В этой статье рассматриваются ключевые части модели приложений Microsoft 365 для разработки агента Copilot.

Модель приложений для Microsoft 365

Экосистема Microsoft 365 превращается в интегрированную платформу приложений, где можно использовать общую модель приложений для определения и упаковки приложения. То, что началось как способ расширения приложений Teams для запуска в других приложениях Microsoft 365 , с тех пор расширилось для поддержки распространения соединителей Microsoft Graph, надстроек Outlook и теперь агентов Copilot.

Пакет приложения

Пакет приложения для Microsoft 365, включая агенты Copilot, представляет собой ZIP-файл, содержащий один или несколько файлов конфигурации (манифеста) и значки вашего приложения. Логика приложения и хранилище данных размещаются в другом месте и получают доступ к ведущему приложению Microsoft 365 по протоколу HTTPS. Вы отправите пакет приложения администратору для публикации в организации или в Центр партнеров для публикации в Microsoft AppSource.

Как минимум, пакет приложения содержит:

манифест приложения (manifest.json), описывающий конфигурацию приложения, возможности, необходимые ресурсы и важные атрибуты;
значок большого цвета (color.png), полноцветный значок 92x92 для отображения агента в пользовательском интерфейсе Microsoft Copilot и в хранилище;
небольшой значок контура (outline.png), значок 32x32 с прозрачным фоном (в настоящее время не используется в Copilot, но требуется для прохождения проверки);

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

Схема, показывающая структуру пакета приложения Microsoft 365: манифест приложения (.json файл) + значки (цветные и контурные .png файлы), заключенные в файл .zip

Значки приложений

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

Примечание.

В настоящее время только значок цвета используется для представления агентов Copilot для конечного пользователя (как в виде описания в магазине, так и в пользовательском интерфейсе Microsoft 365 Copilot), но значок структуры по-прежнему требуется при отправке пакета приложения в Microsoft AppSource.

Дополнительные рекомендации по проектированию цветовых и контурных значков для пакета приложения Microsoft 365, значки приложений для Магазина Teams и панель приложения.

Цветной значок

Значок цвета представляет вашего агента в пользовательском интерфейсе Microsoft Copilot и в магазинах приложений (Teams, Outlook, Microsoft 365).

Значок цвета:

Может быть любым цветом
Должно быть всего 192 x 192 пикселя
Значение должно иметь размер 96 x 96 пикселей для самого символа (чтобы разрешить заполнение 48 пикселей для сценариев размещения, где он обрезается)
Должен располагаться на вершине полностью сплошного или полностью прозрачного квадратного фона

Контурный значок

Значок структуры используется для представления закрепленных и (или) активных приложений на панели приложений Teams. В настоящее время он не используется для агентов Copilot, но по-прежнему необходим для того, чтобы пакет приложения прошел проверку.

Значок структуры:

Должно быть 32 x 32 пикселей
Должен быть либо белым с прозрачным фоном, либо прозрачным с белым фоном
Не должен содержать дополнительных заполнений вокруг символа

Манифест приложения

Манифест приложения для Microsoft 365 представляет собой JSON-файл, в котором описываются функции и характеристики приложения. По своей сути манифест приложения для Microsoft 365 является схемой для создания приложений Teams, однако с тех пор он был расширен (начиная с версии 1.13) для определения приложений, работающих на узлах Microsoft 365, в дополнение к Teams.

Если вы используете Microsoft Copilot Studio для создания декларативного агента, манифест приложения создается на основе сведений, предоставленных во время создания.

Каждый манифест приложения должен содержать следующие сведения:

Поле манифеста	Описание
version	Номер версии приложения в формате MAJOR. НЕСОВЕРШЕННОЛЕТНИЙ. PATCH (стандарт semver ).
id	Уникальный идентификатор, созданный для этого приложения на портале регистрации приложений Майкрософт (apps.dev.microsoft.com) в форме GUID.
разработчик	Сведения о разработчике, включая имя, веб-сайт и ссылки на политику конфиденциальности и условия использования. Для приложений, отправленных в AppSource, значения должны соответствовать значению, указанному в форме отправки приложений Центра партнеров.
name	Имя приложения, отображаемое для конечных пользователей в узле приложения.
description	Краткие и длинные описания приложения для пользователей. Для приложений, отправляемых в AppSource, эти значения должны совпадать с данными в записи AppSource.
Иконки	Относительные пути к файлам значков цвета и структуры.
accentColor	Цвет, используемый с и в качестве фона для значков структуры, в шестнадцатеричном значении RGB, например `#4464ee`.
Определения для конкретных возможностей приложений	Определение для каждой возможности приложения, например личных вкладок (staticTabs), расширений сообщений (composeExtensions) или ботов. Декларативные агенты и подключаемые модули API определяются в узле copilotAgents .

В следующем примере показан манифест приложения с разделами заполнителей в конце для расширения сообщений и декларативного приложения агента.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.18/MicrosoftTeams.schema.json",
    "manifestVersion": "1.18",
    "version": "1.0.0",
    "id": "00000000-0000-0000-0000-000000000000",
    "developer": {
        "name": "Northwind Traders",
        "websiteUrl": "https://www.example.com",
        "privacyUrl": "https://www.example.com/termofuse",
        "termsOfUseUrl": "https://www.example.com/privacy"
    },
    "icons": {
        "color": "Northwind-Logo-196.png",
        "outline": "Northwind-Logo-32.png"
    },
    "name": {
        "short": "Northwind Inventory",
        "full": "Northwind Inventory App"
    },
    "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app."
    },
    "accentColor": "#3690E9",
    "composeExtensions": {
        ...
    },
    "copilotAgents": {
        ...
    }
}

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

`copilotAgents` Определения

Декларативные агенты и подключаемые модули API имеют собственные схемы определений. На файл определения декларативного агента ссылается copilotAgents объект манифеста приложения.

В следующем примере показано, как ссылаться на декларативный агент:

    "copilotAgents": {
        "declarativeAgents": [
            {
                "id": "agent1",
                "file": "declarativeAgent1.json"
            }
        ]
    },

На определение подключаемого модуля API ссылается определение декларативного агента.

Схема манифеста приложения, ссылающегося на манифест декларативного агента и манифест подключаемого модуля API. Манифест декларативного агента ссылается на другой манифест подключаемого модуля API

Обратите внимание на следующее:

В настоящее время поддерживается только одно декларативное определение агента для каждого манифеста приложения. Для каждого декларативного агента поддерживается только один подключаемый модуль API.
При использовании Copilot Studio для создания агентов Copilot для каждого из них создается уникальный id объект в рамках создания общего манифеста приложения. При создании агентов с помощью Набора средств Teams или собственной интегрированной среды разработки вы назначаете id сами в соответствии с вашими соглашениями или понятным именем.

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

Манифест декларативного агента содержит инструкции для ответов Copilot, примеры запросов для начала беседы, источники данных, используемые для заземления, а также список действий (навыки подключаемого модуля API), которые агент может выполнить.

Дополнительные сведения см. в статье Схема манифеста декларативного агента для Microsoft 365 Copilot.

Манифест подключаемого модуля API

Манифест подключаемого модуля API описывает возможности подключаемого модуля, включая поддерживаемые им API и операции, которые он может выполнять. Он также содержит метаданные, такие как имя, описание, версия, а также ссылку на определение OpenAPI интерфейсов REST API, с которыми он взаимодействует. На подключаемые модули API можно ссылаться из манифеста декларативного агента, который будет использоваться в интерфейсе декларативного агента.

Дополнительные сведения см. в статье Схема манифеста подключаемого модуля API для Microsoft 365 Copilot.

Локализация агента

Способ локализации агента Copilot немного отличается от локализации других возможностей (таких как вкладки, боты и расширения сообщений) в манифесте приложения.

Вы будете использовать один и тот же файл локализации (для каждого языка) как для классических возможностей приложения Teams, так и для агента Copilot. Однако в то время как на все остальные поля манифеста приложения ссылаются с помощью выражений JSONPath в языковых файлах, на связанные с агентом Copilot поля просто ссылаются с помощью словарных ключей. В отличие от классических возможностей приложения Teams, в которых используются строки языка по умолчанию в самом манифесте приложения, локализованным агентам Copilot требуется языковой файл для языка по умолчанию, а также для каждого дополнительного языка.

Схема, показывающая связь между манифестом приложения, манифестом декларативного агента и языковым файлом для локализации агента Copilot

Ниже показано, как поддерживать дополнительные языки (за пределами по умолчанию) для агентов Copilot.

1. Обновите манифесты агента Copilot с помощью маркеризованных ключей.

Обновите манифесты декларативного агента и (или) подключаемого модуля API с помощью маркеризованных ключей (отмеченных двойными квадратными скобками, например [[PLUGIN_NAME]]) для любых значений полей, которые вы хотите локализовать. Ключи локализации в значительной степени соответствуют этому регулярному выражению: ^[a-zA-Z_][a-zA-Z0-9_]*$

В следующем примере показан декларативный манифест агента с токенизированными значениями для его имени и описания:

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

2. Добавление `localizationInfo` в манифест приложения

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

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

В следующем примере показан раздел сведений о локализации в манифесте приложения:

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

Если агент Copilot не поддерживает дополнительные языки, строки языка по умолчанию представлены в самом файле манифеста приложения. (Для пакетов приложений на одном языке не требуется отдельный языковой файл для языка по умолчанию.)

3. Создание файла локализации для каждого дополнительного языка

Создайте файл локализации для каждого дополнительного поддерживаемого языка со значениями для ключей с маркерами, используя имена файлов, указанные (для defaultLanguageFile и file свойства) в манифесте приложения на предыдущем шаге.

В следующем примере показан языковой файл fr.jsonс локализованными строками для агента Copilot и личных вкладок:

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

Локализуемые поля в манифесте приложения

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

Поле манифеста	Описание	Максимальная длина	Обязательный
`@schema`	URL-адрес схемы локализации. Для агентов Copilot используйте devPreview: `https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json`. Версия схемы манифеста должна быть одинаковой для файлов манифеста приложения и локализации.		✔️
`name.short`	Заменяет короткое имя из манифеста приложения указанным значением.	30 символов	✔️
`name.full`	Заменяет полное имя из манифеста приложения указанным значением.	100 символов	✔️
`description.short`	Заменяет краткое описание манифеста приложения указанным значением.	80 символов	✔️
`description.full`	Заменяет полное описание манифеста приложения указанным значением.	4000 символов	✔️
Пары "ключ-значение" для локализованных строк в агентах Copilot	Для агентов Copilot используйте маркеризованные ключи (как указано в приложении `manifest.json`, но без двойных квадратных скобок) с локализованными значениями. Пример: `"DA_Name": "Agent de Communications"`
Пары JSONPath/value для локализованных строк других компонентов приложения	Для всех остальных (классических компонентов приложений Teams) используйте выражения JSONPath в качестве ключей для локализованных значений. Пример: `"staticTabs[0].name": "Accueil"`

Дополнительные сведения см. в разделах Локализация приложения (Microsoft Teams) и Справочник по схеме локализации.

Локализуемые поля в манифесте декларативного агента

Следующие поля локализуются в манифесте декларативного агента:

Поле манифеста	Описание	Максимальная длина	Обязательный
`name`	Имя декларативного агента. Должен содержать по крайней мере один символ, отличный от пробелов.	100 символов	✔️
`description`	Описание декларативного агента. Должен содержать по крайней мере один символ, отличный от пробелов.	1000 символов	✔️
`conversation_starters`	Список (массив) примеров вопросов, на которые может ответить декларативный агент, где каждый пример представлен объектом с `title` и `text`, оба из которых локализуются.	6 объектов в массиве

Дополнительные сведения см. в статье Справочник по манифесту декларативного агента.

Локализуемые поля в манифесте подключаемого модуля API

Следующие поля локализуются в манифесте подключаемого модуля API:

Поле манифеста	Описание	Максимальная длина	Обязательный
`name_for_human`	Короткое, понятное для пользователя имя подключаемого модуля. Он должен содержать по крайней мере один символ, отличный от пробелов.	20 символов	✔️
`description_for_model`	Описание подключаемого модуля, предоставленного модели, включая, для чего предназначен подключаемый модуль и в каких обстоятельствах его функции актуальны.	2048 символов
`description_for_human`	Понятное описание подключаемого модуля.	100 символов	✔️
`logo_url`	URL-адрес, используемый для получения логотипа, который может использоваться оркестратором.
`legal_info_url`	Абсолютный URL-адрес, который находит документ, содержащий условия обслуживания для подключаемого модуля.
`privacy_policy_url`	Абсолютный URL-адрес, который находит документ, содержащий политику конфиденциальности для подключаемого модуля.

Дополнительные сведения см. в статье Справочник по манифесту подключаемого модуля API.

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

Агенты Copilot — это приложения для Microsoft 365

Модель приложений для Microsoft 365

Пакет приложения

Значки приложений

Цветной значок

Контурный значок

Манифест приложения

`copilotAgents` Определения

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

Манифест подключаемого модуля API

Локализация агента

1. Обновите манифесты агента Copilot с помощью маркеризованных ключей.

2. Добавление `localizationInfo` в манифест приложения

3. Создание файла локализации для каждого дополнительного языка

Локализуемые поля в манифесте приложения

Локализуемые поля в манифесте декларативного агента

Локализуемые поля в манифесте подключаемого модуля API

См. также

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

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

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

Агенты Copilot — это приложения для Microsoft 365

Модель приложений для Microsoft 365

Пакет приложения

Значки приложений

Цветной значок

Контурный значок

Манифест приложения

copilotAgents Определения

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

Манифест подключаемого модуля API

Локализация агента

1. Обновите манифесты агента Copilot с помощью маркеризованных ключей.

2. Добавление localizationInfo в манифест приложения

3. Создание файла локализации для каждого дополнительного языка

Локализуемые поля в манифесте приложения

Локализуемые поля в манифесте декларативного агента

Локализуемые поля в манифесте подключаемого модуля API

См. также

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

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

`copilotAgents` Определения

2. Добавление `localizationInfo` в манифест приложения