Подключаемые модули API для Microsoft 365 Copilot

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

Примечание.

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

Важно!

Подключаемые модули API поддерживаются только как действия в декларативных агентах. Они не включены в Microsoft 365 Copilot.

Подключаемый модуль API предоставляет документ описания OpenAPI (при использовании REST API) и манифест подключаемого модуля, который Copilot использует для изучения возможностей API. Затем Copilot может решить, когда API установленного и включенного подключаемого модуля подходит для ответа на любой запрос. Дополнительные сведения о файле манифеста, необходимом для подключаемого модуля API, см. в статье Схема манифеста подключаемого модуля API для Microsoft 365 Copilot.

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

GET /budgets?name=contoso%20travel

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

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

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

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

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

Пользователь спрашивает агента: "Сколько осталось в четвертом бюджете реконструкции лобби кофе?"
Агент определяет связанный с бюджетом подключаемый модуль из доступных подключаемых модулей, имеющих функцию GetBudget для получения сведений о бюджете. Он сопоставляет части вопроса пользователя с параметрами функции: budgetName="".
Агент просит пользователя разрешить ему отправку Fourth Coffee lobby renovation в подключаемый модуль.
Пользователь разрешает предоставление общего доступа к данным с подключаемым модулем один раз или разрешает всегда предоставлять общий доступ к данным для этой функции.
Если API подключаемого модуля требует проверки подлинности, подключаемый модуль запрашивает маркер или ключ API из хранилища маркеров.
Хранилище маркеров возвращает маркер или ключ. При необходимости хранилище маркеров заставляет агент запрашивать у пользователя вход.
Агент отправляет запрос в API подключаемого модуля, который размещен за пределами Microsoft 365.
```
GET /budgets?budgetName=Fourth+Coffee+lobby+renovation
```
API возвращает ответ API в формате, указанном в спецификации OpenAPI.
```
{
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}
```
Агент создает ответ на основе ответа API.
Агент отправляет ответ "Доступные средства, оставшиеся в четвертом бюджете реконструкции лобби кофе составляет $ 5000".

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

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

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

По умолчанию API, которые только извлекают данные, предоставляют пользователю параметр "Всегда разрешать", а API, изменяющие данные, — нет. Разработчики подключаемых модулей могут переопределить эти значения по умолчанию. Дополнительные сведения см. в разделе Запросы на подтверждение подключаемых модулей API для Microsoft 365 Copilot.

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

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

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

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

Были ли сведения на этой странице полезными?

Last updated on 2025-11-12