Complementos para Microsoft 365 Copilot

Los complementos permiten a los agentes declarativos de Microsoft 365 Copilot interactuar con servidores de Protocolo de contexto de modelo (MCP) o API de REST que tienen una descripción de OpenAPI. Mediante el uso de un complemento, los usuarios pueden pedir a un agente declarativo no solo que consulte un servidor MCP o una API REST para obtener información, sino también que cree, actualice y elimine datos y objetos. Todo lo que el servidor MCP o la API de REST pueden hacer es accesible a través de indicaciones en lenguaje natural.

Importante

Los complementos solo se admiten como acciones dentro de los agentes declarativos. No están habilitadas en Microsoft 365 Copilot.

Un complemento proporciona un manifiesto de complemento que Copilot usa para conocer las capacidades del servidor MCP o la API del complemento. Copilot puede decidir entonces cuándo un complemento instalado y habilitado es adecuado para responder a cualquier indicación. Para obtener más información sobre el archivo de manifiesto que requiere un complemento, consulte Esquema de manifiesto de complemento para Microsoft 365 Copilot.

Cómo detecta Copilot las herramientas del servidor MCP

Para complementos basados en un servidor MCP, Copilot resuelve las herramientas del servidor dinámicamente en tiempo de ejecución de forma predeterminada, directamente desde el servidor MCP. El descubrimiento dinámico de herramientas significa que los usuarios obtienen las herramientas más recientes que expone el servidor MCP sin esperar a que el agente se vuelva a empaquetar y volver a publicar. Al crear el agente, un desarrollador puede anclar un conjunto fijo de herramientas en el manifiesto del plugin en su lugar. Los complementos de la API de REST siempre usan las herramientas definidas en el manifiesto del complemento. Para obtener más información, consulte Compilar complementos desde un servidor MCP para Microsoft 365 Copilot y Detección de herramientas dinámicas para complementos de MCP en Microsoft 365 Copilot.

Ejemplo de complemento

Considere un servidor MCP 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 activar un complemento de presupuesto, invocando la get-budgets herramienta.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "get-budgets",
    "arguments": {
      "budgetName": "contoso travel"
    }
  }
}

Copilot usa la respuesta del resultado de la herramienta para generar su respuesta: "El presupuesto de viajes de Contoso tiene actualmente 5000 dólares en fondos disponibles. Si necesita asignar fondos a categorías específicas o realizar un seguimiento de los gastos, también puedo ayudarlo con eso. ¡Solo dime cómo puedo ayudar!"

El mensaje "Cargo 500 USD al presupuesto de viaje de Contoso para el billete de avión de Megan" podría traducirse a la siguiente llamada a la herramienta MCP.

POST /mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "charge-budget",
    "arguments": {
      "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 boleto de avión de Megan se procesó con éxito. El presupuesto de viajes de Contoso ahora tiene 4 500 $ restantes en fondos disponibles. Si necesita realizar más transacciones o necesita más ayuda con su presupuesto, ¡hágamelo saber!"

Cómo funcionan los complementos

Diagrama de secuencia que muestra el flujo de datos del complemento

  1. El usuario le pregunta al agente: "¿Cuánto queda en el presupuesto de renovación del vestíbulo de Fourth Coffee?"

  2. En el caso de un complemento de MCP que usa la detección dinámica de herramientas, el agente obtiene las definiciones de herramientas actuales del servidor de MCP del complemento en tiempo de ejecución y valida las herramientas nuevas o modificadas antes de usarlas. Para un complemento con un conjunto de herramientas ancladas, o para un complemento de API REST, el agente usa las herramientas definidas en el manifiesto del complemento en su lugar.

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

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

  5. El usuario elige permitir que los datos se compartan con el complemento una vez, o elige permitir que siempre se compartan datos para esta función.

  6. Si el servidor MCP o la API del complemento requieren autenticación, el complemento solicita un token o una clave API del almacén de tokens.

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

  8. El agente envía una solicitud al servidor MCP o API del complemento, que se hospeda fuera de Microsoft 365.

  9. El servidor o la API del MCP devuelve una respuesta.

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

  10. El agente genera una respuesta basada en la respuesta del servidor MCP o de la API.

  11. El agente envía la respuesta: "Los fondos disponibles que quedan en el presupuesto de renovación del vestíbulo de Fourth Coffee son de $5,000".

Acciones de confirmación

Copilot pregunta al usuario antes de enviar cualquier dato por primera vez a un complemento.

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

Después de que el usuario confirme la conexión, las herramientas y API del servidor MCP que solo recuperan datos no requieren confirmación, mientras que las herramientas y API que modifican datos sí. Los desarrolladores de complementos pueden invalidar estos valores predeterminados. Para obtener más información, consulte Indicaciones de confirmación de complementos de MCP y API para Microsoft 365 Copilot.

Personalizar la presentación de respuesta

Copilot genera respuestas conversacionales mediante datos del servidor MCP o respuestas de API. Los complementos pueden personalizar cómo se presentan estos datos y el mecanismo depende del tipo de complemento.

  • Los complementos de MCP pueden ofrecer respuestas enriquecidas e interactivas mediante el uso de aplicaciones MCP : widgets de interfaz de usuario que el servidor MCP devuelve junto con el resultado de la herramienta en tiempo de ejecución. Dado que el widget se entrega con la respuesta de la herramienta en lugar de estar definida en el manifiesto, las aplicaciones de MCP funcionan tanto si el complemento utiliza un conjunto anclado de herramientas como si la detección dinámica de herramientas.

  • Los complementos de API pueden proporcionar plantillas de tarjeta adaptativa en el manifiesto del complemento para mostrar datos de forma estructurada. Dado que las plantillas se definen con respecto a las operaciones declaradas en el manifiesto, este enfoque se aplica a los complementos de API y MCP que usan un conjunto anclado de herramientas.

Para las citas vinculadas a fuentes en cualquier tipo de complemento, Copilot usa la semántica de respuesta y puede inferir metadatos de citas automáticamente a partir de la respuesta de la herramienta o API. La inferencia automática es especialmente útil para los complementos de MCP que utilizan la detección dinámica de herramientas, donde las herramientas se resuelven en tiempo de ejecución y no hay ninguna definición de herramienta de manifiesto para configurar. Para obtener más información, vea Mostrar citas con semántica de respuesta.

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

Gestión de direcciones URL en respuestas de acción

La experiencia de chat de Microsoft 365 Copilot puede representar las direcciones URL devueltas como parte de las respuestas de acción, ya sea de complementos de MCP, complementos de API, conectores o flujos, como vínculos en los que se puede hacer clic. El tiempo de ejecución de Copilot controla este comportamiento y no lo evalúa con respecto a ningún dominio que declare el complemento (como la servers sección de la descripción de OpenAPI de un complemento de API).

Las reglas de seguridad, confianza y directivas de la plataforma rigen el comportamiento de representación de direcciones URL para las respuestas de acción y puede cambiar con el tiempo. No confíe en direcciones URL en las que se pueda hacer clic en las respuestas de acción en escenarios críticos para producción.

Ayudar al orquestador de Copilot a elegir el complemento

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

La respuesta está en cómo describe su complemento, sus habilidades y los parámetros para el inicio de las habilidades. Especifica descripciones concisas y precisas en el manifiesto del plugin para garantizar mejor que Copilot Orchestrator sepa cuándo y cómo invocar el complemento.

La forma de describir el complemento al 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 OpenAPI sea eficaz en la ampliación de Copilot
Acciones de Copilot Studio Nombres y descripciones en el mapa de conversaciones de Copilot Studio Organizar temas y acciones de Copilot con IA generativa
Complementos de extensiones de mensaje Manifiesto de la aplicación Directrices para complementos de extensión de mensaje

Crear un complemento de agente declarativo

Los desarrolladores pueden usar dos herramientas para generar paquetes de complementos de API:

  • El kit de herramientas de agentes de Microsoft 365 en Visual Studio o Visual Studio Code crea paquetes de complementos basados en un servidor MCP existente o una descripción de OpenAPI. Agents Toolkit también tiene proyectos iniciales con una API de ejemplo y el paquete de complementos correspondiente.
  • Kiota es una herramienta de línea de comandos y una extensión de Visual Studio Code que genera paquetes de complementos basados en una descripción OpenAPI existente.

Sugerencia

Herramientas de desarrollo de Work IQ (versión preliminar): también puede adjuntar y comprobar acciones desde la línea de comandos. wiqd agent add action agrega una acción a un agente declarativo y wiqd agent validate --mode deep confirma que la descripción de OpenAPI de una acción es accesible y está bien formada y que un manifiesto de complemento al que se hace referencia declara el esquema de autenticación correcto. También existe un árbol de comandos alfa wiqd plugin , pero su interfaz está sujeta a cambios. Para obtener más información, consulte la documentación de Dev Tools de Work IQ.

Limitaciones

Cuando un agente declarativo incluye hasta cinco complementos definidos en el manifiesto del agente declarativo, el agente siempre inserta los complementos en el mensaje. Cuando el agente incluye más de cinco complementos, utiliza la coincidencia semántica. La coincidencia semántica se basa en la descripción del complemento, no en ninguna de las funciones o herramientas individuales dentro del complemento en sí.

Un complemento puede incluir un número ilimitado de funciones o herramientas MCP. Se devuelven todas las funciones o herramientas de un complemento coincidente, incluso si solo una coincide. Para un complemento de MCP que utiliza la detección dinámica de herramientas, las herramientas resueltas desde el servidor de MCP en tiempo de ejecución cuentan para este total. 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 o herramientas.

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

Contenido relacionado

  • Last updated on