Расширение агента с помощью действий из 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-интерфейсы, запросы и источники знаний. Пользовательские агенты можно использовать напрямую, интегрировав их на веб-сайты или в другие каналы.

Заметка

Действия API должны создаваться из OpenAPI спецификации v2. Это требование обусловлено поведением Power Platform при обработке спецификаций API. Если спецификация v3 отправлена, она автоматически преобразуется в спецификацию v2 в процессе создания.

Предварительные требования

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

Для всех типов взаимодействия с агентами необходимо иметь учетные данные уровня создателя и лицензию Copilot Studio.

Вам также потребуется копия спецификации OpenAPI, сведения о типе требуемой проверки подлинности и сведения о проверке подлинности.

Добавление действия REST API в агент

Добавление REST API в агент состоит из нескольких шагов. В следующих разделах рассматривается этот процесс.

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

Этот процесс состоит из нескольких этапов.

Добавление действия в агент

1. Начните со страницы Обзор вашего агента.

   

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

   

   Запускается мастер создания действия с отображаемой страницей Выберите действие.

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

1. В нижней части страницы выберите Добавить API для пользовательского соединителя.

   

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

   

   Заметка

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

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

   

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

3. Проверьте сведения, затем выберите Далее.

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

   

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

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

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

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

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

   

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

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

   Заметка

   Если вы не видите решение по умолчанию или CDS в качестве варианта в этом случае, мы рекомендуем использовать индивидуальное решение для упрощения управления. Дополнительные сведения см. в разделе Решение по умолчанию и пользовательское решение.

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

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

Откроется страница Проверка подлинности, на которой можно выбрать тип проверки подлинности, используемый для API.

Заметка

В настоящее время доступны следующие варианты: Нет, Auth 2.0 и API.

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

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

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

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

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

   

Выбор действий для API

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

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

   Откроется страница Настройка действия подключаемого модуля.

   

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

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

   Отображается страница Проверка параметров вашего действия.

   

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

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

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

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

   

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

   Откроется страница Проверка действия. На этой странице содержатся сведения о настроенном действии REST API.

   

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

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

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

2. После завершения публикации вы вернетесь на экран Выберите действие. Здесь вы можете добавить только что настроенный REST API в свой агент Copilot или пользовательский агент и завершить настройку компонента.

   

Действие REST API теперь доступно для использования в агенте.

Совет

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