Compartir a través de

Complementos de API para Microsoft 365 Copilot

  • Artículo

Los complementos de API permiten que los agentes declarativos de Microsoft 365 Copilot interactúen con las API REST que tienen una descripción de OpenAPI. Con un complemento de API, los usuarios pueden pedir a un agente declarativo que no solo consulte una API REST para obtener información, sino que cree, actualice y elimine datos y objetos. Todo lo que la API REST puede hacer es accesible a través de mensajes de lenguaje natural.

Importante

Los complementos de API solo se admiten como acciones dentro de agentes declarativos. No se habilitan en Microsoft 365 Copilot.

Un complemento de API proporciona un documento de descripción de OpenAPI y un manifiesto de complemento que Copilot usa para aprender las funcionalidades de la API. Copilot puede decidir cuándo es adecuada la API de un complemento instalado y habilitado para responder a cualquier pregunta determinada. Para obtener más información sobre el archivo de manifiesto que requiere un complemento de API, consulte Esquema de manifiesto del complemento de API para Microsoft 365 Copilot.

Por ejemplo, considere una API de presupuestos que permita consultar y crear presupuestos, cobrar gastos o agregar fondos a los presupuestos existentes. El mensaje "Cuánto queda en el presupuesto de viaje de Contoso" podría desencadenar un complemento de presupuesto, realizando la siguiente llamada API.

GET /budgets?name=contoso%20travel

Copilot usa la respuesta de la llamada API para generar su respuesta: "El presupuesto de viajes de Contoso tiene actualmente $5,000 en fondos disponibles. Si necesita asignar fondos a categorías específicas o realizar un seguimiento de los gastos, también puedo ayudarle con eso. ¡Sólo avísame cómo puedo ayudar!"

El mensaje "Charge $500 to the Contoso travel budget for Megan's airline ticket" (Cobrar 500 USD al presupuesto de viaje de Contoso para el billete de avión de Megan) podría traducirse a la siguiente llamada API.

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot responde al usuario, utilizando la información devuelta: "El cargo de $500 por el billete de avión de Megan se ha procesado correctamente. El presupuesto de viaje de Contoso ahora tiene $4,500 restantes en fondos disponibles. Si necesita realizar más transacciones o necesita ayuda adicional con su presupuesto, hágamelo saber.

Funcionamiento de los complementos de API

Diagrama de secuencia que muestra cómo funciona un complemento de API

  1. El usuario pregunta al agente "¿Cuánto queda en el presupuesto de renovación del cuarto vestíbulo del café?"

  2. El agente identifica un complemento relacionado con el presupuesto de sus complementos disponibles que tiene una función GetBudget para obtener detalles del presupuesto. Asigna partes de la pregunta del usuario a los parámetros de la función: budgetName="".

  3. El agente pide al usuario que le permita enviar Fourth Coffee lobby renovation al complemento.

  4. El usuario decide permitir que los datos se compartan con el complemento una vez, o bien optar por permitir que los datos se compartan siempre para esta función.

  5. Si la API del complemento requiere autenticación, el complemento solicita un token o una clave de API del almacén de tokens.

  6. El almacén de tokens devuelve un token o una clave. Si es necesario, el almacén de tokens hace que el agente pida al usuario que inicie sesión.

  7. El agente envía una solicitud a la API del complemento, que se hospeda fuera de Microsoft 365.

    GET /budgets?budgetName=Fourth+Coffee+lobby+renovation

  8. La API devuelve una respuesta de API con el formato especificado en la especificación de OpenAPI.

    {
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}

  9. El agente genera una respuesta basada en la respuesta de la API.

  10. El agente envía la respuesta "Los fondos disponibles que quedan en el presupuesto de renovación del cuarto vestíbulo del café son $5000".

Confirmación de acciones

Copilot pregunta al usuario antes de enviar datos a un complemento de API.

Captura de pantalla de un cuadro de diálogo de confirmación del complemento.

De forma predeterminada, las API que solo recuperan datos proporcionan al usuario una opción "Permitir siempre", mientras que las API que modifican los datos no. Los desarrolladores de complementos pueden invalidar estos valores predeterminados. Para obtener más información, consulte Confirmación de los complementos de API para Microsoft 365 Copilot.

Personalización de la presentación de la respuesta

Copilot genera respuestas conversacionales mediante datos de respuestas de API. Los complementos pueden personalizar estas respuestas proporcionando plantillas de tarjeta adaptable para mostrar los datos de forma estructurada.

Captura de pantalla de una respuesta de tarjeta adaptable de un complemento de API

Generación de paquetes de complementos de API

Hay dos herramientas que los desarrolladores pueden usar para generar paquetes de complementos de API.

  • El kit de herramientas de Teams en Visual Studio o Visual Studio Code puede crear paquetes de complementos basados en una descripción de OpenAPI existente. Si no tiene una API existente, Teams Toolkit también tiene proyectos de inicio con una API de ejemplo y el paquete de complemento correspondiente.
  • Kiota es una herramienta de línea de comandos y una extensión de Visual Studio Code que puede generar paquetes de complementos basados en una descripción de OpenAPI existente.

Limitaciones

Las direcciones URL de las respuestas de API se describen

Para proteger la privacidad del usuario, Copilot redacta las direcciones URL contenidas en las respuestas de la API. La única excepción a este comportamiento es cualquier dirección URL de una propiedad especificada por la url propiedad en el objeto de propiedades semánticas Response.

Contenido relacionado