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

Note

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

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

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

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

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

Important

Эта статья содержит документацию по предварительной версии Microsoft Copilot Studio и может быть изменена.

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

Если вы создаете агент, готовый для рабочей среды, см. Обзор Microsoft Copilot Studio.

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

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

Note

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

Необходимые условия

• Учетные данные уровня "создатель" и лицензия 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. Выберите Новый инструмент>REST API.

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

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

   

   Note

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

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

   

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

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

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

   

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

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

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

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

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

   

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

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

   Note

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

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

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

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

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

   • Нет: для доступа к API не требуется аутентификация.
   • Ключ API: выберите этот вариант, если для аутентификации API требуется ключ API. Во время выполнения, когда агент хочет использовать API-инструмент, он просит пользователя пройти аутентификацию. Пользователь предоставляет ключ API, и агент подключается к API с помощью этого ключа.
   • Auth 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

Выберите инструменты из REST API для добавления в агента. Как правило, REST API предоставляет широкий спектр инструментов посредством различных сочетаний конечных точек и 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. Выберите Добавить и настроить, чтобы добавить инструмент в агента.

   

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

Tip

Чтобы быстрее находить нужный инструмент, ищите его с помощью строки поиска.