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

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

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

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

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

• Добавлено behavior_overrides свойство для объекта манифеста декларативного агента.
• Добавлены part_type свойства и part_id для объекта items by SharePoint IDs.
• Добавлены дополнительные свойства для объекта Connection, позволяющие определить область содержимого соединителя Copilot.
• В список добавлена возможность моделей сценариев , которая позволяет агентам использовать модели для конкретных capabilitiesзадач.

Схема JSON

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

Конвенций

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

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

Длина строки

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

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

Объекты 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 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 объекта манифеста декларативного агента. Возможные типы объектов:

• Объект веб-поиска
• Объект OneDrive и SharePoint
• Объект соединителей Copilot
• Графический арт-объект
• Объект интерпретатора кода
• Объект Dataverse
• Объект teams messages
• Объект Email
• Объект пользователя
• Объект моделей сценариев

Пример объекта 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"
        }
      ]
    }
  ]
}

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;
}

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

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

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

Объект сайта

Указывает сайт, на котором декларативный агент может искать содержимое.

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

Объект OneDrive и SharePoint

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

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

Сведения об оптимизации содержимого SharePoint для Copilot см. в статье Оптимизация извлечения содержимого SharePoint.

Объект Items by SharePoint IDs

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

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

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

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

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

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

Объект Connection

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

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

Объект идентификатора элемента

Определяет внешний элемент по его идентификатору.

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

Объект Path

Определяет внешний элемент по пути к нему.

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

Объект имени контейнера

Определяет контейнер по его имени.

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

Объект URL-адреса контейнера

Определяет контейнер по ЕГО URL-адресу.

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

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

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

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

Объект интерпретатора кода

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

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

Объект Dataverse

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

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

Объект источников знаний

Содержит сведения об экземплярах Dataverse для включения в качестве знаний.

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

Объект Tables

Содержит таблицы для область знаний агента.

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

Объект teams messages

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

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

Объект URL-адреса Teams

Определяет канал Teams, команду или чат для собраний.

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

Объект Email

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

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

Объект Folders

Содержит папки для область знаний агента.

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

Объект пользователя

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

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

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

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

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

Объект Model

Определяет модель для конкретной задачи.

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

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

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

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

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

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

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, содержащий параметры для внедрения специальных инструкций в запрос.

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

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

В следующем примере показан файл манифеста декларативного агента, который использует большинство свойств манифеста, описанных в этой статье.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "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?"
    }
  ],
  "actions": [
    {
      "id": "repairsPlugin",
      "file": "repairs-hub-api-plugin.json"
    }
  ],
  "behavior_overrides": {
    "suggestions": {
      "disabled": true
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  },
  "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": "[email protected]",
      "folders": [
        {
         "folder_id": "inbox"
        }
      ]
    },
    {
      "name": "People"
    },
    {
      "name": "ScenarioModels",
      "models": [
        {
          "id": "model_id"
        }
      ]
    }
  ]
}

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

• Написание действующих инструкций для декларативных агентов
• Справочник по манифесту приложения Microsoft 365