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 o SDK de Aplicações OpenAI.

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

Observação

O suporte para Aplicações MCP estará disponível em breve.

Para obter detalhes sobre as capacidades do SDK de Aplicações OpenAI 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

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

1. Abra Visual Studio Code e selecione o ícone do Toolkit de Agentes do Microsoft 365 na Barra de Atividade do lado esquerdo.

2. Selecione Criar um Novo Agente/Aplicação no painel de tarefas Toolkit agentes.

   

3. Selecione Agente Declarativo.

4. Selecione Adicionar uma Ação e, em seguida, selecione Iniciar com um Servidor MCP. Se lhe for pedido, selecione Servidor MCP remoto.

5. Introduza URL no servidor MCP.

6. Escolha uma localização para o projeto do agente.

7. 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

1. Abra o ficheiro .vscode/mcp.json . Selecione o botão Iniciar no editor de ficheiros.

2. Selecione o botão ATK: Obter ação do MCP no editor de ficheiros e, em seguida, selecione ai-plugin.json.

   

3. 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.

4. 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.

5. Selecione o ícone Toolkit de Agentes do Microsoft 365 na Barra de Atividade do lado esquerdo.

6. No painel Contas , selecione Iniciar sessão no Microsoft 365. (Se já tiver sessão iniciada, avance para o passo seguinte).

7. 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.

8. No painel Ciclo de Vida , selecione Aprovisionar.

9. Se lhe for pedido, adicione os detalhes de autenticação.

10. Aguarde que o toolkit reporte que termina o aprovisionamento.

Testar o agente

1. Abra o navegador e vá para https://m365.cloud.microsoft/chat.
2. Selecione o agente na barra lateral esquerda. Se não vir o agente, selecione Todos os agentes.
3. Peça ao agente para fazer algo que invoque o servidor MCP.
4. Quando lhe for pedido, permita que o agente se ligue ao servidor MCP.
5. 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	Com suporte?
window.openai.toolInput	✅
window.openai.toolOutput	✅
window.openai.toolResponseMetadata	✅
window.openai.widgetState	✅
window.openai.setWidgetState(state)	✅
window.openai.callTool(name, args)	✅
window.openai.sendFollowUpMessage({ prompt })	✅
window.openai.uploadFile(file)	❌
window.openai.getFileDownloadUrl({ fileId })	❌
window.openai.requestDisplayMode(...)	✅ (apenas em ecrã inteiro)
window.openai.requestModal(...)	❌
window.openai.notifyIntrinsicHeight(...)	✅
window.openai.openExternal({ href })	✅
window.openai.setOpenInAppUrl({ href })	✅
window.openai.theme	✅
window.openai.displayMode	✅
window.openai.maxHeight	✅
window.openai.safeArea	✅
window.openai.view	✅
window.openai.userAgent	✅
window.openai.locale	✅

Descrição de ferramentas _meta campos

SDK de Aplicações OpenAI	Com suporte?
_meta["openai/outputTemplate"]	✅
_meta["openai/widgetAccessible"]	❌
_meta["openai/visibility"]	✅
_meta["openai/toolInvocation/invoking"]	❌
_meta["openai/toolInvocation/invoked"]	❌
_meta["openai/fileParams"]	❌
_meta["securitySchemes"]	❌

Anotações do descritor de ferramentas

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

Campos de _meta de recursos do componente

SDK de Aplicações OpenAI	Com suporte?
_meta["openai/widgetDescription"]	❌
_meta["openai/widgetPrefersBorder"]	❌
_meta["openai/widgetCSP"]	✅
_meta["openai/widgetDomain"]	❌

Propriedades no objeto CSP

SDK de Aplicações OpenAI	Com suporte?
connect_domains	✅
resource_domains	✅
frame_domains	❌
redirect_domains	❌

Resultados da ferramenta fornecida pelo anfitrião _meta campos

SDK de Aplicações OpenAI	Com suporte?
_meta["openai/widgetSessionId"]	❌

Campos de _meta fornecidos pelo cliente

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

Conteúdo relacionado

• Criar plug-ins a partir de um servidor MCP para Microsoft 365 Copilot
• Diretrizes de experiência do utilizador para widgets interativos de IU em agentes declarativos
• SDK de Aplicações OpenAI
• Exemplos de IU interativa baseados em MCP para Microsoft 365 Copilot