Ajouter des widgets d’interface utilisateur interactifs aux agents déclaratifs

Vous pouvez ajouter des widgets d’interface utilisateur interactifs à vos agents déclaratifs en ajoutant une action basée sur le serveur MCP (Model Context Protocol) à votre agent et en étendant les outils MCP utilisés par l’agent pour inclure l’interface utilisateur. Microsoft 365 Copilot prend en charge les widgets d’interface utilisateur créés à l’aide des méthodes suivantes.

• Applications MCP : extension de MCP qui permet aux serveurs MCP de fournir des interfaces utilisateur interactives aux hôtes.
• Kit de développement logiciel (SDK) OpenAI Apps : outils permettant de créer des applications ChatGPT basées sur la norme MCP Apps avec des fonctionnalités ChatGPT supplémentaires.

Pour obtenir des exemples de plug-ins de serveur MCP, consultez Exemples d’interface utilisateur interactive mcp pour Microsoft 365 Copilot sur GitHub.

Pour plus d’informations sur les fonctionnalités des applications MCP ou du SDK OpenAI Apps prises en charge, consultez Fonctionnalités prises en charge.

Configuration requise

• Conditions requises spécifiées dans Conditions requises pour les options d’extensibilité Copilot
• Un serveur MCP distant qui fournit des widgets d’interface utilisateur ou que vous pouvez modifier pour implémenter des widgets d’interface utilisateur
• Outil permettant d’afficher les réponses du serveur MCP, comme l’inspecteur MCP
• Visual Studio Code
• Microsoft 365 Agents Toolkit (version 6.6.1 ou ultérieure)

Configuration requise du serveur MCP

• Authentification : OAuth 2.1 et Microsoft Entra l’authentification unique (SSO) sont prises en charge. L’authentification anonyme est prise en charge à des fins de développement. Pour plus d’informations sur l’authentification, consultez Configurer l’authentification pour les plug-ins d’API dans les agents.
• URL autorisées : les URL suivantes doivent être autorisées par votre serveur MCP et votre fournisseur d’identité.
  • URL de l’hôte du widget pour CORS - Copilot affiche l’interface utilisateur du widget sous un hôte propre au serveur MCP avec l’URL suivante : {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, où {hashed-mcp-domain} est le hachage SHA-256 du domaine de votre serveur MCP. Vous pouvez utiliser le générateur d’URL de l’hôte de widget pour générer l’URL de l’hôte en fonction de l’URL de votre serveur MCP.
  • URI de redirection OAuth 2.1 :
    • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect pour Copilot
    • https://vscode.dev/redirectpour Visual Studio Code extraire des outils à l’aide du Kit de ressources Agents
  • URI de redirection de l’authentification unique Microsoft Entra :
    • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect pour Copilot
    • Visual Studio Code ne prend actuellement pas en charge l’authentification unique pour la récupération des outils
• Widgets d’interface utilisateur : les widgets d’interface utilisateur doivent être implémentés en fonction de la configuration requise pour les applications MCP ou le Kit de développement logiciel (SDK) OpenAI Apps.

Meilleures pratiques

Conception de l’expérience utilisateur

Pour plus d’informations sur les meilleures pratiques en matière de conception d’expérience utilisateur, consultez Instructions relatives à l’expérience utilisateur pour les widgets d’interface utilisateur interactifs dans les agents déclaratifs.

Vérifier la disponibilité de l’API

Toutes les window.openai.* API ne sont pas disponibles sur chaque plateforme ou hôte. Les API qui ne sont pas prises en charge sont undefined. Toujours case activée disponibilité de l’API et fournissez un secours si l’API n’est pas disponible.

Exemples

Ce modèle simple évite les erreurs d’exécution en vérifiant avant d’appeler l’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.
}

Dans cet exemple, un bouton permettant de passer en mode plein écran est affiché uniquement si l’hôte prend en charge l’API requestDisplayMode .

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>
  );
}

Votre widget peut également case activée disponibilité de toutes les API qu’il utilise au démarrage et activer/désactiver les fonctionnalités en conséquence.

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
}

Créer un agent déclaratif

1. Ouvrez Visual Studio Code et sélectionnez l’icône Microsoft 365 Agents Toolkit dans la barre d’activités de gauche.

2. Sélectionnez Créer un agent/une application dans le volet Office Agents Toolkit.

   

3. Sélectionnez Agent déclaratif.

4. Sélectionnez Ajouter une action, puis Sélectionnez Démarrer avec un serveur MCP. Si vous y êtes invité, choisissez Serveur MCP distant.

5. Entrez l’URL de votre serveur MCP.

6. Choisissez un emplacement pour le projet d’agent.

7. Entrez un nom pour l’agent.

Lorsque vous effectuez ces étapes, Agents Toolkit génère les fichiers requis pour l’agent et ouvre une nouvelle fenêtre Visual Studio Code avec le projet d’agent chargé.

Mettre à jour et charger une version test de l’agent

1. Ouvrez le fichier .vscode/mcp.json . Sélectionnez le bouton Démarrer dans l’éditeur de fichiers.

2. Sélectionnez l’action ATK : Récupérer à partir de MCP dans l’éditeur de fichiers, puis sélectionnez ai-plugin.json.

   

3. Sélectionnez les outils que l’agent doit utiliser, puis sélectionnez OK. Veillez à sélectionner au moins un outil qui a un widget d’interface utilisateur.

4. Sélectionnez le type d’authentification applicable.

   

   Importante

   Si votre serveur MCP est en développement et n’implémente pas l’authentification, cette étape est ignorée. Vous devez ajouter manuellement l’authentification à votre manifeste une fois que vous avez ajouté l’authentification à votre serveur.

5. Sélectionnez l’icône Microsoft 365 Agents Toolkit dans la barre d’activités de gauche.

6. Dans le volet Comptes , sélectionnez Se connecter à Microsoft 365. (Si vous êtes déjà connecté, passez à l’étape suivante).

7. Vérifiez que le chargement d’application personnalisé activé et l’accès Copilot activé s’affichent sous votre compte Microsoft 365. Si ce n’est pas le cas, case activée avec votre administrateur organization. Pour plus d’informations, consultez Configuration requise pour les options d’extensibilité Copilot.

8. Dans le volet Cycle de vie , sélectionnez Provisionner.

9. Si vous y êtes invité, ajoutez vos détails d’authentification.

10. Attendez que le kit de ressources signale qu’il termine l’approvisionnement.

Tester l’agent

1. Ouvrez votre navigateur, puis accédez à https://m365.cloud.microsoft/chat.
2. Sélectionnez votre agent dans la barre latérale gauche. Si vous ne voyez pas votre agent, sélectionnez Tous les agents.
3. Demandez à l’agent de faire quelque chose qui appelle votre serveur MCP.
4. Autorisez l’agent à se connecter au serveur MCP lorsque vous y êtes invité.
5. L’agent restitue le widget d’interface utilisateur.

Fonctionnalités prises en charge

Microsoft 365 Copilot prend en charge les fonctionnalités suivantes.

Pont de composants

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
window.openai.toolInput	app.ontoolinput	✅
window.openai.toolOutput	app.ontoolresult	✅
window.openai.toolResponseMetadata	app.ontoolresult → params._meta	✅
window.openai.widgetState	—	✅
window.openai.setWidgetState(state)	Non disponible directement. Utiliser d’autres mécanismes, notamment 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 })	✅ (plein écran uniquement)
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()	✅

Champs de _meta descripteur d’outil

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
_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"]	—	❌

Annotations de descripteur d’outil

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
readOnlyHint	readOnlyHint	✅
destructiveHint	destructiveHint	❌
openWorldHint	openWorldHint	❌
idempotentHint	idempotentHint	❌

Champs de _meta de ressource de composant

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
_meta["openai/widgetDescription"]	—	❌
_meta["openai/widgetPrefersBorder"]	_meta.ui.prefersBorder	❌
_meta["openai/widgetCSP"]	_meta.ui.csp	✅
_meta["openai/widgetDomain"]	_meta.ui.domain	❌
—	_meta.ui.permissions	❌

Propriétés dans l’objet CSP

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
connect_domains	connectDomains	✅
resource_domains	resourceDomains	✅
frame_domains	frameDomains	❌
redirect_domains	—	❌
—	baseUriDomains	❌

Résultats de l’outil fourni par l’hôte _meta champs

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
_meta["openai/widgetSessionId"]	—	❌

Champs _meta fournis par le client

Kit de développement logiciel (SDK) OpenAI Apps	Applications MCP équivalentes	Pris en charge ?
_meta["openai/locale"]	_meta["openai/locale"]	✅
_meta["openai/userAgent"]	_meta["openai/userAgent"]	✅
_meta["openai/userLocation"]	_meta["openai/userLocation"]	✅
_meta["openai/subject"]	—	❌

Contenu connexe

• Créer des plug-ins à partir d’un serveur MCP pour Microsoft 365 Copilot
• Instructions relatives à l’expérience utilisateur pour les widgets d’interface utilisateur interactifs dans les agents déclaratifs
• Vue d’ensemble des applications MCP
• Kit de développement logiciel (SDK) OpenAI Apps
• Exemples d’interface utilisateur interactive mcp pour Microsoft 365 Copilot