Расширите агента инструментами из REST API (предварительный просмотр)

[Данная статья посвящена предварительному выпуску и может быть изменена.]

Вы можете использовать интерфейсы REST API (включая OpenAI API) для подключения агента, который вы создаете, к внешним системам и доступа к имеющимся данным для использования в агенте. Вы можете подключить своего агента к REST API, предоставив Copilot Studio три функции:

• Спецификация OpenAPI, определяющая функции API-интерфейса и доступные действия
• Сведения о типе необходимой проверки подлинности и сведениях о проверке подлинности пользователей, которые подключаются к API для доступа к внешней системе
• Описания, помогающие языковой модели определять, когда вызывать API для использования данных

Вы можете добавлять REST API для агентов Copilot и кастомных агентов через Copilot Studio.

Агенты Copilot позволяют создателю объединять несколько источников данных, таких как соединители, API, подсказки и источники знаний, в один агент. Используйте этот агент для расширения опыта агентов под брендом Microsoft, таких как Microsoft 365 Copilot.

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

Предпосылки

• Квалификация уровня Maker и лицензия Copilot Studio.
• Копия спецификации OpenAPI для REST API, к которому вы хотите подключиться
• Знание типа аутентификации, необходимой для подключения к API, а также деталей аутентификации.

Добавьте инструмент REST API к вашему агенту

Чтобы добавить инструмент REST API к вашему агенту, выполните следующие шаги:

1. Добавьте новый инструмент агента и выберите REST API
2. Предоставить спецификацию, описание и решение API
3. Предоставление данных аутентификации
4. Выберите инструменты из API
5. Рецензирование и публикация

В следующих разделах вы пройдёте процесс шаг за шагом.

Процесс добавления REST API одинаков как для пользовательских агентов, так и для агентов Microsoft 365 Copilot.

Добавьте новый инструмент агента и выберите REST API

1. Перейдите на страницу обзора вашего агента.

2. В разделе «Инструменты » выберите « Добавить инструмент». Вы также можете зайти на вкладку «Инструменты » и выбрать «Добавить инструмент».

   Отображается страница инструмента добавления .

3. Выберите RESTAPI>.

Предоставление спецификации API, описания и решения

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

   

   Замечание

   Спецификация OpenAPI должна быть JSON-файлом в формате v2. Если вы подаёте спецификацию v3, процесс создания автоматически переводит её в спецификацию v2.

   После загрузки спецификации экран обновляется, показывая имя файла спецификации и детали.

   

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

2. Проверьте детали, затем выберите «Далее».

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

   

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

   Например, первоначальное описание звучит так: «Простой сервис для управления билетами».

   Лучшее описание: «Система, используемая для получения, извлечения, поиска и отображения существующих билетов от SunnyADO. Это позволяет пользователям обновлять, изменять и управлять билетами, чтобы предоставлять больше данных для улучшения записей».

3. Введите улучшенное описание в поле Описание.

4. В разделе Решение в раскрывающемся списке будут перечислены все решения, доступные в текущей среде. Выберите решение, которое нужно использовать. Узнайте больше о решениях в концепциях решений.

   

   Если у вас есть предпочтительное решение или выбранный вами соединитель уже присутствует в решении, это решение выбирается автоматически.

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

   Замечание

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

5. Выбрав решение, нажмите кнопку Далее , чтобы продолжить.

Предоставление сведений о проверке подлинности

Появляется страница аутентификации . Выберите тип аутентификации для API.

1. Выберите метод проверки подлинности из списка. Выберите один из трёх вариантов:

   • Нет: Для доступа к API не требуется аутентификация.
   • Ключ API: выберите этот вариант, если вашему API требуется ключ API для аутентификации. Во время выполнения, когда агент хочет использовать инструмент API, он просит пользователя пройти аутентификацию. Пользователь предоставляет API-ключ, и агент подключается к API с помощью этого ключа.
   • Аутентификация 2.0: Выберите этот вариант, если ваш MCP-сервер использует OAuth 2.0 для аутентификации. OAuth 2.0 позволяет отдельным пользователям аутентифицироваться в API через провайдера идентификации. Этот метод аутентификации позволяет пользователю предоставлять разрешения вашему приложению (агенту) без передачи их учетных данных агенту.

2. Введите необходимые поля для выбранного метода аутентификации. Поля различаются в зависимости от метода проверки подлинности.

   • Нет: Нет информации.
   • Ключ API:
     • Метка параметра: Текстовая метка для показа параметра API пользователям.
     • Имя параметра: Фактическое имя ключа API, который используется либо в заголовке, либо в строке запроса.
     • Расположение параметров: Как вы отправляете ключ для API. Выберите либо заголовок , либо запрос.
   • Авторизация 2.0:
     • Идентификатор клиента: идентификатор клиента, который выдаёт поставщик идентичности при регистрации приложения. Идентификатор клиента сообщает провайдеру идентификации, какое приложение делает запрос.
     • Клиентский секрет: Клиентский секрет — это провайдер идентификации при регистрации приложения. Ваш агент отправляет секрет клиента вместе с идентификатором клиента, чтобы доказать, что он уполномочен запрашивать токены доступа для сервера MCP.
     • URL авторизации: конечная точка поставщика идентификации, где ваш агент перенаправляет пользователя на вход и предоставление разрешения агенту (карта согласия отображается в чате агента). Пользователь здесь аутентифицируется, а затем провайдер идентификации отвечает агенту по URL обратного вызова с кодом авторизации.
     • URL токена: конечная точка, где ваш агент обменяет код авторизации (или токен обновления) на токен доступа и токена обновления. Токен доступа позволяет вашему агенту использовать MCP-сервер от имени пользователя. Токены обновления позволяют вашему агенту получать новый доступ и токены обновления с точки обновления после истечения срока действия предыдущего токена.
     • Обновление URL: конечная точка для запроса нового токена доступа с помощью токена обновления (чтобы пользователю не приходилось снова входить в систему после истечения срока действия токена).
     • Область применения: (Необязательно): Права, которые ваше приложение запрашивает, в виде списка с разделённым пробелом.
     • Какая Microsoft 365 организация получает доступ к конечным точкам: Эта настройка ограничивает доступ к исходнику либо для организации создателя, либо для всех организаций. Выберите из:
       • Только моя организация
       • Любые Microsoft 365 организации
     • Какое приложение (клиент) может использовать конечные точки: GUID, определяющий клиентскую систему, с помощью которой можно получить доступ к этим данным. Приложения могут включать Microsoft 365, Power Automate и другие варианты.

3. Когда вы заполните все поля, выберите «Далее».

   Появляется страница «Выбрать и настроить инструмент », где можно выбрать инструменты для включения через API.

   

Выберите инструменты из API

Выберите инструменты, поддерживаемые API, из REST API для добавления в ваш агент. В целом, REST API предлагает ряд инструментов через различные комбинации методов endpoint и HTTP (get, put, post, delete и т.д.), определённых в спецификации API. В некоторых случаях вы можете не захотеть, чтобы пользователи агента имели возможность выполнять все действия, которые обычно предлагает API. Например, спецификация API может включать возможность обновления и удаления, но вы хотите, чтобы пользователи вашего агента могли создавать записи.

1. Выберите инструмент из списка для настройки.

   Отображается страница «Настрой инструмент ».

   

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

3. Заполнив поля, выберите Далее.

   Отображается страница «Проверить параметры вашего инструмента ».

   

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

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

5. После заполнения описаний выберите Далее.

   Первый инструмент теперь настроен и отображается в списке выбранных инструментов на странице «Выбрать и настроить плагин».

   

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

   Отображается страница «Обзор вашего инструмента ». На странице представлены детали настроенного инструмента REST API.

   

Проверка и публикация

1. Если нужно внести обновления, выберите «Назад » и внесите изменения. В противном случае щелкните Далее.

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

2. Выберите Создать соединение, чтобы продолжить. Вы возвращаетесь на экран инструмента добавления .

3. Выберите REST API в селекторе типов инструментов. Вы можете увидеть новые инструменты через свой API. В каждом инструменте, который вы добавили из API, должна быть одна запись.

4. Для каждого из новых настроенных инструментов из API создайте или выберите соединение с API и добавьте инструмент к вашему агенту:

   1. На экране «Добавить» инструмент выберите этот инструмент.
   2. В разделе «Подключение» выберите существующее соединение или выберите «Создать новое соединение».
   3. Введите любую необходимую информацию для соединения, затем выберите Создать , чтобы создать соединение с инструментом.
   4. Выберите Add и Configuration , чтобы добавить инструмент в ваш агент.

   

Инструменты из REST API теперь доступны для использования в вашем агенте.