Complementos de MCP y API para agentes declarativos

Los complementos MCP y API son acciones personalizadas que permiten a los agentes declarativos de Microsoft 365 Copilot interactuar con servidores de Protocolo de contexto de modelo (MCP) o API REST que tienen una descripción OpenAPI. Mediante el uso de uno de estos complementos, los usuarios pueden pedir a un agente declarativo que consulte un servidor MCP o una API REST para obtener información y, cuando sea compatible, crear, actualizar y eliminar datos y objetos a través de indicaciones de lenguaje natural.

En este artículo se utiliza un complemento para la acción técnica MCP o personalizada de API utilizada por un agente declarativo. Para obtener el producto, el paquete, el registro y el ciclo de vida de complementos orientados al cliente, consulte Complementos para Microsoft 365 Copilot.

Durante la compilación o la reutilización, use este artículo para elegir una acción MCP o API y comprender cómo la invoca el orquestador. Terminas con el modelo técnico de actuación y un procedimiento de producto para implementarlo. La acción resultante es una dependencia del agente, no una promesa de distribución pública separada.

Importante

Los complementos MCP y API proporcionan acciones dentro de los agentes declarativos. No son paquetes de complementos instalables independientes: solo el agente contenedor puede acceder a sus funciones y herramientas. Para obtener información sobre la relación de paquete y manifiesto de acción, consulte Complementos y acciones de agente declarativo.

Una API o un complemento de MCP usa un manifiesto de complemento que Copilot lee para obtener información sobre la API o el servidor MCP disponible para el agente. Copilot puede decidir entonces cuándo el agente debe usar esa integración para responder a una indicación. Para obtener más información sobre este manifiesto, consulte Esquema de manifiesto de complementos de API y MCP. El paquete instalable usa un manifiesto de aplicación de Microsoft 365 independiente.

Cómo detecta Copilot las herramientas del servidor MCP

Para los complementos basados en un servidor MCP, Copilot resuelve las herramientas del complemento dinámicamente en tiempo de ejecución de forma predeterminada, directamente desde el servidor MCP. El descubrimiento dinámico de herramientas significa que obtiene las herramientas más recientes que expone el servidor MCP sin esperar a que el agente se vuelva a empaquetar y 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.

Este valor predeterminado se aplica a los complementos de MCP utilizados como acciones de agente declarativo. Para un complemento que hace referencia a un servidor MCP remoto a través del agentConnectors manifiesto de la aplicación de Microsoft 365, la detección dinámica de herramientas requiere una versión del manifiesto de aplicación 1.29 o posterior y un host que lo permita. Para obtener más información, consulte Configuración de servidores MCP remotos para complementos de 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 las acciones del agente

Describa la integración de API o MCP, sus funciones o herramientas y sus entradas con precisión para que el orquestador pueda seleccionar la acción correcta para la solicitud del usuario. Estas descripciones se refieren a las acciones del agente, no al nombre o descripción de la tienda del paquete de complementos externo.

Integración de acciones Dónde describirlo Más información
Complemento de API Manifiesto de complemento y descripciones de parámetros y operaciones de OpenAPI Crear descripciones eficaces de OpenAPI
Complemento MCP Descripciones de la herramienta MCP y del manifiesto del complemento; Las definiciones de herramientas provienen del servidor en tiempo de ejecución o están ancladas en el manifiesto Detección dinámica de herramientas y herramientas ancladas

Las funciones y las herramientas MCP no son las mismas que los archivos de instrucciones reutilizables descritos en Habilidades como capacidades de complemento.

Crear un agente declarativo con acciones de API o MCP

Para el desarrollo profesional, comience con Work IQ Dev Tools. Elija primero un entorno documentado y agregue una herramienta de la lista siguiente cuando necesite sus capacidades de generación de proyectos o integración:

  • Work IQ Dev Tools es la herramienta recomendada. Se usa wiqd agent add action para agregar una acción OpenAPI o MCP remota compatible a un proyecto de agente declarativo.
  • Los tutoriales existentes basados en el kit de herramientas siguen estando disponibles para un servidor MCP, una descripción de OpenAPI o una nueva API de REST. Siga esos procedimientos al trabajar con un proyecto de Toolkit.
  • Kiota puede generar un manifiesto de complemento de API a partir de una descripción OpenAPI existente.

El manifiesto del complemento API o MCP configura la integración de acciones del agente. Empaquetar y distribuir el agente contenedor a través de su ruta app-package compatible; El manifiesto de acción no es un paquete de complementos que se pueda instalar de forma independiente.

Recomendación

Las herramientas de desarrollo de Work IQ están disponibles de forma general. wiqd agent add action Agrega una acción a un proyecto de agente declarativo y wiqd agent validate --mode source ejecuta comprobaciones fuera de línea en el origen del agente guardado. Una comprobación de origen superada no establece la accesibilidad del punto de conexión OpenAPI o del tiempo de ejecución, la exactitud de la autenticación o la aceptación del paquete final. Si omite --mode, la validación predeterminada es package, que carga una copia de un archivo zip existente y podría requerir inicio de sesión. Para conocer los modos de validación y la cobertura, consulte la referencia de comandos WIQD y Validation and MVL.

Limitaciones

Estos límites se refieren a los complementos API y MCP utilizados como acciones de agente declarativo, no al número de habilidades, agentes o conectores en un paquete de complementos instalable.

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.

Siguiente paso

Implemente la acción MCP o la acción de API seleccionadas. Una vez que los componentes funcionen individualmente, ingrese al paquete & prueba con Integrar y pruebe los componentes.