Adición de widgets de interfaz de usuario interactivos a agentes declarativos

Puede agregar widgets de interfaz de usuario interactivos a los agentes declarativos agregando una acción basada en servidor del Protocolo de contexto de modelo (MCP) al agente y ampliando las herramientas de MCP que usa el agente para incluir la interfaz de usuario. Microsoft 365 Copilot admite widgets de interfaz de usuario creados con los métodos siguientes.

Aplicaciones MCP : una extensión a MCP que permite a los servidores MCP entregar interfaces de usuario interactivas a los hosts.
SDK de OpenAI Apps : herramientas para crear aplicaciones chatGPT basadas en el estándar mcp apps con funcionalidad adicional de ChatGPT.

Por ejemplo, complementos de servidor MCP, consulte ejemplos de interfaz de usuario interactiva basada en MCP para Microsoft 365 Copilot en GitHub.

Para obtener más información sobre qué funcionalidades de MCP Apps o OpenAI Apps SDK son compatibles, consulte Funcionalidades admitidas.

Requisitos previos

Requisitos especificados en Requisitos para las opciones de extensibilidad de Copilot
Un servidor MCP remoto que proporciona widgets de interfaz de usuario o que puede modificar para implementar widgets de interfaz de usuario
Una herramienta para ver las respuestas del servidor MCP, como mcp inspector
Visual Studio Code
Microsoft 365 Agents Toolkit (versión 6.6.1 o posterior)

Requisitos del servidor MCP

Autenticación: se admiten OAuth 2.1 y Microsoft Entra inicio de sesión único (SSO). La autenticación anónima se admite con fines de desarrollo. Para obtener más información sobre la autenticación, consulte Configuración de la autenticación para complementos de API en agentes.
Direcciones URL permitidas : el servidor MCP y el proveedor de identidades deben permitir las siguientes direcciones URL.
- Dirección URL del host de widget para CORS: Copilot representa la interfaz de usuario del widget en un host específico del servidor MCP con la siguiente dirección URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, donde {hashed-mcp-domain} es el hash SHA-256 del dominio del servidor MCP. Puede usar el generador de direcciones URL del host de widget para generar la dirección URL del host en función de la dirección URL del servidor MCP.
- URI de redireccionamiento de OAuth 2.1:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect para Copilot
  - https://vscode.dev/redirectpara Visual Studio Code para capturar herramientas mediante el kit de herramientas de agentes
- Microsoft Entra URI de redireccionamiento de SSO:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect para Copilot
  - Visual Studio Code no admite actualmente el inicio de sesión único para capturar herramientas
Widgets de interfaz de usuario : los widgets de la interfaz de usuario se deben implementar de acuerdo con los requisitos del SDK de aplicaciones de MCP o OpenAI Apps.

Procedimientos recomendados

Diseño de la experiencia del usuario

Para obtener más información sobre los procedimientos recomendados de diseño de experiencia de usuario, consulte Instrucciones de experiencia del usuario para widgets interactivos de interfaz de usuario en agentes declarativos.

Comprobación de la disponibilidad de la API

No todas las window.openai.* API están disponibles en todas las plataformas o hosts. Las API que no son compatibles son undefined. Compruebe siempre la disponibilidad de la API y proporcione una reserva si la API no está disponible.

Ejemplos

Este patrón simple evita errores en tiempo de ejecución comprobando antes de llamar a la API.

if (window.openai.callTool) {
  const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
  // Handle unsupported case — show fallback UI, skip the feature, etc.
}

En este ejemplo, solo se representa un botón para entrar en modo de pantalla completa si el host admite la requestDisplayMode API.

function FullScreenButton() {
  // Don't render the button if the host doesn't support it
  if (!window.openai.requestDisplayMode) {
    return null;
  }

  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
      Enter Fullscreen
    </button>
  );
}

Como alternativa, el widget puede comprobar la disponibilidad de todas las API que usa en el inicio y habilitar o deshabilitar las características en consecuencia.

interface PlatformCapabilities {
  canCallTools: boolean;
  canChangeDisplayMode: boolean;
  canSendMessages: boolean;
}

function detectCapabilities(): PlatformCapabilities {
  return {
    canCallTools: !!window.openai.callTool,
    canChangeDisplayMode: !!window.openai.requestDisplayMode,
    canSendMessages: !!window.openai.sendMessage,
  };
}

// Use at widget startup
const capabilities = detectCapabilities();

if (!capabilities.canCallTools) {
  // Show a reduced-functionality experience
}

Creación de un agente declarativo

Abra Visual Studio Code y seleccione el icono Microsoft 365 Agents Toolkit (Kit de herramientas de agentes de Microsoft 365) en la barra de actividad de la izquierda.
Seleccione Crear un nuevo agente o aplicación en el panel de tareas Kit de herramientas de agentes.
Seleccione Agente declarativo.
Seleccione Agregar una acción y, a continuación, seleccione Iniciar con un servidor MCP. Si se le solicita, elija Servidor MCP remoto.
Escriba la dirección URL al servidor MCP.
Elija una ubicación para el proyecto del agente.
Escriba un nombre para el agente.

Cuando complete estos pasos, Agents Toolkit genera los archivos necesarios para el agente y abre una nueva ventana Visual Studio Code con el proyecto del agente cargado.

Actualización y transferencia local del agente

Abra el archivo .vscode/mcp.json . Seleccione el botón Iniciar en el editor de archivos.
Seleccione el botón ATK: Capturar acción de MCP en el editor de archivos y, a continuación, seleccione ai-plugin.json.
Seleccione las herramientas para que el agente use y seleccione Aceptar. Asegúrese de seleccionar al menos una herramienta que tenga un widget de interfaz de usuario.
Seleccione el tipo de autenticación aplicable.

Importante

Si el servidor MCP está en desarrollo y no implementa la autenticación, se omite este paso. Debe agregar manualmente la autenticación al manifiesto una vez que agregue la autenticación al servidor.
Seleccione el icono microsoft 365 Agents Toolkit en la barra de actividad de la izquierda.
En el panel Cuentas , seleccione Iniciar sesión en Microsoft 365. (Si ya ha iniciado sesión, continúe con el paso siguiente).
Confirme que tanto la carga de aplicaciones personalizadas habilitada comoel acceso de Copilot habilitado se muestran en su cuenta de Microsoft 365. Si no lo hacen, consulte con el administrador de la organización. Consulte Requisitos para las opciones de extensibilidad de Copilot para obtener más información.
En el panel Ciclo de vida , seleccione Aprovisionar.
Si se le solicita, agregue los detalles de autenticación.
Espere a que el kit de herramientas informe de que finaliza el aprovisionamiento.

Prueba del agente

Abra el explorador y vaya a https://m365.cloud.microsoft/chat.
Seleccione el agente en la barra lateral izquierda. Si no ve el agente, seleccione Todos los agentes.
Pida al agente que haga algo que invoque el servidor MCP.
Permitir que el agente se conecte al servidor MCP cuando se le solicite.
El agente representa el widget de interfaz de usuario.

Funciones admitidas

Microsoft 365 Copilot admite las siguientes funcionalidades.

Puente de componentes

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`window.openai.toolInput`	`app.ontoolinput`	✅
`window.openai.toolOutput`	`app.ontoolresult`	✅
`window.openai.toolResponseMetadata`	`app.ontoolresult` → `params._meta`	✅
`window.openai.widgetState`	—	✅
`window.openai.setWidgetState(state)`	No disponible directamente. Uso de mecanismos alternativos, incluidos `app.updateModelContext()`	✅
`window.openai.callTool(name, args)`	`app.callServerTool({ name, arguments })`	✅
`window.openai.sendFollowUpMessage({ prompt })`	`app.sendMessage({ ... })`	✅
`window.openai.uploadFile(file)`	—	❌
`window.openai.getFileDownloadUrl({ fileId })`	—	❌
`window.openai.requestDisplayMode(...)`	`app.requestDisplayMode({ mode })`	✅ (solo pantalla completa)
`window.openai.requestModal(...)`	—	❌
`window.openai.notifyIntrinsicHeight(...)`	`app.sendSizeChanged({ width, height })`	✅
`window.openai.openExternal({ href })`	`app.openLink({ url })`	✅
`window.openai.setOpenInAppUrl({ href })`	—	✅
`window.openai.theme`	`app.getHostContext()?.theme`	✅
`window.openai.displayMode`	`app.getHostContext()?.displayMode`	✅
`window.openai.maxHeight`	`app.getHostContext()?.viewport?.maxHeight`	✅
`window.openai.safeArea`	`app.getHostContext()?.safeAreaInsets`	✅
`window.openai.view`	—	✅
`window.openai.userAgent`	`app.getHostContext()?.userAgent`	✅
`window.openai.locale`	`app.getHostContext()?.locale`	✅
—	`app.ontoolinputpartial`	❌
—	`app.ontoolcancelled`	❌
—	`app.getHostContext()?.availableDisplayModes`	❌
—	`app.getHostContext()?.toolInfo`	❌
—	`app.onhostcontextchanged`	❌
—	`app.onteardown`	❌
—	`app.sendLog({ level, data })`	❌
—	`app.getHostVersion()`	❌
—	`app.getHostCapabilities()`	✅

Campos de _meta del descriptor de herramientas

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`_meta["openai/outputTemplate"]`	`_meta.ui.resourceUri`	✅
`_meta["openai/widgetAccessible"]`	`_meta.ui.visibility` (string[])	❌
`_meta["openai/visibility"]`	`_meta.ui.visibility` (string[])	✅
`_meta["openai/toolInvocation/invoking"]`	—	❌
`_meta["openai/toolInvocation/invoked"]`	—	❌
`_meta["openai/fileParams"]`	—	❌
`_meta["securitySchemes"]`	—	❌

Anotaciones de descriptor de herramientas

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`readOnlyHint`	`readOnlyHint`	✅
`destructiveHint`	`destructiveHint`	❌
`openWorldHint`	`openWorldHint`	❌
`idempotentHint`	`idempotentHint`	❌

Campos de _meta de recursos de componente

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`_meta["openai/widgetDescription"]`	—	❌
`_meta["openai/widgetPrefersBorder"]`	`_meta.ui.prefersBorder`	❌
`_meta["openai/widgetCSP"]`	`_meta.ui.csp`	✅
`_meta["openai/widgetDomain"]`	`_meta.ui.domain`	❌
—	`_meta.ui.permissions`	❌

Propiedades del objeto CSP

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`connect_domains`	`connectDomains`	✅
`resource_domains`	`resourceDomains`	✅
`frame_domains`	`frameDomains`	❌
`redirect_domains`	—	❌
—	`baseUriDomains`	❌

Resultados de la herramienta proporcionados por el host _meta campos

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`_meta["openai/widgetSessionId"]`	—	❌

Campos de _meta proporcionados por el cliente

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
`_meta["openai/locale"]`	`_meta["openai/locale"]`	✅
`_meta["openai/userAgent"]`	`_meta["openai/userAgent"]`	✅
`_meta["openai/userLocation"]`	`_meta["openai/userLocation"]`	✅
`_meta["openai/subject"]`	—	❌

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-31