Adicionar widgets de IU interativos a agentes declarativos

Pode adicionar widgets de IU interativos aos seus agentes declarativos ao adicionar uma ação baseada no servidor do Protocolo de Contexto de Modelo (MCP) ao agente e ao expandir as ferramentas MCP utilizadas pelo agente para incluir a IU. Microsoft 365 Copilot suporta widgets de IU criados com os seguintes métodos.

Aplicações MCP – uma extensão do MCP que permite aos servidores MCP fornecer interfaces de utilizador interativas a anfitriões.
SDK de Aplicações OpenAI - ferramentas para criar aplicações ChatGPT com base no padrão aplicações MCP com funcionalidades de ChatGPT adicionais.

Por exemplo, plug-ins de servidor MCP, veja Exemplos de IU interativos baseados em MCP para Microsoft 365 Copilot no GitHub.

Para obter detalhes sobre quais as funcionalidades do SDK de Aplicações MCP ou OpenAI Apps suportadas, veja Capacidades suportadas.

Pré-requisitos

Requisitos especificados em Requisitos para opções de extensibilidade do Copilot
Um servidor MCP remoto que fornece widgets de IU ou que pode modificar para implementar widgets de IU
Uma ferramenta para ver as respostas do servidor MCP, como o Inspetor mcP
Visual Studio Code
Toolkit de Agentes do Microsoft 365 (versão 6.6.1 ou posterior)

Requisitos do servidor MCP

Autenticação – OAuth 2.1 e Microsoft Entra início de sessão único (SSO) são suportados. A autenticação anónima é suportada para fins de desenvolvimento. Para obter detalhes sobre a autenticação, veja Configurar a autenticação para plug-ins de API em agentes.
URLs permitidos – os seguintes URLs devem ser permitidos pelo servidor MCP e pelo fornecedor de identidade.
- URL do anfitrião widget para CORS – Copilot compõe a IU do widget num anfitrião específico do servidor MCP com o seguinte URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, em {hashed-mcp-domain} que é o hash SHA-256 do domínio do servidor MCP. Pode utilizar o Gerador de URLs do Anfitrião widget para gerar o URL do anfitrião com base no URL do servidor MCP.
- URIs de redirecionamento do OAuth 2.1:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect para Copilot
  - https://vscode.dev/redirectpara Visual Studio Code obter ferramentas com o Toolkit de Agentes
- Microsoft Entra URIs de redirecionamento do SSO:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect para Copilot
  - Visual Studio Code não suporta atualmente o SSO para obter ferramentas
Widgets de IU – os widgets da IU têm de ser implementados de acordo com os requisitos do SDK aplicações MCP ou OpenAI Apps.

Práticas recomendadas

Design da experiência de utilizador

Para obter detalhes sobre as melhores práticas de conceção de UX, veja Diretrizes de experiência do utilizador para widgets de IU interativos em agentes declarativos.

Verificar a disponibilidade da API

Nem todas as window.openai.* APIs estão disponíveis em todas as plataformas ou anfitriões. As APIs que não são suportadas são undefined. Sempre marcar disponibilidade da API e fornecer uma contingência se a API estiver indisponível.

Exemplos

Este padrão simples evita erros de runtime ao verificar antes de chamar a 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.
}

Neste exemplo, um botão para entrar no modo de ecrã inteiro só é composto se o anfitrião suportar a 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>
  );
}

Em alternativa, o widget pode marcar disponibilidade de todas as APIs que utiliza no arranque e ativar/desativar funcionalidades em conformidade.

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
}

Criar um agente declarativo

Abra Visual Studio Code e selecione o ícone do Toolkit de Agentes do Microsoft 365 na Barra de Atividade do lado esquerdo.
Selecione Criar um Novo Agente/Aplicação no painel de tarefas Toolkit agentes.
Selecione Agente Declarativo.
Selecione Adicionar uma Ação e, em seguida, selecione Iniciar com um Servidor MCP. Se lhe for pedido, selecione Servidor MCP remoto.
Introduza URL no servidor MCP.
Escolha uma localização para o projeto do agente.
Introduza um nome para o agente.

Quando concluir estes passos, o Toolkit de Agentes gera os ficheiros necessários para o agente e abre uma nova janela de Visual Studio Code com o projeto do agente carregado.

Atualizar e fazer sideload do agente

Abra o ficheiro .vscode/mcp.json . Selecione o botão Iniciar no editor de ficheiros.
Selecione o botão ATK: Obter ação do MCP no editor de ficheiros e, em seguida, selecione ai-plugin.json.
Selecione as ferramentas para o agente utilizar e selecione OK. Certifique-se de que seleciona, pelo menos, uma ferramenta que tem um widget de IU.
Selecione o tipo de autenticação aplicável.

Importante

Se o servidor MCP estiver em desenvolvimento e não implementar a autenticação, este passo será ignorado. Tem de adicionar manualmente a autenticação ao seu manifesto depois de adicionar a autenticação ao servidor.
Selecione o ícone Toolkit de Agentes do Microsoft 365 na Barra de Atividade do lado esquerdo.
No painel Contas , selecione Iniciar sessão no Microsoft 365. (Se já tiver sessão iniciada, avance para o passo seguinte).
Confirme que o Carregamento de Aplicações Personalizadas Ativado e o Acesso Copilot Ativado são apresentados na sua conta do Microsoft 365. Caso contrário, marcar junto do administrador da sua organização. Veja Requisitos para opções de extensibilidade do Copilot para obter detalhes.
No painel Ciclo de Vida , selecione Aprovisionar.
Se lhe for pedido, adicione os detalhes de autenticação.
Aguarde que o toolkit reporte que termina o aprovisionamento.

Testar o agente

Abra o navegador e vá para https://m365.cloud.microsoft/chat.
Selecione o agente na barra lateral esquerda. Se não vir o agente, selecione Todos os agentes.
Peça ao agente para fazer algo que invoque o servidor MCP.
Quando lhe for pedido, permita que o agente se ligue ao servidor MCP.
O agente compõe o widget da IU.

Recursos compatíveis

Microsoft 365 Copilot suporta as seguintes capacidades.

Bridge de componentes

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`window.openai.toolInput`	`app.ontoolinput`	✅
`window.openai.toolOutput`	`app.ontoolresult`	✅
`window.openai.toolResponseMetadata`	`app.ontoolresult` → `params._meta`	✅
`window.openai.widgetState`	—	✅
`window.openai.setWidgetState(state)`	Não está disponível diretamente. Utilizar mecanismos alternativos, incluindo `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 })`	✅ (apenas em ecrã inteiro)
`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()`	✅

Descrição de ferramentas _meta campos

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`_meta["openai/outputTemplate"]`	`_meta.ui.resourceUri`	✅
`_meta["openai/widgetAccessible"]`	`_meta.ui.visibility` (cadeia[])	❌
`_meta["openai/visibility"]`	`_meta.ui.visibility` (cadeia[])	✅
`_meta["openai/toolInvocation/invoking"]`	—	❌
`_meta["openai/toolInvocation/invoked"]`	—	❌
`_meta["openai/fileParams"]`	—	❌
`_meta["securitySchemes"]`	—	❌

Anotações do descritor de ferramentas

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`readOnlyHint`	`readOnlyHint`	✅
`destructiveHint`	`destructiveHint`	❌
`openWorldHint`	`openWorldHint`	❌
`idempotentHint`	`idempotentHint`	❌

Campos de _meta de recursos do componente

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`_meta["openai/widgetDescription"]`	—	❌
`_meta["openai/widgetPrefersBorder"]`	`_meta.ui.prefersBorder`	❌
`_meta["openai/widgetCSP"]`	`_meta.ui.csp`	✅
`_meta["openai/widgetDomain"]`	`_meta.ui.domain`	❌
—	`_meta.ui.permissions`	❌

Propriedades no objeto CSP

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`connect_domains`	`connectDomains`	✅
`resource_domains`	`resourceDomains`	✅
`frame_domains`	`frameDomains`	❌
`redirect_domains`	—	❌
—	`baseUriDomains`	❌

Resultados da ferramenta fornecida pelo anfitrião _meta campos

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`_meta["openai/widgetSessionId"]`	—	❌

Campos de _meta fornecidos pelo cliente

SDK de Aplicações OpenAI	Equivalente a Aplicações MCP	Com suporte?
`_meta["openai/locale"]`	`_meta["openai/locale"]`	✅
`_meta["openai/userAgent"]`	`_meta["openai/userAgent"]`	✅
`_meta["openai/userLocation"]`	`_meta["openai/userLocation"]`	✅
`_meta["openai/subject"]`	—	❌

Comentários

Esta página foi útil?

Last updated on 2026-03-31