Пакет SDK агента (предварительная версия)

Перенаправит полезные данные действий пакета SDK для агентов Bot Framework или Microsoft в конечную точку агента, предоставленной пользователем. URL-адрес конечной точки агента предоставляется для каждого вызова в качестве входного параметра. Проверка подлинности выбирается при создании подключения: проверка подлинности, статический ключ API или Microsoft Entra ID OAuth (client_credentials или вход пользователя). При выборе OAuth аудитория маркера носителя (URL-адрес ресурса, настроенный для подключения), должна соответствовать аудитории, ожидаемой целевым агентом.

Этот соединитель доступен в следующих продуктах и регионах:

Service	Class	Regions
Copilot Studio	Стандарт	Все регионы Power Automate за исключением следующих: - Правительство США (GCC) - Правительство США (GCC High) — Облако Китая, управляемое 21Vianet - Министерство обороны США (DoD)
Логические приложения	Стандарт	Все регионы Logic Apps , кроме следующих: — Регионы Azure для государственных организаций — Регионы Azure Для Китая - Министерство обороны США (DoD)
Power Apps	Стандарт	Все регионы Power Apps кроме следующих: - Правительство США (GCC) - Правительство США (GCC High) — Облако Китая, управляемое 21Vianet - Министерство обороны США (DoD)
Power Automate	Стандарт	Все регионы Power Automate за исключением следующих: - Правительство США (GCC) - Правительство США (GCC High) — Облако Китая, управляемое 21Vianet - Министерство обороны США (DoD)

Контакт
Имя.	Microsoft
URL	https://support.microsoft.com

Метаданные соединителя
Publisher	Microsoft
Веб-сайт	https://www.microsoft.com
Политика конфиденциальности	https://privacy.microsoft.com/
Categories	Продуктивность

Соединитель SDK агента перенаправит полезные данные действия пакета SDK Для агентов Bot Framework или Microsoft в конечную точку агента, предоставленной пользователем. URL-адрес конечной точки агента предоставляется для каждого вызова в качестве входного параметра. Подключение выбирает способ проверки подлинности соединителя в агенте: без проверки подлинности, статического ключа API, маркера Microsoft Entra ID приложения (учетные данные клиента) или Microsoft Entra ID делегированного маркера пользователя (вход пользователя). Для обоих Microsoft Entra ID параметров аудитория маркеров носителя (URL-адрес ресурса, настроенный для подключения), должна соответствовать аудитории, ожидаемой целевым агентом.

Prerequisites

Развернутый пакет SDK для агентов Microsoft или агент Bot Framework, доступный по протоколу HTTPS.
Для Microsoft Entra ID (учетные данные клиента): приложение Microsoft Entra ID, зарегистрированное в клиенте, на котором размещен агент, настроено с client_credentials предоставлением и разрешением на вызов целевого агента.
Для Microsoft Entra ID (вход пользователя): собственное приложение Microsoft Entra ID агента (его идентификатор приложения Microsoft) с секретом клиента, областью открытого API, на которую пользователи могут согласиться, Microsoft Graph User.Read ("Вход и чтение профиля пользователя") делегированное разрешение с согласием и https://global.consent.azure-apim.net/redirect/agentsdk добавлено в качестве URI веб-перенаправления.
Для параметров ключа API и учетных данных клиента ожидаемая аудитория маркера агента (например, идентификатор приложения Microsoft агента, например api://<appId> GUID идентификатора приложения). Для входа пользователей аудитория должна быть ИДЕНТИФИКАТОРом приложения (см. ниже).

Получите ваши учетные данные

Microsoft Entra ID (учетные данные клиента)

Соединитель отправляет маркер только для приложений. Для проверки подлинности запросов API вам потребуется:

Идентификатор клиента приложения Microsoft Entra ID.
Идентификатор клиента (идентификатор приложения) приложения Microsoft Entra ID.
Секрет клиента для этого приложения.
URL-адрес ресурса, соответствующий аудитории целевому агенту (шаблон проверки подлинности навыка Bot Framework).

Укажите эти значения при создании подключения. Создайте одно подключение для каждого агента, если аудитории отличаются.

Соединитель отправляет делегированный маркер учетной записи, вошедшего в подключение, поэтому агент может обмениваться им от имени этой учетной записи (например, с обработчиком Пакет SDK агентов Microsoft 365ConnectorUserAuthorization). Вам потребуется:

Идентификатор клиента приложения Microsoft Entra ID агента.
Идентификатор клиента: собственный Microsoft идентификатора приложения агента. Пакет SDK агентов Microsoft 365 обменивается маркером от имени пользователя, только если маркер был выдан собственному приложению агента.
Секрет клиента для этого приложения.
URL-адрес ресурса: Microsoft идентификатор приложения агента (GUID), то же значение, что и идентификатор клиента. Так как собственное приложение агента является клиентом и ресурсом, Microsoft Entra требует GUID здесь (AADSTS90009 в противном случае); api://<appId> для этого параметра не поддерживается.

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

Приложению также требуется делегированное разрешение Microsoft Graph User.Read ("Вход и чтение профиля пользователя") с согласием; без этого вход завершается ошибкой с AADSTS90008.

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

Известные проблемы и ограничения

Входные agentEndpoint данные должны быть полным URL-адресом HTTPS (например, https://my-agent.azurewebsites.net). Соединитель добавляет /api/messages и перенаправит полезные данные действия.
Соединитель перенаправит полезные данные действия as-is и не задает deliveryMode. Агент отвечает асинхронно (обычной доставкой), выполняя действия ответа POSTing обратно serviceUrl в предоставленный для входящего действия (вызывающий объект, например, Microsoft Copilot Studio, обеспечивает обратный serviceUrlвызов с ключом SAS).
Подключение Microsoft Entra ID (вход пользователя) всегда отправляет делегированный маркер учетной записи, вошедшего в подключение, для каждого вызова, выполняемого с этим подключением, включая звонки от имени других пользователей, общающихся с агентом. Он не отправляет отдельный маркер для каждого вызывающего абонента, поэтому пользователь действия from может отличаться от пользователя в маркере. Авторизуйте запросы только в качестве учетной записи в проверенном токене и не рассматривайте заголовки действия from или запроса как полномочия пользователя чата. Если агент должен действовать как каждый пользователь, общающийся с ним, не используйте этот тип подключения.
Если согласие учетной записи входа отменяется или его сеанс больше не может быть обновлен, войдите в подключение снова.
Этот соединитель находится в предварительной версии. Доступность и возможности могут быть изменены.

Создание подключения

Соединитель поддерживает следующие типы проверки подлинности:


Ключ API	Проверка подлинности со статическим ключом API, который целевой агент ожидает в пользовательском заголовке HTTP. Укажите имя заголовка (например, x-api-key) и его значение.	Все регионы	Недоступен для совместного использования
Microsoft Entra ID (учетные данные клиента)	Маркеры носителя OAuth мяты из приложения Microsoft Entra ID с помощью потока client_credentials. Аудитория маркера носителя (URL-адрес ресурса) должна соответствовать аудитории, ожидаемой целевым агентом.	Все регионы	Недоступен для совместного использования
Microsoft Entra ID (вход пользователя)	Войдите через приложение Microsoft Entra ID целевого агента (поток кода авторизации) и отправьте делегированный маркер носителя учетной записи входа. При каждом вызове с этим подключением используется учетная запись, вошедщая в подключение, а не пользователь, общающийся с агентом. Для обмена маркером от имени пользователя агенту требуется делегированные ниже делегированные разрешения и согласие.	Все регионы	Недоступен для совместного использования
Без проверки подлинности	Вызовите конечную точку целевого агента без заголовка проверки подлинности. Используйте это только с агентами, которые явно принимают анонимные вызовы.	Все регионы	Доступный для общего пользования
По умолчанию [не рекомендуется]	Этот параметр предназначен только для старых подключений без явного типа проверки подлинности и предоставляется только для обратной совместимости.	Все регионы	Недоступен для совместного использования

Ключ API

Идентификатор проверки подлинности: apiKey

Применимо: все регионы

Проверка подлинности со статическим ключом API, который целевой агент ожидает в пользовательском заголовке HTTP. Укажите имя заголовка (например, x-api-key) и его значение.

Это недоступно для общего доступа. Если приложение power предоставляется другому пользователю, пользователю будет предложено явно создать новое подключение.

Имя.	Тип	Description	Обязательный
Имя заголовка ключа API	string	Имя заголовка HTTP, в котором целевой агент ожидает ключ API (например, x-api-key или Ocp-Apim-Subscription-Key).	True
Значение ключа API	Securestring	Значение ключа статического API, отправленное при каждом запросе в конечную точку целевого агента.	True

Microsoft Entra ID (учетные данные клиента)

Идентификатор проверки подлинности: oauthClientCredentials

Применимо: все регионы

Маркеры носителя OAuth мяты из приложения Microsoft Entra ID с помощью потока client_credentials. Аудитория маркера носителя (URL-адрес ресурса) должна соответствовать аудитории, ожидаемой целевым агентом.

Имя.	Тип	Description	Обязательный
Tenant	string	Идентификатор клиента для приложения Microsoft Entra ID	True
идентификатор клиента	string	Идентификатор клиента (или приложения) приложения Microsoft Entra ID.	True
Секрет клиента	Securestring	Секрет клиента приложения Microsoft Entra ID.	True
URL-адрес ресурса	string	Аудитория маркера OAuth. Обычно идентификатор приложения целевого агента Microsoft (например, api://< appId> или GUID идентификатора приложения).	True

Идентификатор проверки подлинности: oauthAuthorizationCode

Применимо: все регионы

Войдите через приложение Microsoft Entra ID целевого агента (поток кода авторизации) и отправьте делегированный маркер носителя учетной записи входа. При каждом вызове с этим подключением используется учетная запись, вошедщая в подключение, а не пользователь, общающийся с агентом. Для обмена маркером от имени пользователя агенту требуется делегированные ниже делегированные разрешения и согласие.

Имя.	Тип	Description	Обязательный
Tenant	string	Идентификатор клиента приложения Microsoft Entra ID целевого агента.	True
идентификатор клиента	string	Идентификатор приложения Microsoft целевого агента. Используйте собственное приложение агента, чтобы агент может обмениваться делегированным маркером от имени пользователя.	True
Секрет клиента	Securestring	Секрет клиента приложения Microsoft Entra ID целевого агента.	True
URL-адрес ресурса	string	Аудитория делегированного токена. Должен быть Microsoft идентификатор приложения целевого агента (GUID), то же значение, что и идентификатор клиента: Microsoft Entra принимает только GUID, когда приложение запрашивает маркер для себя.	True

Без аутентификации

Идентификатор проверки подлинности: анонимный

Применимо: все регионы

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

Это совместное подключение. Если приложение power app предоставлено другому пользователю, подключение также предоставляется совместно. Дополнительные сведения см. в обзоре Connectors для приложений холста — Power Apps | Документация Майкрософт

По умолчанию [не рекомендуется]

Применимо: все регионы

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

Действия

Отправка действия агенту

Перенаправляет полезные данные протокола действий в конечную точку агента в {agentEndpoint}/api/messages. Если подключение использует Microsoft Entra ID OAuth, аудитория маркеров (URL-адрес ресурса подключения) должна равенства аудитории, ожидаемой целевым агентом (шаблон проверки подлинности навыка Bot Framework); создайте одно подключение для каждого агента, если аудитория отличается. Соединитель перенаправит полезные данные действия as-is и не задает "deliveryMode"; агент отвечает асинхронно (обычной доставкой), выполняя действия ответа POSTing на запрос serviceUrl, предоставленный для входящего действия.

Отправка действия агенту

Идентификатор операции:: SendActivity

Параметры

Имя.	Ключ	Обязательно	Тип	Описание
URL-адрес конечной точки агента	agentEndpoint	True	string	Базовый URL-адрес целевого пакета SDK для агентов Microsoft или конечной точки Bot Framework (например, https://my-agent.azurewebsites.net). Соединитель добавляет /api/messages.
			object

Пакет SDK агента (предварительная версия)

Prerequisites

Получите ваши учетные данные

Microsoft Entra ID (учетные данные клиента)

Microsoft Entra ID (вход пользователя)

Известные проблемы и ограничения

Создание подключения

Ключ API

Microsoft Entra ID (учетные данные клиента)

Microsoft Entra ID (вход пользователя)

Без аутентификации

По умолчанию [не рекомендуется]

Действия

Отправка действия агенту

Параметры

Возвращаемое значение

Определения

object