Complementos de API para Microsoft 365 Copilot

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 o servidores MCP. Con un complemento de API, los usuarios pueden pedir a un agente declarativo que no solo consulte una API REST o un servidor MCP para obtener información, sino que cree, actualice y elimine datos y objetos. Cualquier cosa que la API REST o el servidor MCP puedan hacer es accesible a través de mensajes de lenguaje natural.

Nota:

Además de llamar a las API REST o a los servidores MCP, hay una característica en versión preliminar que permite a un complemento llamar a las API en una biblioteca local. Le recomendamos que experimente con esta característica, pero no debe usarse en un complemento de producción. Para obtener más información, vea Build API plugins for Microsoft 365 Copilot with the Office JavaScript Library (Compilación de complementos de API para Microsoft 365 Copilot con la biblioteca de JavaScript de Office).

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 (cuando se usa una API REST) 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

El usuario pregunta al agente "¿Cuánto queda en el presupuesto de renovación del cuarto vestíbulo del café?"
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="".
El agente pide al usuario que le permita enviar Fourth Coffee lobby renovation al complemento.
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.
Si la API del complemento requiere autenticación, el complemento solicita un token o una clave de API del almacén de tokens.
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.
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
```
La API devuelve una respuesta de API en el formato especificado en la especificación de OpenAPI.
```
{
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}
```
El agente genera una respuesta basada en la respuesta de la API.
El agente envía la respuesta "Los fondos disponibles que quedan en el presupuesto de renovación del cuarto vestíbulo del café son $5,000".

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

Optimización del complemento para el orquestador de Copilot

Microsoft 365 Copilot puede elegir de forma única la aptitud adecuada entre las muchas aptitudes de su repertorio. Pero, ¿cómo puedes asegurarte de que Copilot elija tu complemento para proporcionar la aptitud adecuada?

La respuesta radica en cómo se describe el complemento, sus aptitudes y los parámetros para iniciar las aptitudes. Especifique descripciones concisas y precisas en el manifiesto del complemento para asegurarse de que el orquestador de Copilot sabe cuándo y cómo invocar el complemento.

La forma en que describa el complemento en el orquestador depende del tipo de complemento que compile, como se describe en la tabla siguiente.

Tipo de complemento	Descrito por	Más información
Complementos de API.	Descripción de OpenAPI	Cómo hacer que un documento de OpenAPI sea eficaz para ampliar Copilot
Acciones de Copilot Studio	Nombres y descripciones en Copilot Studio mapa de conversación	Orquestación de temas y acciones de copiloto con inteligencia artificial generativa
Complementos de extensiones de mensaje	Manifiesto de la aplicación	Directrices para complementos de extensión de mensajes

Generación de paquetes de complementos de API

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

Microsoft 365 Agents Toolkit 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, Agents 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

Complementos de agente declarativo

Cuando un agente declarativo incluye hasta cinco complementos definidos en el manifiesto del agente declarativo, los complementos siempre se insertan en el símbolo del sistema. Cuando se definen más de cinco complementos, el agente usa la coincidencia semántica. La coincidencia semántica se basa en la descripción del complemento, no en ninguna de las funciones individuales dentro del propio complemento.

Un complemento puede incluir un número ilimitado de funciones. Se devuelven todas las funciones, incluso si solo se coincide con una función. Sin embargo, debido a los límites de la ventana de tokens, la calidad de las respuestas podría degradarse si se incluyen más de 10 funciones.

La ventana de token para las entradas y salidas de un complemento trunca el contenido grande. El límite funcional está sujeto a cambios a medida que los modelos mejoran y dependen de la sobrecarga del sistema. Optimice las longitudes de token pequeñas o opte por opciones de extensibilidad que permitan transmitir contenido grande si es necesario.

Comentarios

¿Le resultó útil esta página?

Last updated on 2025-11-12