SDK del agente (versión preliminar)

Reenvía las cargas de actividad del SDK de Bot Framework o Microsoft Agents a un punto de conexión del agente proporcionado por el usuario. La dirección URL del punto de conexión del agente se proporciona por llamada como parámetro de entrada. La autenticación se selecciona al crear la conexión: sin autenticación, una clave de API estática o Microsoft Entra ID OAuth (client_credentials o inicio de sesión de usuario). Cuando se selecciona OAuth, la audiencia del token de portador (dirección URL de recurso configurada en la conexión) debe coincidir con la audiencia esperada por el agente de destino.

Este conector está disponible en los siguientes productos y regiones:

El conector del SDK del agente reenvía las cargas de actividad del SDK de Bot Framework o Microsoft Agents a un punto de conexión del agente proporcionado por el usuario. La dirección URL del punto de conexión del agente se proporciona por llamada como parámetro de entrada. La conexión selecciona cómo se autentica el conector en el agente: sin autenticación, una clave de API estática, un token de solo aplicación (credenciales de cliente) Microsoft Entra ID o un token de usuario delegado (inicio de sesión de usuario) Microsoft Entra ID. Para ambas opciones de Microsoft Entra ID, la audiencia del token de portador (dirección URL de recurso configurada en la conexión) debe coincidir con la audiencia esperada por el agente de destino.

Prerequisites

• Un SDK de agentes de Microsoft implementado o agente de Bot Framework accesible a través de HTTPS.
• Para Microsoft Entra ID (credenciales de cliente): una aplicación Microsoft Entra ID registrada en el inquilino que hospeda el agente, configurada con la client_credentials concesión y el permiso para llamar al agente de destino.
• Para Microsoft Entra ID (inicio de sesión de usuario): la propia aplicación de Microsoft Entra ID del agente (su identificador de aplicación de Microsoft) con un secreto de cliente, un ámbito de API expuesto al que los usuarios pueden dar su consentimiento, el Microsoft Graph User.Read ("Iniciar sesión y leer el perfil de usuario") ha delegado el permiso con consentimiento y https://global.consent.azure-apim.net/redirect/agentsdk se ha agregado como un URI de redirección web.
• Para las opciones de clave de API y credenciales de cliente, el público de tokens esperado del agente (normalmente el identificador de aplicación de Microsoft del agente, por ejemploapi://<appId>, o el GUID del identificador de aplicación). Para el inicio de sesión del usuario, la audiencia debe ser el GUID del identificador de aplicación (consulte a continuación).

Obtención de las credenciales

Microsoft Entra ID (credenciales de cliente)

El conector envía un token de solo aplicación. Para autenticar las solicitudes de API, necesitará lo siguiente:

1. Identificador de inquilino de la aplicación Microsoft Entra ID.
2. Identificador de cliente (id. de aplicación) de la aplicación Microsoft Entra ID.
3. Secreto de cliente para esa aplicación.
4. La dirección URL del recurso que coincide con la audiencia esperada por el agente de destino (patrón de autenticación de aptitudes de Bot Framework).

Proporcione estos valores al crear una conexión. Cree una conexión por agente si las audiencias difieren.

Microsoft Entra ID (inicio de sesión de usuario)

El conector envía el token delegado de la cuenta que inició sesión en la conexión, por lo que el agente puede intercambiarlo en nombre de esa cuenta (por ejemplo, con el controlador SDK de agentes de Microsoft 365ConnectorUserAuthorization). Necesitará lo siguiente:

1. Identificador de inquilino de la aplicación Microsoft Entra ID del agente.
2. Id. de cliente: el propio identificador de aplicación de Microsoft del agente. El SDK de agentes de Microsoft 365 intercambia el token en nombre del usuario solo cuando el token se emitió a la propia aplicación del agente.
3. Secreto de cliente para esa aplicación.
4. La dirección URL del recurso: el identificador de aplicación (GUID) de Microsoft del agente, el mismo valor que el identificador de cliente. Dado que la propia aplicación del agente es el cliente y el recurso, Microsoft Entra requiere el GUID aquí (AADSTS90009 de lo contrario); api://<appId> no se admite para esta opción.

Proporcione estos valores al crear una conexión y, a continuación, inicie sesión y dé su consentimiento al ámbito expuesto del agente. Cree una conexión por agente.

La aplicación también necesita el permiso delegado Microsoft Graph User.Read ("Iniciar sesión y leer perfil de usuario") con consentimiento; sin él, se produce un error de inicio de sesión con AADSTS90008.

Para intercambiar el token de una API de bajada, configure los permisos delegados de esa API en la aplicación del agente y obtenga el consentimiento de usuario o administrador necesario. Exponer un ámbito en la propia API del agente no concede permisos de bajada.

Limitaciones y problemas conocidos

• La agentEndpoint entrada debe ser una dirección URL HTTPS completa (por ejemplo, https://my-agent.azurewebsites.net). El conector anexa /api/messages y reenvía la carga de actividad.
• El conector reenvía la carga de actividad as-is y no establece deliveryMode. El agente responde de forma asincrónica (entrega normal) mediante el POSTing reply activities back to the serviceUrl supplied on the inbound activity (the caller, p. ej., Microsoft Copilot Studio, proporciona una devolución de llamada serviceUrlcon clave SAS ).
• Una conexión Microsoft Entra ID (inicio de sesión de usuario) siempre envía el token delegado de la cuenta que inició sesión en la conexión, para cada llamada realizada con esa conexión, incluidas las llamadas en nombre de otras personas que chate con el agente. No envía un token independiente para cada llamador, por lo que el usuario de from la actividad puede diferir del usuario del token. Autorice las solicitudes solo como la cuenta en el token validado y no trate los encabezados de from la actividad ni de la solicitud como autoridad de la persona de chat. Si el agente debe actuar como cada persona que chatea con él, no use este tipo de conexión.
• Si se revoca el consentimiento de la cuenta de inicio de sesión o su sesión ya no se puede actualizar, vuelva a iniciar sesión en la conexión.
• Este conector está en versión preliminar. La disponibilidad y las funcionalidades están sujetas a cambios.

Creación de una conexión

El conector admite los siguientes tipos de autenticación:

Clave de API

Identificador de autenticación: apiKey

Aplicable: Todas las regiones

Autentíquese con una clave de API estática que el agente de destino espera en un encabezado HTTP personalizado. Especifique el nombre del encabezado (por ejemplo, x-api-key) y su valor.

Esta conexión no se puede compartir. Si la aplicación de energía se comparte con otro usuario, se pedirá a otro usuario que cree explícitamente una nueva conexión.

Microsoft Entra ID (credenciales de cliente)

Identificador de autenticación: oauthClientCredentials

Aplicable: Todas las regiones

Mint OAuth bearer tokens de una aplicación de Microsoft Entra ID mediante el flujo de client_credentials. La audiencia del token de portador (DIRECCIÓN URL del recurso) debe coincidir con la audiencia esperada por el agente de destino.

Esta conexión no se puede compartir. Si la aplicación de energía se comparte con otro usuario, se pedirá a otro usuario que cree explícitamente una nueva conexión.

Microsoft Entra ID (inicio de sesión de usuario)

Identificador de autenticación: oauthAuthorizationCode

Aplicable: Todas las regiones

Inicie sesión a través de la aplicación Microsoft Entra ID del agente de destino (flujo de código de autorización) y envíe el token de portador delegado de la cuenta de inicio de sesión. Todas las llamadas realizadas con esta conexión usan la cuenta que inició sesión en la conexión, no la persona que chatea con el agente. Para intercambiar el token en nombre del usuario, el agente necesita sus permisos delegados de bajada y el consentimiento configurados.

Esta conexión no se puede compartir. Si la aplicación de energía se comparte con otro usuario, se pedirá a otro usuario que cree explícitamente una nueva conexión.

Sin autenticación

Identificador de autenticación: anónimo

Aplicable: Todas las regiones

Llame al punto de conexión del agente de destino sin ningún encabezado de autenticación. Úselo solo con agentes que acepten explícitamente llamadas anónimas.

Se trata de una conexión que se puede compartir. Si la aplicación de energía se comparte con otro usuario, también se comparte la conexión. Para obtener más información, consulte la información general de Connectors para aplicaciones de lienzo: Power Apps | Microsoft Docs

Valor predeterminado [EN DESUSO]

Aplicable: Todas las regiones

Esta opción solo es para conexiones anteriores sin un tipo de autenticación explícito y solo se proporciona para la compatibilidad con versiones anteriores.

Esta conexión no se puede compartir. Si la aplicación de energía se comparte con otro usuario, se pedirá a otro usuario que cree explícitamente una nueva conexión.

Acciones

Envío de actividad al agente

Definiciones

object