Декларативная схема агента 1.6 для #REF!

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

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

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

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

• Добавлено необязательное sensitivity_label свойство для указания меток конфиденциальности Purview для агента , только если агент содержит внедренные файлы.
• Добавлено необязательное worker_agents свойство для указания других декларативных агентов, которые могут использоваться этим агентом.
• Добавлено необязательное user_overrides свойство для указания настроенных возможностей, которые может изменять пользователь агента.
• Добавлена возможность внедренных знаний , позволяющая агентам использовать локальные файлы в качестве знаний.
• Добавлено items_by_id свойство для объекта meetings, позволяющее создателям агентов ограничить собрания, доступные агенту.
• Добавлено include_related_content свойство для объекта people, что позволяет создателям агентов включать связанные документы, сообщения электронной почты и сообщения Teams при поиске содержимого людей.
• Добавлено group_mailboxes свойство для объекта email.

Схема JSON

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

Конвенций

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

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

Длина строки

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

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

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

• Объект веб-поиска
• Объект #REF! и #REF!
• Объект соединителей Copilot
• Графический арт-объект
• Объект интерпретатора кода
• Объект Dataverse
• Объект сообщений #REF!
• Объект 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<Sites = [
    {
        url: "https://contoso.com"
    }
  ]>;

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

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

  op graphicArt is AgentCapabilities.GraphicArt;

  op codeInterpreter is AgentCapabilities.CodeInterpreter;

  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 meetings is AgentCapabilities.Meetings;
}

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

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

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

Объект сайта

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

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

Объект #REF! и #REF!

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

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

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

Объект Items by #REF! IDs

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

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

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

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

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

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

Объект Connection

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

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

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

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

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

Объект Path

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Объект Dataverse

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

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

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

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

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

Чтобы найти уникальный skill идентификатор для источников знаний Dataverse, которые необходимо включить:

1. В Copilot Studio в области слева выберите Агенты>Copilot для 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 содержит следующее свойство.

Объект сообщений #REF!

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

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

Объект URL-адреса #REF!

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

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

Объект Email

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

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

Объект Folders

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

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

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

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

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

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

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

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

Объект Model

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

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

Объект Meetings

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

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

Объект идентификатора собрания

Определяет собрание.

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

Внедренный объект знаний

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

Внедренные файлы знаний имеют максимальный размер файла 1 МБ и должны иметь один из следующих типов документов:

• документ #REF! (.doc, .docx)
• Презентация #REF! (.ppt, .pptx)
• Книга Excel (.xls, .xlsx)
• Обычный текст (TXT)
• Portable Document Format (PDF)

Внедренный объект знаний содержит следующие свойства:

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

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

Объект File

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

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

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

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

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

Объект метки конфиденциальности

Необязательный объект JSON, указывающий метку конфиденциальности #REF! для внедренных файлов в агенте. Он содержит самую высокую защиту среди всех файлов, внедренных в агенты в свойстве Embedded Knowledge.

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

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

Объект агента рабочей роли

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

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

Объект переопределения пользователя

Определяет возможности, настроенные в объекте Capabilities, которые пользователь может переопределить с помощью элемента управления пользовательского интерфейса в #REF!. Единственным поддерживаемым действием является remove, которое включает переключатель в пользовательском интерфейсе, позволяя пользователю включать или отключать возможность, используемую для создания ответов.

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

Пример объекта переопределения пользователя

В следующем примере включается переключатель элементов управления для возможностей поиска в Интернете и сообщений #REF! , что позволяет пользователю включать или выключать эти возможности.

{
  "user_overrides": [
    {
      "path": "$.capabilities[?(@.name == 'WebSearch')]",
      "allowed_actions": ["remove"]
    },
    {
      "path": "$.capabilities[?(@.name == 'TeamsMessages')]",
      "allowed_actions": ["remove"]
    }
  ]
}

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

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

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