Extensión del agente con herramientas de una API REST (versión preliminar)

[Este artículo es documentación preliminar y está sujeto a cambios.]

Utiliza APIs REST (incluida la API OpenAI) para conectar un agente que crees con sistemas externos y acceder a los datos disponibles para su uso dentro de tu agente. Conecta a tu 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

Añade APIs REST a los agentes de Copilot y a los agentes personalizados a través de Copilot Studio.

Los agentes Copilot permiten a un creador combinar diversas fuentes de datos, como conectores, APIs, indicaciones y fuentes de conocimiento en un solo agente. Use este agente para ampliar experiencias de agente de marca Microsoft como Microsoft 365 Copilot.

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.

Prerequisites

• Credenciales de nivel Maker y una licencia de Copilot Studio.
• Una copia de la especificación OpenAPI para la API REST a la que quieres conectarte
• Conocimiento del tipo de autenticación necesario para conectarse a la API y los detalles de la autenticación.

Añade una herramienta de API REST a tu agente

Para agregar una herramienta de API REST al agente, complete los pasos siguientes:

1. Añade una nueva herramienta de agente y selecciona REST API
2. Proporcionar especificación, descripción y solución de la API
3. Proporcionar detalles de autenticación
4. Seleccionar herramientas de la API
5. Revisión y publicación

Las siguientes secciones te guían paso a paso por el proceso.

El proceso para agregar una API REST es el mismo para los agentes personalizados y los agentes de Microsoft 365 Copilot.

Añadir nueva herramienta de agente y seleccionar REST API

1. Ve a la página de Resumen de tu agente.

2. En la sección Herramientas , seleccione Agregar herramienta. También puede ir a la pestaña Herramientas y seleccionar Agregar una herramienta.

   Se muestra la página de la herramienta Añadir .

3. Seleccione Nueva herramienta>API REST.

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

1. Cargue un archivo de especificación de OpenAPI para la API de REST a la que desea conectarse. Puedes arrastrar y soltar el archivo de especificación en la pantalla de Subir una API REST o navegar por tu sistema para localizar el archivo que quieres usar.

   

   Note

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

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

   

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

2. Compruebe los detalles y, a continuación, seleccione Siguiente.

   Se te presenta una página de detalles del plugin de la API donde puedes proporcionar más información sobre la API.

   

   El campo de descripción se rellena inicialmente en función de la descripción de la especificación de API que cargó. Proporcione una descripción detallada, ya que la orquestación del agente usa la descripción para determinar cuándo usar la herramienta 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».

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

4. En Solución, una lista enumera todas las soluciones disponibles en el entorno actual. Seleccione la solución que desee usar. Obtenga más información sobre las soluciones en Conceptos de la solución.

   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 dejas la solución en blanco, el sistema creará una solución para ti con el nombre de la acción y el publicador predeterminado. Almacenar su acción en una solución le permite moverla fácilmente entre entornos.

   Note

   Si no ves la solución por defecto o la solución predeterminada como opción en este caso, añade una solución personalizada para facilitar la gestión. Obtenga más información en Solución predeterminada frente a solución personalizada.

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

Proporcionar detalles de autenticación

Aparece la página Autenticación . Seleccione el tipo de autenticación que se va a usar para la API.

1. Seleccione un método de autenticación en la lista. Hay tres opciones:

   • Ninguna: No se requiere autenticación para acceder a la API.
   • Clave API: Selecciona esta opción si tu API requiere una clave API para autenticación. En tiempo de ejecución, cuando el agente quiere usar la herramienta API, el agente pide al usuario que se autentique. El usuario proporciona una clave de API y el agente se conecta a la API usando esa clave.
   • Auth 2.0: Selecciona esta opción si tu servidor MCP usa OAuth 2.0 para autenticación. OAuth 2.0 permite a los usuarios individuales autenticarse en la API a través de un proveedor de identidad. Este método de autenticación permite al usuario conceder permisos a la aplicación (agente) sin compartir sus credenciales con el agente.

2. Introduce los campos requeridos para el método de autenticación seleccionado. Los campos varían según el método de autenticación.

   • Ninguna: No hay información que proporcionar.
   • Clave de API:
     • Etiqueta de parámetro: Una etiqueta de texto para que el parámetro de la API lo presente a los usuarios.
     • Nombre del parámetro: el nombre real del parámetro de clave de API que se va a usar en el encabezado o en la cadena de consulta.
     • Ubicación del parámetro: cómo se envía la clave para la API. Selecciona Encabezado o Consulta.
   • Auth 2.0:
     • ID de cliente: el identificador de cliente que emite el proveedor de identidades cuando registras tu aplicación. El identificador de cliente permite al proveedor de identidades saber qué aplicación está realizando la solicitud.
     • Secreto de cliente: secreto de cliente que emite el proveedor de identidades al registrar la aplicación. El agente envía el secreto de cliente junto con el identificador de cliente para demostrar que el agente está autorizado para solicitar tokens de acceso para el servidor MCP.
     • Dirección URL de autorización: el punto de conexión del proveedor de identidades donde el agente redirige al usuario para iniciar sesión y conceder permisos al agente (tarjeta de consentimiento presentada en el chat del agente). El usuario se autentica aquí y luego el proveedor de identidades responde al agente en la URL de devolución de llamada con un código de autorización.
     • URL del token: El punto final donde tu agente intercambia el código de autorización (o token de actualización) por un token de acceso y un token de actualización. El token de acceso permite al agente usar el servidor MCP en nombre del usuario. Los tokens de actualización permiten que el agente obtenga nuevos tokens de acceso y actualización desde el punto de conexión de actualización cuando expire el token de acceso anterior.
     • Url de actualización: punto de conexión para solicitar un nuevo token de acceso mediante un token de actualización (de modo que el usuario no tenga que iniciar sesión de nuevo cuando expire el token).
     • Alcance: (Opcional): Los permisos que solicita tu aplicación, como una lista separada por espacio.
     • Qué organización de Microsoft 365 accede a los puntos de conexión: esta configuración limita el acceso al origen a la organización del creador o a todas las organizaciones. Seleccione cualquiera de las siguientes opciones:
       • Solo en mi organización
       • Cualquier organización de Microsoft 365
     • ¿Qué aplicación (cliente) puede usar los endpoints: GUID que define el sistema cliente que puede usarse para acceder a estos datos. Las aplicaciones podrían incluir Microsoft 365, Power Automate y otras opciones.

3. Cuando complete todos los campos, seleccione Siguiente.

   Aparece la página Seleccionar y configurar la herramienta , donde puede seleccionar herramientas para habilitar desde la API.

   

Seleccionar herramientas de la API

Selecciona las herramientas compatibles con API desde la API REST para añadirlas a tu agente. Generalmente, una API REST ofrece una variedad de herramientas a través de las diversas combinaciones de métodos endpoint y 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, tu especificación de API podría incluir la posibilidad de actualizar y eliminar, pero solo quieres que los usuarios de tu agente puedan crear registros.

1. Seleccione una herramienta de la lista para configurar.

   La página de Configurar tu herramienta se muestra.

   

2. Configura el nombre y la descripción de la herramienta seleccionada. De forma similar a la API general, proporcione un nombre de herramienta y una descripción de la herramienta. Inicialmente, las descripciones se rellenan previamente a partir de las descripciones de la especificación de la API. El nombre no necesita ser único, pero debe representar la propia herramienta. 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 si tu consulta se alinea con esta herramienta concreta.

3. Una vez completados los campos, seleccione Siguiente.

   Se muestra la página Revisar los parámetros de tu herramienta.

   

   Esta página muestra los valores esperados para la entrada y los valores de salida que se devuelven. No puede cambiar estos valores, pero puede actualizar las descripciones de las entradas y salidas. Todo el contenido de esta página se extrae directamente de la especificación de la API cargada.

4. Si es necesario, actualiza las descripciones. Las descripciones proporcionan una definición de para qué se utilizan los valores. Si alguna de las descripciones está en blanco, debe completarlas para poder avanzar. Pega el nombre si no tienes una mejor descripción.

5. Después de completar las descripciones, selecciona Siguiente.

   La primera herramienta ahora está configurada y aparece en la lista de Herramientas seleccionadas en la página Seleccionar y configurar la herramienta de complemento .

   

6. Agregue cualquier otra herramienta de la API que quiera incluir en este momento. Cuando haya terminado de agregar herramientas que quiera que admita el agente, seleccione Siguiente.

   Se muestra la página de Revisar tu herramienta . La página proporciona los detalles de la herramienta de API REST configurada.

   

Revisión y publicación

1. Si necesita realizar actualizaciones, seleccione Atrás y realice los cambios. De lo contrario, seleccione Siguiente.

   Aparece una pantalla que indica que la herramienta se está publicando mientras el proceso está en curso. Se le informará una vez que se complete la publicación.

2. Selecciona Crear conexión para continuar. Vuelves a la pantalla de Añadir herramienta.

3. Selecciona la API REST en el selector de tipos de herramienta. Puedes ver las herramientas recién creadas desde tu API. Debería haber una entrada por cada herramienta que hayas añadido desde la API.

4. Para cada una de las herramientas recién configuradas desde la API, cree o seleccione una conexión a la API y agregue la herramienta al agente:

   1. En la pantalla de Añadir herramienta , selecciona la herramienta.
   2. En Conexión, selecciona una conexión existente o selecciona Crear nueva conexión.
   3. Escriba cualquier información necesaria para la conexión y, a continuación, seleccione Crear para crear la conexión a la herramienta.
   4. Selecciona Añadir y configurar para añadir la herramienta a tu agente.

   

Las herramientas de la API REST ya están disponibles para su uso en su agente.