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

Подключаемые модули для #REF!

Подключаемые модули позволяют декларативным агентам в #REF! взаимодействовать с серверами MCP или REST API с описанием OpenAPI. С помощью подключаемого модуля пользователи могут попросить декларативный агент не только запрашивать сведения у сервера MCP или REST API, но и создавать, обновлять и удалять данные и объекты. Все, что может сделать сервер MCP или REST API, доступно через запросы на естественном языке.

Примечание.

Помимо вызова серверов MCP или REST API существует функция предварительной версии, которая позволяет подключаемого модуля вызывать API в локальной библиотеке. Мы рекомендуем поэкспериментировать с этой функцией, но ее не следует использовать в рабочем подключаемом модуле. Дополнительные сведения см. в статье Создание подключаемых модулей API для #REF! с помощью библиотеки JavaScript для Office.

Важно!

Подключаемые модули поддерживаются только как действия в декларативных агентах. Они не включены в #REF!.

Подключаемый модуль предоставляет манифест подключаемого модуля, который Copilot использует для изучения возможностей сервера MCP или API подключаемого модуля. Затем Copilot может решить, когда установленный и включенный подключаемый модуль подходит для ответа на любой запрос. Дополнительные сведения о файле манифеста, который требуется для подключаемого модуля, см. в статье Схема манифеста подключаемого модуля для #REF!.

Пример подключаемого модуля

Рассмотрим сервер MCP для бюджетов, который позволяет запрашивать и создавать бюджеты, взимать расходы или добавлять средства в существующие бюджеты. Запрос "Сколько осталось в бюджете на поездки Contoso" может вызвать подключаемый модуль бюджета, вызвав get-budgets средство.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

Copilot использует ответ из результата инструмента для создания ответа: "Бюджет на поездки Contoso в настоящее время имеет 5000 долл. США в наличии. Если вам нужно выделить средства на определенные категории или отслеживать расходы, я могу помочь вам в этом. Просто дайте мне знать, как я могу помочь!"

Запрос "Взимать 500 долл. США в бюджете на поездки Contoso за авиабилет Меган" можно перевести в следующий вызов средства.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

Copilot использует ответ от средства для создания ответа: "Бюджет на поездки Contoso в настоящее время содержит 5000 долларов США в наличии. Если вам нужно выделить средства на определенные категории или отслеживать расходы, я могу помочь вам в этом. Просто дайте мне знать, как я могу помочь!"

Запрос "Взимать 500 долл. США в бюджете на поездки Contoso за авиабилет Меган" можно перевести в следующий вызов средства MCP.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "charge-budget",
    "arguments": {
      "budgetName": "contoso travel",
      "amount": 500,
      "description": "Megan's airline ticket"
    }
  }
}

Copilot отвечает пользователю, используя возвращенную информацию: "Плата в размере $ 500 за авиабилет Меган была успешно обработана. Бюджет на поездки Contoso теперь имеет 4500 долларов США, остающихся в наличии. Если вам нужно выполнить еще какие-либо транзакции или вам нужна дополнительная помощь с бюджетом, пожалуйста, сообщите мне!

Принцип работы подключаемых модулей

Схема последовательностей, показывающая, как работает подключаемый модуль API

  1. Пользователь спрашивает агента: "Сколько осталось в четвертом бюджете реконструкции лобби кофе?"

  2. Агент определяет связанный с бюджетом подключаемый модуль из доступных подключаемых модулей, имеющих средство сервера MCP или API GetBudget для получения сведений о бюджете. Он сопоставляет части вопроса пользователя с параметрами функции: budgetName="".

  3. Агент просит пользователя разрешить ему отправку Fourth Coffee lobby renovation в подключаемый модуль.

  4. Пользователь разрешает предоставление общего доступа к данным с подключаемым модулем один раз или разрешает всегда предоставлять общий доступ к данным для этой функции.

  5. Если сервер MCP или API подключаемого модуля требует проверки подлинности, подключаемый модуль запрашивает маркер или ключ API из хранилища маркеров.

  6. Хранилище маркеров возвращает маркер или ключ. При необходимости хранилище маркеров заставляет агент запрашивать у пользователя вход.

  7. Агент отправляет запрос на сервер MCP подключаемого модуля или API, размещенный за пределами Microsoft 365.

  8. Сервер MCP или API возвращает ответ.

    {
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}

  9. Агент создает ответ на основе сервера MCP или ответа API.

  10. Агент отправляет ответ "Доступные средства, оставшиеся в четвертом бюджете реконструкции лобби кофе составляет $ 5000".

Подтверждающие действия

Copilot запрашивает у пользователя перед отправкой данных в первый раз в подключаемый модуль.

Снимок экрана: диалоговое окно подтверждения подключаемого модуля.

После того как пользователь подтвердит подключение, средства сервера MCP и API, которые только извлекают данные, не требуют подтверждения, в то время как средства и API, изменяющие данные, делают это. Разработчики подключаемых модулей могут переопределить эти значения по умолчанию. Дополнительные сведения см. в разделе Запросы на подтверждение подключаемых модулей API для #REF!.

Настройка презентации ответа

Copilot создает диалоговые ответы, используя данные из сервера MCP или ответов API. Подключаемые модули могут настраивать эти ответы, предоставляя шаблоны адаптивных карточек для структурированного отображения данных.

Снимок экрана: ответ адаптивной карточки из подключаемого модуля API

Оптимизация подключаемого модуля для оркестратора Copilot

#REF! может уникально выбрать нужный навык из многих навыков в своем репертуаре. Но как вы можете убедиться, что Copilot выбирает ваш подключаемый модуль , чтобы обеспечить правильный навык?

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

Способ описания подключаемого модуля в оркестраторе зависит от типа создаваемого подключаемого модуля, как описано в следующей таблице.

Тип подключаемого модуля Описано Дополнительные сведения
Подключаемые модули API Описание OpenAPI Как сделать документ OpenAPI эффективным при расширении Copilot
Действия Copilot Studio Имена и описания в карте бесед Copilot Studio Оркестрация разделов и действий совместного использования с помощью генеративного ИИ
Подключаемые модули расширений для сообщений Манифест приложения Рекомендации по подключаемым модулям расширения сообщений

Создание пакетов подключаемого модуля

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

  • Набор средств агентов Microsoft 365 в Visual Studio или Visual Studio Code может создавать пакеты подключаемых модулей на основе существующего сервера MCP или описания OpenAPI. Набор средств агентов также содержит начальные проекты с примером API и соответствующим пакетом подключаемого модуля.
  • Kiota — это программа командной строки и расширение Visual Studio Code, которое может создавать пакеты подключаемых модулей на основе существующего описания OpenAPI.

Ограничения

Подключаемые модули декларативного агента

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

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

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

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

  • Last updated on