Implementación de una aptitud para su uso en Copilot Studio

SE APLICA A: SDK v4

Una aptitud es un bot que puede usar otro bot. De este modo, puede crear un único bot orientado al usuario y ampliarlo con una o varias aptitudes. Puede obtener más información sobre las aptitudes en general en Acerca de las aptitudes y cómo crearlas en Implementación de una aptitud. Como alternativa, las plantillas de Virtual Assistant contienen un conjunto de aptitudes precompiladas que puede personalizar e implementar en lugar de crear una desde cero.

Si espera que su aptitud se consuma desde un copilot Studio copilot, hay otras restricciones que se aplican a su aptitud para las que debe tener en cuenta.

Manifiesto de restricciones

Copilot Studio aplica restricciones a lo que puede declarar en el manifiesto de aptitud.

• Solo puede declarar 100 o menos acciones.
• Cada acción se limita a 25 entradas o salidas o menos.
• No puede usar el tipo de matriz para entradas o salidas.

Restricción del mismo inquilino

Para garantizar el cumplimiento y la gobernanza adecuada de las aptitudes personalizadas que se registran para su uso en Copilot Studio, el bot de aptitudes debe ser una aplicación registrada en microsoft Entra ID. Al agregar una aptitud, se valida si el identificador de aplicación de la aptitud está en el inquilino del usuario que ha iniciado sesión y el punto de conexión de aptitudes coincide con el de la aplicación Home Page URLregistrada.

Para poder registrar el bot como una aptitud en Copilot Studio, debe asegurarse de que para el bot, la página principal de Azure Portal se establece en la dirección URL del manifiesto de aptitud del bot.

Restricción multiinquilino y multiinquilino

Copilot Studio creó previamente aplicaciones de id. de entra multiinquilino. Sin embargo, ahora está creando aplicaciones de id. de Entra de inquilino único. Para que las aptitudes funcionen correctamente con los agentes en función de las nuevas aplicaciones de id. entra de inquilino único, las aptitudes deben configurarse para una instancia de un solo inquilino.

Conversión de una aptitud existente de varios inquilinos a un solo inquilino

Puede convertir las aptitudes existentes de compatibilidad multiinquilino a soporte técnico de un solo inquilino. Para convertir una aptitud multiinquilino en una aptitud de un solo inquilino, debe realizar los siguientes cambios:

• Creación de un nuevo registro de aplicación de Entra id. de inquilino único
• Actualización de la configuración de aptitudes para usar un solo inquilino
• Implementación de la aptitud
• (Opcional) actualizar el código fuente

Los siguientes valores son necesarios para las aptitudes de un solo inquilino:

Propiedad	Valor
MicrosoftAppType	SingleTenant
MicrosoftAppId	Identificador de aplicación del bot
MicrosoftAppPassword	Contraseña de la aplicación del bot
MicrosoftAppTenantId	Identificador de inquilino de la aplicación del bot

Como referencia, se usaron los siguientes valores para aptitudes multiinquilino:

Propiedad	Valor
MicrosoftAppType	MultiTenant
MicrosoftAppId	Identificador de aplicación del bot
MicrosoftAppPassword	Contraseña de la aplicación del bot
MicrosoftAppTenantId	No aplicable; dejado en blanco para bots multiinquilino

Después de convertir los valores, importe la aptitud en una instancia del agente creada como una instancia de un solo inquilino. También puede ver el registro de la aplicación Entra ID para ver cómo se creó. Vaya a Administrar>autenticación>tipos de cuenta admitidos.

Actualización de código multiinquilino a un solo inquilino

Después de convertir los valores, es posible que tenga que actualizar también el código para permitir la conexión del inquilino especificado a la aptitud. Para obtener más información, consulte BotBuilder-Samples .

Validación realizada durante el registro de una aptitud

Cuando un usuario final intenta conectarse a su aptitud desde su copiloto, primero deberá importar la aptitud a Copilot Studio. La aptitud pasa por una serie de comprobaciones de validación. Un error de una de estas comprobaciones podría dar lugar a un mensaje de error como se describe en esta tabla.

Paso de validación	Código de error	Mensaje de error	Descripción o mitigación
La dirección URL del manifiesto es válida	URL_MALFORMED, URL_NOT_HTTPS	El vínculo no es válido; el vínculo debe empezar por https://	Vuelva a escribir el vínculo como una dirección URL segura.
El manifiesto es recuperable	MANIFEST_FETCH_FAILED	Hemos tenido problemas para obtener el manifiesto de aptitud.	Compruebe que la dirección URL del manifiesto es un vínculo al manifiesto; intente abrir la dirección URL del manifiesto en un explorador web. Si la URL muestra la página en 10 segundos, vuelva a registrar la capacidad.
El manifiesto es legible	MANIFEST_TOO_LARGE	El manifiesto es demasiado grande.	El manifiesto debe ser de 500 KB o menos.
El manifiesto es legible	MANIFEST_MALFORMED	El manifiesto es incompatible.	Compruebe si el manifiesto es un archivo JSON válido. Compruebe si el manifiesto contiene las propiedades necesarias, como name, msaAppId, etc. Consulte Restricciones del manifiesto para obtener más información.
La aptitud aún no está registrada	MANIFEST_ALREADY_IMPORTED	Ya se ha agregado esta capacidad al bot.	Elimine la aptitud y regístrela de nuevo.
Coincidencia de dominios de punto de conexión de manifiesto y de página principal	MANIFEST_ENDPOINT_ORIGIN_MISMATCH	Hay un error de coincidencia en los puntos de conexión de aptitudes.	El dominio de dirección URL de la página principal de la aplicación de Microsoft Entra ID y el dominio de dirección URL del manifiesto deben coincidir. Consultar el apartado Restricción del mismo inquilino
La aptitud se hospeda en el inquilino del usuario que ha iniciado sesión	APPID_NOT_IN_TENANT	Para agregar una aptitud, primero se debe registrar.	Un administrador debe registrar la aptitud en la organización del usuario que ha iniciado sesión.
Las acciones son limitadas	LIMITS_TOO_MANY_ACTIONS	La capacidad está limitada a 100 acciones.	Hay demasiadas acciones de capacidad definidas en el manifiesto de capacidad. Quite acciones y vuelva a intentarlo.
Los parámetros de entrada de acción son limitados	LIMITS_TOO_MANY_INPUTS	Las acciones están limitadas a 25 entradas.	Hay demasiados parámetros de entrada de acción de capacidad. Quite parámetros y vuelva a intentarlo.
Los parámetros de salida de acción son limitados	LIMITS_TOO_MANY_OUTPUTS	Las acciones están limitadas a 25 salidas.	Hay demasiados parámetros de salida de acción de capacidad. Quite el parámetro e inténtelo de nuevo.
El recuento de aptitudes es limitado	LIMITS_TOO_MANY_SKILLS	Su bot puede tener un máximo de 25 aptitudes.	Se han agregado demasiadas capacidades a un bot. Quite una capacidad existente y vuelva a intentarlo.
El token de seguridad es válido	AADERROR_OTHER	Parece que se produjo algún problema.	Puede haber un error transitorio para adquirir un token de seguridad para desencadenar la aptitud. Reintente la importación de la aptitud.
La aptitud es correcta	ENDPOINT_HEALTHCHECK_FAILED, HEALTH_PING_FAILED	Se ha producido un problema al comprobar la capacidad.	Copilot Studio recibió una respuesta desconocida al enviar una EndOfConversation actividad a su aptitud. Asegúrese de que su aptitud se ejecuta y responde correctamente.
La aptitud está autorizada	ENDPOINT_HEALTHCHECK_UNAUTHORIZED	Esta aptitud no ha permitido la lista del bot.	Compruebe si el bot está en la lista de permitidos de la aptitud. Para obtener más información, consulte Copilot Studio cómo configurar una aptitud.