Ampliar un agente con acciones de la API de REST (versión preliminar)

Puede usar las API de REST (incluida la API de OpenAI) para conectar un agente que cree con sistemas externos y acceder a los datos disponibles para usarlos dentro de su agente. Puede conectar su agente a una API REST proporcionando a Copilot Studio tres cosas:

• Una especificación OpenAPI que define las funciones de la API y las acciones disponibles
• Detalles sobre el tipo de autenticación necesaria y los detalles de autenticación para que los usuarios se conecten a la API para acceder al sistema externo
• Descripciones para ayudar al modelo de lenguaje a determinar cuándo invocar la API para utilizar los datos

Las API de REST se pueden agregar a agentes de Copilot y agentes personalizados a través de Copilot Studio.

Los agentes de Copilot permiten a un creador combinar múltiples fuentes de datos como conectores, API, solicitudes y fuentes de conocimiento en un solo agente. Puede usar este agente para ampliar experiencias de copiloto de la marca Microsoft como Copilot para Microsoft 365.

Los agentes personalizados son agentes independientes que contienen conectores, API, indicaciones y orígenes de conocimiento. Puede utilizar agentes personalizados directamente integrándolos en sitios web u otros canales.

Oharra

Las acciones de API deben crearse a partir de una especificación OpenAPI v2. Esto se debe a las capacidades de Power Platform en el procesamiento de las especificaciones de la API. Si se envía una especificación v3, se convierte automáticamente en una especificación v2 durante el proceso de creación.

Requisitos previos

Se necesitan algunos requisitos previos para ampliar las experiencias copiloto de la marca Microsoft con acciones de conector.

Para todos los tipos de experiencia copiloto, debe tener credenciales de nivel de creador y una licencia de Copilot Studio.

También necesita una copia de la especificación de OpenAPI, conocimiento del tipo de autenticación necesaria y los detalles de autenticación.

Agregar una acción de API de REST a un agente

Agregar una API REST a su agente implica algunos pasos. Las siguientes secciones el guían por el proceso.

El proceso para agregar una API de REST es idéntico para los agentes de Copilot y personalizados.

Hay varios pasos en el proceso.

Agregar una acción al agente

1. Comience en la página de descripción general de su agente.

   

2. En la sección Acciones, seleccione Agregar acción. También puede ir a la pestaña Acciones y seleccionar Agregar acción.

   

   El asistente para la creación de acciones se inicia con la página Elegir una acción mostrada.

Proporcionar la especificación, la descripción y la solución de la API

1. En la parte inferior de la página, seleccione Agregar una API para un conector personalizado.

   

2. Cargue un archivo de especificación de OpenAPI para la API de REST a la que desea conectarse. Puede arrastrar y soltar el archivo de especificación en la pantalla Cargar una API de REST o examinar el sistema para localizar el archivo que desea utilizar.

   

   Oharra

   La especificación de OpenAPI debe ser un archivo JSON en formato v2. Si se envía una especificación v3, se convierte automáticamente en una especificación v2 durante el proceso de creación.

   Después de cargar la especificación, la pantalla se actualiza para indicar el nombre del archivo de especificación y los detalles.

   

   En los pasos que siguen, basamos el procedimiento en un ejemplo específico de SunnyADO, un sistema de gestión de tickets de ADO. En el ejemplo, la intención es permitir que los usuarios recuperen y actualicen sus tickets a través del agente.

3. Verifique los detalles y después seleccione Siguiente.

   Se le presenta una página de detalles del complemento de API donde puede proporcionar información adicional sobre la API.

   

   El campo de descripción se rellena inicialmente en función de la descripción de la especificación de la API que cargó. Proporcione una descripción detallada, ya que la orquestación de agente usa la descripción para determinar cuándo usar la acción concreta. Proporcione detalles, incluidos sinónimos, para ayudar a su agente con el proceso de selección.

   Por ejemplo, la descripción inicial proporcionada es: «Un servicio simple para administrar tickets».

   Una mejor descripción es: «Un sistema utilizado para obtener, recuperar, encontrar y mostrar tickets existentes de SunnyADO. Permite a los usuarios actualizar, cambiar y administrar tickets para proporcionar más datos para mejorar los registros».

4. Escriba una descripción mejorada en el campo Descripción.

5. En Solución, una lista enumera todas las soluciones disponibles en el entorno actual. Seleccione la solución que desee usar. Para obtener más información sobre qué son las soluciones, consulte Conceptos de soluciones.

   

   Si tiene una solución preferida o el conector seleccionado ya está en la solución, esa solución se selecciona automáticamente.

   Puede seleccionar una solución o dejarla en blanco. Si deja la solución en blanco, se crea una solución con el nombre de la acción y el editor predeterminado. Almacenar su acción en una solución le permite moverla fácilmente entre entornos.

   Oharra

   Si no ve la solución predeterminada o la solución predeterminada de CDS como una opción en este caso, le recomendamos tener una solución personalizada para facilitar la administración. Para obtener más información, consulte : Solución predeterminada frente a solución personalizada.

6. Con una solución seleccionada, seleccione Siguiente para continuar.

Proporcionar detalles de autenticación

Se muestra la página Autenticación para seleccionar qué tipo de autenticación usar para la API.

Oharra

Actualmente las opciones disponibles son Ninguna, Auth 2.0 y API. Habrá más métodos disponibles en una fecha posterior.

1. Seleccione un método de autenticación en la lista.

2. Rellene los campos obligatorios para el método de autenticación. Los campos varían según el método de autenticación.

   • Ninguno: no hay otros campos obligatorios.
   • Clave de API:
     • Etiqueta de parámetro: una etiqueta de texto para el parámetro de API.
     • Nombre del parámetro: un nombre de texto para el parámetro de la API.
     • Ubicación del parámetro: dónde se puede encontrar el parámetro.
   • Auth 2.0:
     • Id. de cliente: GUID de cliente para el servicio de destino.
     • Secreto de cliente: valor secreto para el cliente. El secreto no se muestra cuando el usuario abre el panel de edición después. Sin embargo, guarde el secreto, porque lo necesitará si decide realizar más ediciones.
     • URL de autorización: URL utilizada para autorizar el sistema de origen.
     • URL del token: URL donde se puede recuperar el token.
     • URL de actualización: la URL a la que se le redirige en un escenario de actualización.
     • Ámbito: la dirección URL de ámbito asignada a la API para aplicaciones Microsoft Entra.
     • Qué organización de Microsoft 365 accede a los puntos de conexión: esto limita el acceso al origen a la organización del creador o a todas las organizaciones.
     • Qué aplicación (cliente) puede usar los puntos de conexión: GUID que define el sistema de cliente que se puede usar para acceder a estos datos. Las aplicaciones pueden incluir Microsoft 365, Power Automate y otras opciones.

3. Una vez completados todos los campos, seleccione Siguiente.

   Se le presenta una página Seleccionar y configure su acción de complemento donde puede seleccionar acciones para habilitar para la API.

   

Seleccionar acciones para la API

Elija las acciones admitidas por API que desea habilitar. Por lo general, una API REST ofrece una serie de acciones a través de las distintas combinaciones de punto final y método HTTP (get, put, post, delete, etc.) definidas en la especificación de la API. En algunos casos, es posible que no desee que los usuarios de agente tengan la capacidad de ejecutar todas las acciones que la API ofrece generalmente. Por ejemplo, la especificación de su API puede incluir acciones para actualizar y eliminar, pero solo desea que los usuarios de su agente puedan crear registros.

1. Seleccione una acción en la lista para configurar.

   Se muestra la página Configurar su acción de complemento.

   

2. Configurar la acción seleccionada. Al igual que con la API general, se le pide que proporcione un nombre de la acción y una descripción de la acción. Inicialmente, las descripciones se rellenan previamente a partir de las descripciones de la especificación de la API. No es necesario que el nombre sea único, pero debe representar la acción en sí. La descripción, al igual que la descripción general de la API, debe ser lo suficientemente específica como para proporcionar al modelo de lenguaje detalles que permitan identificar mejor que la consulta se alinea con esta acción específica.

3. Una vez completados los campos, seleccione Siguiente.

   Se muestra la página Revisar los parámetros de su acción.

   

   El contenido de esta página muestra los valores proporcionados como parte de los posibles valores de entrada y salida. Estos valores no se pueden cambiar, sin embargo, las descripciones de las entradas y salidas sí se pueden actualizar. Todo el contenido de esta página se extrae directamente de la especificación de la API cargada.

4. Rellene los valores según sea necesario para las descripciones. Las descripciones proporcionan una definición de para qué se utilizan los valores. Si alguna de las descripciones está en blanco, debe completarse antes de poder avanzar. Puede pegar el nombre si no tiene una descripción mejor.

5. Después de completar la descripción, seleccione Siguiente.

   La primera acción ya está configurada y aparece en la lista de Acciones seleccionadas en la página Seleccionar y configurar su acción de complemento.

   

6. Agregue cualquier otra acción que desee incluir en este momento. Una vez que haya terminado de agregar las acciones que desea que admita su agente, seleccione Siguiente.

   Aparece la página Revisar la acción. La página proporciona los detalles de la acción de la API de REST configurada.

   

Revisar y publicar

1. Si necesita realizar alguna actualización, puede seleccionar Atrás y realizar los cambios. Si no quiere, seleccione Siguiente.

   Se presenta una pantalla que indica que su acción se está publicando mientras se completa el proceso. Se le informará una vez que se complete la publicación.

2. Una vez finalizada la publicación, volverá a la pantalla Elegir una acción. Aquí puede agregar la API de REST recién configurada a su agente de Copilot o agente personalizado y completar la configuración del componente.

   

La acción de la API de REST ya está disponible para su uso en su agente.

Argibidea

Para encontrar más fácilmente su acción, use la barra de búsqueda para localizarla.